diff --git a/src/mmtk.rs b/src/mmtk.rs index 7e665c212e..ea7dbddeca 100644 --- a/src/mmtk.rs +++ b/src/mmtk.rs @@ -240,11 +240,22 @@ impl MMTK { /// Prepare an MMTk instance for calling the `fork()` system call. /// - /// This function makes all MMTk threads (currently including GC worker threads) save their - /// contexts and stop. A subsequent call to `MMTK::after_fork()` will re-spawn the threads - /// using the saved contexts. + /// The `fork()` system call is available on Linux and some UNIX variants. When `fork()` is + /// called when the process has multiple threads, it will only duplicate the current thread + /// into the child process, and the child process can only call async-signal-safe functions, + /// notably `exec()`. For VMs that that use multi-process concurrency, it is imperative that + /// when calling `fork()`, only one thread may exist in the process. /// - /// This function returns when all MMTK threads stopped. + /// This function helps VMs that use `fork()` for multi-process concurrency. It makes all MMTk + /// threads (currently including GC worker threads) save their contexts and stop. This + /// function returns when all MMTK threads stopped. A subsequent call to `MMTK::after_fork()` + /// will re-spawn the threads using the saved contexts. + /// + /// To use thie function, the VM needs to implement [`crate::vm::Collection::spawn_gc_thread`] + /// so that the native thread exits after the entry-point functions of GC threads, such as + /// [`crate::memory_manager::start_worker`], exits. Its returned + /// [`GCThreadJoinHandle`](crate::vm::gc_thread::GCThreadJoinHandle) must wait for the + /// underlying native thread to exit. pub fn prepare_to_fork(&'static self) { assert!( self.state.is_initialized(),