implement mutator builder (#1287)

https://mmtk.zulipchat.com/#narrow/channel/262673-mmtk-core/topic/create.20plan.2Fmutator/near/504996362
Introducing `MutatorBuilder` to simplify customising `Mutator`,
adding/removing fields of a certain plan's `Mutator` no longer affects
other plan as `MutatorBuilder` provides default values for `Mutator`

Author: tianleq

src/plan/generational/copying/mutator.rs

@@ -5,9 +5,9 @@ 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::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::Allocators;
 use crate::util::alloc::BumpAllocator;
 use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
@@ -40,13 +40,10 @@ pub fn create_gencopy_mutator<VM: VMBinding>(
         release_func: &gencopy_mutator_release,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(ObjectBarrier::new(GenObjectBarrierSemantics::new(
-            mmtk, gencopy,
-        ))),
-        mutator_tls,
-        config,
-        plan: gencopy,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder
+        .barrier(Box::new(ObjectBarrier::new(
+            GenObjectBarrierSemantics::new(mmtk, gencopy),
+        )))
+        .build()
 }

src/plan/generational/immix/mutator.rs

@@ -5,9 +5,9 @@ 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::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::Allocators;
 use crate::util::alloc::BumpAllocator;
 use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
@@ -40,13 +40,10 @@ pub fn create_genimmix_mutator<VM: VMBinding>(
         release_func: &genimmix_mutator_release,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(ObjectBarrier::new(GenObjectBarrierSemantics::new(
-            mmtk, genimmix,
-        ))),
-        mutator_tls,
-        config,
-        plan: genimmix,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder
+        .barrier(Box::new(ObjectBarrier::new(
+            GenObjectBarrierSemantics::new(mmtk, genimmix),
+        )))
+        .build()
 }

src/plan/immix/mutator.rs

@@ -3,17 +3,15 @@ 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::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::ReservedAllocators;
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::{AllocatorSelector, Allocators};
+use crate::util::alloc::allocators::AllocatorSelector;
 use crate::util::alloc::ImmixAllocator;
+use crate::util::opaque_pointer::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
 use crate::MMTK;
-use crate::{
-    plan::barriers::NoBarrier,
-    util::opaque_pointer::{VMMutatorThread, VMWorkerThread},
-};
 use enum_map::EnumMap;
 
 pub fn immix_mutator_release<VM: VMBinding>(mutator: &mut Mutator<VM>, _tls: VMWorkerThread) {
@@ -56,11 +54,6 @@ pub fn create_immix_mutator<VM: VMBinding>(
         release_func: &immix_mutator_release,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(NoBarrier),
-        mutator_tls,
-        config,
-        plan: immix,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder.build()
 }

src/plan/markcompact/mutator.rs

@@ -1,13 +1,13 @@
 use super::MarkCompact;
-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::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::ReservedAllocators;
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::{AllocatorSelector, Allocators};
+use crate::util::alloc::allocators::AllocatorSelector;
 use crate::util::alloc::MarkCompactAllocator;
 use crate::util::opaque_pointer::*;
 use crate::vm::VMBinding;
@@ -42,14 +42,8 @@ pub fn create_markcompact_mutator<VM: VMBinding>(
         prepare_func: &unreachable_prepare_func,
         release_func: &markcompact_mutator_release,
     };
-
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(NoBarrier),
-        mutator_tls,
-        config,
-        plan: markcompact,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder.build()
 }
 
 pub fn markcompact_mutator_release<VM: VMBinding>(

src/plan/marksweep/mutator.rs

@@ -1,13 +1,13 @@
-use crate::plan::barriers::NoBarrier;
 use crate::plan::marksweep::MarkSweep;
 use crate::plan::mutator_context::create_allocator_mapping;
 use crate::plan::mutator_context::Mutator;
+use crate::plan::mutator_context::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::ReservedAllocators;
 use crate::plan::mutator_context::SpaceMapping;
 use crate::plan::AllocationSemantics;
 use crate::plan::Plan;
-use crate::util::alloc::allocators::{AllocatorSelector, Allocators};
+use crate::util::alloc::allocators::AllocatorSelector;
 use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
 use crate::MMTK;
@@ -121,11 +121,6 @@ pub fn create_ms_mutator<VM: VMBinding>(
         release_func: &ms_mutator_release,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(NoBarrier),
-        mutator_tls,
-        config,
-        plan: mmtk.get_plan(),
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder.build()
 }

src/plan/mutator_context.rs

@@ -9,9 +9,12 @@ use crate::util::alloc::Allocator;
 use crate::util::{Address, ObjectReference};
 use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
+use crate::MMTK;
 
 use enum_map::EnumMap;
 
+use super::barriers::NoBarrier;
+
 pub(crate) type SpaceMapping<VM> = Vec<(AllocatorSelector, &'static dyn Space<VM>)>;
 
 /// A place-holder implementation for `MutatorConfig::prepare_func` that should not be called.
@@ -78,6 +81,49 @@ impl<VM: VMBinding> std::fmt::Debug for MutatorConfig<VM> {
     }
 }
 
+/// Used to build a mutator struct
+pub struct MutatorBuilder<VM: VMBinding> {
+    barrier: Box<dyn Barrier<VM>>,
+    /// The mutator thread that is bound with this Mutator struct.
+    mutator_tls: VMMutatorThread,
+    mmtk: &'static MMTK<VM>,
+    config: MutatorConfig<VM>,
+}
+
+impl<VM: VMBinding> MutatorBuilder<VM> {
+    pub fn new(
+        mutator_tls: VMMutatorThread,
+        mmtk: &'static MMTK<VM>,
+        config: MutatorConfig<VM>,
+    ) -> Self {
+        MutatorBuilder {
+            barrier: Box::new(NoBarrier),
+            mutator_tls,
+            mmtk,
+            config,
+        }
+    }
+
+    pub fn barrier(mut self, barrier: Box<dyn Barrier<VM>>) -> Self {
+        self.barrier = barrier;
+        self
+    }
+
+    pub fn build(self) -> Mutator<VM> {
+        Mutator {
+            allocators: Allocators::<VM>::new(
+                self.mutator_tls,
+                self.mmtk,
+                &self.config.space_mapping,
+            ),
+            barrier: self.barrier,
+            mutator_tls: self.mutator_tls,
+            plan: self.mmtk.get_plan(),
+            config: self.config,
+        }
+    }
+}
+
 /// A mutator is a per-thread data structure that manages allocations and barriers. It is usually highly coupled with the language VM.
 /// It is recommended for MMTk users 1) to have a mutator struct of the same layout in the thread local storage that can be accessed efficiently,
 /// and 2) to implement fastpath allocation and barriers for the mutator in the VM side.

src/plan/nogc/mutator.rs

@@ -1,14 +1,14 @@
-use crate::plan::barriers::NoBarrier;
 use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::unreachable_release_func;
 use crate::plan::mutator_context::Mutator;
+use crate::plan::mutator_context::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::{
     create_allocator_mapping, create_space_mapping, ReservedAllocators,
 };
 use crate::plan::nogc::NoGC;
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::{AllocatorSelector, Allocators};
+use crate::util::alloc::allocators::AllocatorSelector;
 use crate::util::VMMutatorThread;
 use crate::vm::VMBinding;
 use crate::MMTK;
@@ -56,11 +56,6 @@ pub fn create_nogc_mutator<VM: VMBinding>(
         release_func: &unreachable_release_func,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(NoBarrier),
-        mutator_tls,
-        config,
-        plan,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder.build()
 }

src/plan/pageprotect/mutator.rs

@@ -2,15 +2,16 @@ use super::PageProtect;
 use crate::plan::mutator_context::no_op_release_func;
 use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::Mutator;
+use crate::plan::mutator_context::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::{
     create_allocator_mapping, create_space_mapping, ReservedAllocators,
 };
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::{AllocatorSelector, Allocators};
+use crate::util::alloc::allocators::AllocatorSelector;
+use crate::util::opaque_pointer::VMMutatorThread;
 use crate::vm::VMBinding;
 use crate::MMTK;
-use crate::{plan::barriers::NoBarrier, util::opaque_pointer::VMMutatorThread};
 use enum_map::EnumMap;
 
 const RESERVED_ALLOCATORS: ReservedAllocators = ReservedAllocators {
@@ -44,11 +45,6 @@ pub fn create_pp_mutator<VM: VMBinding>(
         release_func: &no_op_release_func,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(NoBarrier),
-        mutator_tls,
-        config,
-        plan: page,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder.build()
 }

src/plan/semispace/mutator.rs

@@ -1,13 +1,13 @@
 use super::SemiSpace;
-use crate::plan::barriers::NoBarrier;
 use crate::plan::mutator_context::unreachable_prepare_func;
 use crate::plan::mutator_context::Mutator;
+use crate::plan::mutator_context::MutatorBuilder;
 use crate::plan::mutator_context::MutatorConfig;
 use crate::plan::mutator_context::{
     create_allocator_mapping, create_space_mapping, ReservedAllocators,
 };
 use crate::plan::AllocationSemantics;
-use crate::util::alloc::allocators::{AllocatorSelector, Allocators};
+use crate::util::alloc::allocators::AllocatorSelector;
 use crate::util::alloc::BumpAllocator;
 use crate::util::{VMMutatorThread, VMWorkerThread};
 use crate::vm::VMBinding;
@@ -61,11 +61,6 @@ pub fn create_ss_mutator<VM: VMBinding>(
         release_func: &ss_mutator_release,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(NoBarrier),
-        mutator_tls,
-        config,
-        plan: ss,
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder.build()
 }

src/plan/sticky/immix/mutator.rs

@@ -1,9 +1,10 @@
 use crate::plan::barriers::ObjectBarrier;
 use crate::plan::generational::barrier::GenObjectBarrierSemantics;
 use crate::plan::immix;
-use crate::plan::mutator_context::{create_space_mapping, unreachable_prepare_func, MutatorConfig};
+use crate::plan::mutator_context::{
+    create_space_mapping, unreachable_prepare_func, MutatorBuilder, MutatorConfig,
+};
 use crate::plan::sticky::immix::global::StickyImmix;
-use crate::util::alloc::allocators::Allocators;
 use crate::util::alloc::AllocatorSelector;
 use crate::util::opaque_pointer::VMWorkerThread;
 use crate::util::VMMutatorThread;
@@ -33,14 +34,10 @@ pub fn create_stickyimmix_mutator<VM: VMBinding>(
         release_func: &stickyimmix_mutator_release,
     };
 
-    Mutator {
-        allocators: Allocators::<VM>::new(mutator_tls, mmtk, &config.space_mapping),
-        barrier: Box::new(ObjectBarrier::new(GenObjectBarrierSemantics::new(
-            mmtk,
-            stickyimmix,
-        ))),
-        mutator_tls,
-        config,
-        plan: mmtk.get_plan(),
-    }
+    let builder = MutatorBuilder::new(mutator_tls, mmtk, config);
+    builder
+        .barrier(Box::new(ObjectBarrier::new(
+            GenObjectBarrierSemantics::new(mmtk, stickyimmix),
+        )))
+        .build()
 }