Disabling PrepareMutator from PlanConstraints (#964)

Some plans do nothing when preparing mutators. We add a boolean flag so
that we do not create the PrepareMutator work packets in the first
place.

We also remove the function that prepares Mutator for Immix. It is
unnecessary to reset the ImmixAllocator of a mutator when preparing
mutator because the mutator's ImmixAllocator is not used during GC. When
a GC worker defragments the heap and promotes young objects, it uses the
ImmixAllocator instances in ImmixCopyContext or ImmixHybridCopyContext.

Fixes: #959

Author: wks

docs/userguide/src/tutorial/mygc/ss/collection.md

@@ -104,13 +104,19 @@ the new `tospace`.
 
 ### Prepare mutator
 
-Going back to `mutator.rs`, create a new function called 
-`mygc_mutator_prepare(_mutator: &mut Mutator <MyGC<VM>>, _tls: OpaquePointer,)`. 
-This function will be called at the preparation stage of a collection 
-(at the start of a collection) for each mutator. Its body can stay empty, as 
-there aren't any preparation steps for the mutator in this GC.
-In `create_mygc_mutator()`, find the field `prep_func` and change it from
-`mygc_mutator_noop()` to `mygc_mutator_prepare()`.
+Going back to `mutator.rs`, create a new function called
+`mygc_mutator_prepare<VM: VMBinding>(_mutator: &mut Mutator<VM>, _tls: VMWorkerThread)`.
+This function will be called at the preparation stage of a collection (at the start of a
+collection) for each mutator. Its body can stay empty, as there aren't any preparation steps for
+the mutator in this GC.  In `create_mygc_mutator()`, find the field `prepare_func` and change it
+from `&unreachable_prepare_func` to `&mygc_mutator_prepare`.
+
+> 💡 Hint: If your plan does nothing when preparing mutators, there is an optimization you can do.
+You may set the plan constraints field `PlanConstraints::needs_prepare_mutator` to `false` so that
+the `PrepareMutator` work packets which call `prepare_func` will not be created in the first place.
+This optimization is helpful for VMs that run with a large number of mutator threads.  If you do
+this optimization, you may also leave the `MutatorConfig::prepare_func` field as
+`&unreachable_prepare_func` to indicate it should not be called.
 
 ## Release
 
@@ -131,24 +137,18 @@ routines for the common plan spaces and the fromspace.
 
 ### Release in mutator
 
-Go back to `mutator.rs`. In `create_mygc_mutator()`, replace 
-`mygc_mutator_noop()` in the `release_func` field with `mygc_mutator_release()`.
-Leave the `release()` function in the `CopyContext` empty. There are no 
-release steps for `CopyContext` in this collector.
-
-Create a new function called `mygc_mutator_release()` that takes the same 
-inputs as the `prepare()` function above. This function will be called at the 
-release stage of a collection (at the end of a collection) for each mutator. 
-It rebinds the allocator for the `Default` allocation semantics to the new 
-tospace. When the mutator threads resume, any new allocations for `Default` 
-will then go to the new tospace.
- 
+Go back to `mutator.rs`.  Create a new function called `mygc_mutator_release()` that takes the same
+inputs as the `mygc_mutator_prepare()` function above.
+
 ```rust
 {{#include ../../code/mygc_semispace/mutator.rs:release}}
 ```
 
-Delete `mygc_mutator_noop()`. It was a placeholder for the prepare and 
-release functions that you have now added, so it is now dead code.
+Then go to `create_mygc_mutator()`, replace `&unreachable_release_func` in the `release_func` field
+with `&mygc_mutator_release`.  This function will be called at the release stage of a collection
+(at the end of a collection) for each mutator.  It rebinds the allocator for the `Default`
+allocation semantics to the new tospace. When the mutator threads resume, any new allocations for
+`Default` will then go to the new tospace.
 
 ## ProcessEdgesWork for MyGC
 

src/plan/generational/copying/mutator.rs

@@ -3,6 +3,7 @@ use super::GenCopy;
 use crate::plan::barriers::ObjectBarrier;
 use crate::plan::generational::barrier::GenObjectBarrierSemantics;
 use crate::plan::generational::create_gen_space_mapping;
+use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::Mutator;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::AllocationSemantics;
@@ -12,10 +13,6 @@ use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
 use crate::MMTK;
 
-pub fn gencopy_mutator_prepare<VM: VMBinding>(_mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {
-    // Do nothing
-}
-
 pub fn gencopy_mutator_release<VM: VMBinding>(mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {
     // reset nursery allocator
     let bump_allocator = unsafe {
@@ -39,7 +36,7 @@ pub fn create_gencopy_mutator<VM: VMBinding>(
             mmtk.get_plan(),
             &gencopy.gen.nursery,
         )),
-        prepare_func: &gencopy_mutator_prepare,
+        prepare_func: &unreachable_prepare_func,
         release_func: &gencopy_mutator_release,
     };
 

src/plan/generational/immix/mutator.rs

@@ -3,6 +3,7 @@ use crate::plan::barriers::ObjectBarrier;
 use crate::plan::generational::barrier::GenObjectBarrierSemantics;
 use crate::plan::generational::create_gen_space_mapping;
 use crate::plan::generational::immix::GenImmix;
+use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::Mutator;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::AllocationSemantics;
@@ -12,8 +13,6 @@ use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
 use crate::MMTK;
 
-pub fn genimmix_mutator_prepare<VM: VMBinding>(_mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {}
-
 pub fn genimmix_mutator_release<VM: VMBinding>(mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {
     // reset nursery allocator
     let bump_allocator = unsafe {
@@ -37,7 +36,7 @@ pub fn create_genimmix_mutator<VM: VMBinding>(
             mmtk.get_plan(),
             &genimmix.gen.nursery,
         )),
-        prepare_func: &genimmix_mutator_prepare,
+        prepare_func: &unreachable_prepare_func,
         release_func: &genimmix_mutator_release,
     };
 

src/plan/generational/mod.rs

@@ -55,6 +55,7 @@ pub const GEN_CONSTRAINTS: PlanConstraints = PlanConstraints {
         crate::plan::plan_constraints::MAX_NON_LOS_ALLOC_BYTES_COPYING_PLAN,
         crate::util::options::NURSERY_SIZE,
     ),
+    needs_prepare_mutator: false,
     ..PlanConstraints::default()
 };
 

src/plan/immix/global.rs

@@ -43,6 +43,7 @@ pub const IMMIX_CONSTRAINTS: PlanConstraints = PlanConstraints {
     num_specialized_scans: 1,
     /// Max immix object size is half of a block.
     max_non_los_default_alloc_bytes: crate::policy::immix::MAX_IMMIX_OBJECT_SIZE,
+    needs_prepare_mutator: false,
     ..PlanConstraints::default()
 };
 

src/plan/immix/mutator.rs

@@ -1,6 +1,7 @@
 use super::Immix;
 use crate::plan::mutator_context::create_allocator_mapping;
 use crate::plan::mutator_context::create_space_mapping;
+use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::Mutator;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::ReservedAllocators;
@@ -15,17 +16,6 @@ use crate::{
 };
 use enum_map::EnumMap;
 
-pub fn immix_mutator_prepare<VM: VMBinding>(mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {
-    let immix_allocator = unsafe {
-        mutator
-            .allocators
-            .get_allocator_mut(mutator.config.allocator_mapping[AllocationSemantics::Default])
-    }
-    .downcast_mut::<ImmixAllocator<VM>>()
-    .unwrap();
-    immix_allocator.reset();
-}
-
 pub fn immix_mutator_release<VM: VMBinding>(mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {
     let immix_allocator = unsafe {
         mutator
@@ -62,7 +52,7 @@ pub fn create_immix_mutator<VM: VMBinding>(
             vec.push((AllocatorSelector::Immix(0), &immix.immix_space));
             vec
         }),
-        prepare_func: &immix_mutator_prepare,
+        prepare_func: &unreachable_prepare_func,
         release_func: &immix_mutator_release,
     };
 

src/plan/markcompact/global.rs

@@ -44,6 +44,7 @@ pub const MARKCOMPACT_CONSTRAINTS: PlanConstraints = PlanConstraints {
     needs_forward_after_liveness: true,
     max_non_los_default_alloc_bytes:
         crate::plan::plan_constraints::MAX_NON_LOS_ALLOC_BYTES_COPYING_PLAN,
+    needs_prepare_mutator: false,
     ..PlanConstraints::default()
 };
 

src/plan/markcompact/mutator.rs

@@ -2,6 +2,7 @@ use super::MarkCompact; // Add
 use crate::plan::barriers::NoBarrier;
 use crate::plan::mutator_context::create_allocator_mapping;
 use crate::plan::mutator_context::create_space_mapping;
+use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::Mutator;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::ReservedAllocators;
@@ -38,7 +39,7 @@ pub fn create_markcompact_mutator<VM: VMBinding>(
             vec.push((AllocatorSelector::MarkCompact(0), markcompact.mc_space()));
             vec
         }),
-        prepare_func: &markcompact_mutator_prepare,
+        prepare_func: &unreachable_prepare_func,
         release_func: &markcompact_mutator_release,
     };
 
@@ -51,12 +52,6 @@ pub fn create_markcompact_mutator<VM: VMBinding>(
     }
 }
 
-pub fn markcompact_mutator_prepare<VM: VMBinding>(
-    _mutator: &mut Mutator<VM>,
-    _tls: VMWorkerThread,
-) {
-}
-
 pub fn markcompact_mutator_release<VM: VMBinding>(
     _mutator: &mut Mutator<VM>,
     _tls: VMWorkerThread,

src/plan/marksweep/global.rs

@@ -43,6 +43,8 @@ pub const MS_CONSTRAINTS: PlanConstraints = PlanConstraints {
     num_specialized_scans: 1,
     max_non_los_default_alloc_bytes: MAX_OBJECT_SIZE,
     may_trace_duplicate_edges: true,
+    needs_prepare_mutator: !cfg!(feature = "malloc_mark_sweep")
+        && !cfg!(feature = "eager_sweeping"),
     ..PlanConstraints::default()
 };
 

src/plan/mutator_context.rs

@@ -13,6 +13,28 @@ use enum_map::EnumMap;
 
 pub(crate) type SpaceMapping<VM> = Vec<(AllocatorSelector, &'static dyn Space<VM>)>;
 
+/// A place-holder implementation for `MutatorConfig::prepare_func` that should not be called.
+/// It is the most often used by plans that sets `PlanConstraints::needs_prepare_mutator` to
+/// `false`.  It is also used by `NoGC` because it must not trigger GC.
+pub(crate) fn unreachable_prepare_func<VM: VMBinding>(
+    _mutator: &mut Mutator<VM>,
+    _tls: VMWorkerThread,
+) {
+    unreachable!("`MutatorConfig::prepare_func` must not be called for the current plan.")
+}
+
+/// A place-holder implementation for `MutatorConfig::release_func` that should not be called.
+/// Currently only used by `NoGC`.
+pub(crate) fn unreachable_release_func<VM: VMBinding>(
+    _mutator: &mut Mutator<VM>,
+    _tls: VMWorkerThread,
+) {
+    unreachable!("`MutatorConfig::release_func` must not be called for the current plan.")
+}
+
+/// A place-holder implementation for `MutatorConfig::release_func` that does nothing.
+pub(crate) fn no_op_release_func<VM: VMBinding>(_mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {}
+
 // This struct is part of the Mutator struct.
 // We are trying to make it fixed-sized so that VM bindings can easily define a Mutator type to have the exact same layout as our Mutator struct.
 #[repr(C)]