HasSpaces trait and derive macro

Author: wks

docs/userguide/src/tutorial/code/mygc_semispace/global.rs

@@ -24,11 +24,11 @@ use std::sync::atomic::{AtomicBool, Ordering}; // Add
 // Remove #[allow(unused_imports)].
 // Remove handle_user_collection_request().
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 // Modify
 // ANCHOR: plan_def
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct MyGC<VM: VMBinding> {
     pub hi: AtomicBool,
     #[space]

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

@@ -72,7 +72,7 @@ you can implement object tracing, in this tutorial we use the macros, as it is t
 Make sure you import the macros. We will discuss on what those attributes mean in later sections.
 
 ```rust
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 ```
 
 ### Implement the Plan trait for MyGC
@@ -230,4 +230,4 @@ by the common plan:
 
 With this, you should have the allocation working, but not garbage collection. 
 Try building again. If you run HelloWorld or Fannkunchredux, they should
-work. DaCapo's lusearch should fail, as it requires garbage to be collected. 
+work. DaCapo's lusearch should fail, as it requires garbage to be collected. 

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

@@ -181,7 +181,7 @@ it can use `PlanProcessEdges`.
 
 You can manually provide an implementation of `PlanTraceObject` for `MyGC`. But you can also use the derive macro MMTK provides,
 and the macro will generate an implementation of `PlanTraceObject`:
-* add `#[derive(PlanTraceObject)]` for `MyGC` (import the macro properly: `use mmtk_macros::PlanTraceObject`)
+* add `#[derive(HasSpaces, PlanTraceObject)]` for `MyGC` (import the macro properly: `use mmtk_macros::PlanTraceObject`)
 * add `#[space]
 #[copy_semantics(CopySemantics::Default)]` to both copy space fields, `copyspace0` and `copyspace1`. This tells the macro to generate
   trace code for both spaces, and for any copying in the spaces, use `CopySemantics::DefaultCopy` that we have configured early.

macros/src/has_spaces_impl.rs

@@ -0,0 +1,87 @@
+use proc_macro2::TokenStream as TokenStream2;
+use proc_macro_error::abort_call_site;
+use quote::quote;
+use syn::{DeriveInput, Field};
+
+use crate::util;
+
+pub fn derive(input: DeriveInput) -> TokenStream2 {
+    let ident = input.ident;
+    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
+
+    let syn::Data::Struct(syn::DataStruct {
+        fields: syn::Fields::Named(ref fields),
+        ..
+    }) = input.data else {
+        abort_call_site!("`#[derive(HasSpaces)]` only supports structs with named fields.");
+    };
+
+    let spaces = util::get_fields_with_attribute(fields, "space");
+    let parent = util::get_unique_field_with_attribute(fields, "parent");
+
+    let items = generate_impl_items(&spaces, &parent);
+
+    let output = quote! {
+        impl #impl_generics crate::plan::HasSpaces #ty_generics for #ident #ty_generics #where_clause {
+            #items
+        }
+    };
+
+    output.into()
+}
+
+pub(crate) fn generate_impl_items<'a>(
+    space_fields: &[&'a Field],
+    parent_field: &Option<&'a Field>,
+) -> TokenStream2 {
+    // Currently we implement callback-style visitor methods.
+    // Iterators should be more powerful, but is more difficult to implement.
+
+    let mut space_visitors = vec![];
+    let mut space_visitors_mut = vec![];
+
+    for f in space_fields {
+        let f_ident = f.ident.as_ref().unwrap();
+
+        let visitor = quote! {
+            __func(&self.#f_ident);
+        };
+
+        let visitor_mut = quote! {
+            __func(&mut self.#f_ident);
+        };
+
+        space_visitors.push(visitor);
+        space_visitors_mut.push(visitor_mut);
+    }
+
+    let (parent_visitor, parent_visitor_mut) = if let Some(f) = parent_field {
+        let f_ident = f.ident.as_ref().unwrap();
+        let visitor = quote! {
+            self.#f_ident.for_each_space(&mut __func)
+        };
+        let visitor_mut = quote! {
+            self.#f_ident.for_each_space_mut(&mut __func)
+        };
+        (visitor, visitor_mut)
+    } else {
+        (quote! {}, quote! {})
+    };
+
+    let foo: Option<TokenStream2> = None;
+    let bar: Option<TokenStream2> = Some(quote! { /* do nothing */});
+
+    quote! {
+        fn for_each_space(&self, mut __func: impl FnMut(&dyn Space<VM>)) {
+            #(#space_visitors)*
+            #parent_visitor
+            #foo
+        }
+
+        fn for_each_space_mut(&mut self, mut __func: impl FnMut(&mut dyn Space<VM>)) {
+            #(#space_visitors_mut)*
+            #parent_visitor_mut
+            #bar
+        }
+    }
+}

macros/src/lib.rs

@@ -10,11 +10,21 @@ use quote::quote;
 use syn::parse_macro_input;
 use syn::DeriveInput;
 
+mod has_spaces_impl;
 mod plan_trace_object_impl;
 mod util;
 
 const DEBUG_MACRO_OUTPUT: bool = false;
 
+#[proc_macro_error]
+#[proc_macro_derive(HasSpaces, attributes(space, parent))]
+pub fn derive_has_spaces(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    let output = has_spaces_impl::derive(input);
+
+    output.into()
+}
+
 /// Generally a plan needs to add these attributes in order for the macro to work. The macro will
 /// generate an implementation of `PlanTraceObject` for the plan. With `PlanTraceObject`, the plan use
 /// `PlanProcessEdges` for GC tracing. The attributes only affects code generation in the macro, thus

src/plan/generational/copying/global.rs

@@ -27,9 +27,9 @@ use crate::ObjectQueue;
 use enum_map::EnumMap;
 use std::sync::atomic::{AtomicBool, Ordering};
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct GenCopy<VM: VMBinding> {
     #[parent]
     pub gen: CommonGenPlan<VM>,

src/plan/generational/global.rs

@@ -17,11 +17,11 @@ use std::sync::atomic::AtomicBool;
 use std::sync::atomic::Ordering;
 use std::sync::{Arc, Mutex};
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 /// Common implementation for generational plans. Each generational plan
 /// should include this type, and forward calls to it where possible.
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct CommonGenPlan<VM: VMBinding> {
     /// The nursery space.
     #[space]

src/plan/generational/immix/global.rs

@@ -29,13 +29,13 @@ use enum_map::EnumMap;
 use std::sync::atomic::AtomicBool;
 use std::sync::atomic::Ordering;
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 /// Generational immix. This implements the functionality of a two-generation copying
 /// collector where the higher generation is an immix space.
 /// See the PLDI'08 paper by Blackburn and McKinley for a description
 /// of the algorithm: <http://doi.acm.org/10.1145/1375581.1375586>.
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct GenImmix<VM: VMBinding> {
     /// Generational plan, which includes a nursery space and operations related with nursery.
     #[parent]

src/plan/global.rs

@@ -33,7 +33,7 @@ use enum_map::EnumMap;
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 pub fn create_mutator<VM: VMBinding>(
     tls: VMMutatorThread,
@@ -385,7 +385,7 @@ pub enum GcStatus {
 /**
 BasePlan should contain all plan-related state and functions that are _fundamental_ to _all_ plans.  These include VM-specific (but not plan-specific) features such as a code space or vm space, which are fundamental to all plans for a given VM.  Features that are common to _many_ (but not intrinsically _all_) plans should instead be included in CommonPlan.
 */
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct BasePlan<VM: VMBinding> {
     /// Whether MMTk is now ready for collection. This is set to true when initialize_collection() is called.
     pub initialized: AtomicBool,
@@ -896,7 +896,7 @@ impl<VM: VMBinding> BasePlan<VM> {
 /**
 CommonPlan is for representing state and features used by _many_ plans, but that are not fundamental to _all_ plans.  Examples include the Large Object Space and an Immortal space.  Features that are fundamental to _all_ plans must be included in BasePlan.
 */
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct CommonPlan<VM: VMBinding> {
     #[space]
     pub immortal: ImmortalSpace<VM>,
@@ -1014,6 +1014,33 @@ impl<VM: VMBinding> CommonPlan<VM> {
 use crate::policy::gc_work::TraceKind;
 use crate::vm::VMBinding;
 
+/// A trait for anything that contains spaces.
+/// Examples include concrete plans as well as `Gen`, `CommonPlan` and `BasePlan`.
+///
+/// This trait provides methods for enumerating spaces in a struct, including nested struct such as
+/// `Gen`, `CommonPlan` and `BasePlan`.
+///
+/// This trait can be implemented automatically using `#[derive(HasSpaces)]` defined in the
+/// `mmtk-macros` crate.
+///
+/// This trait visits spaces as `dyn`, so it should only be used when performance is not critical.
+/// For performance critical methods that visit spaces in a plan, such as `trace_object`, it is
+/// recommended to define a trait (such as `PlanTraceObject`) for concrete plans to implement, and
+/// implement (by hand or automatically) the method without `dyn`.
+pub trait HasSpaces<VM: VMBinding> {
+    /// Visit each space field immutably.
+    ///
+    /// If `Self` contains a parent field that contain more spaces, this method will visit spaces
+    /// in the outer struct first.
+    fn for_each_space(&self, func: impl FnMut(&dyn Space<VM>));
+
+    /// Visit each space field mutably.
+    ///
+    /// If `Self` contains a parent field that contain more spaces, this method will visit spaces
+    /// in the outer struct first.
+    fn for_each_space_mut(&mut self, func: impl FnMut(&mut dyn Space<VM>));
+}
+
 /// A plan that uses `PlanProcessEdges` needs to provide an implementation for this trait.
 /// Generally a plan does not need to manually implement this trait. Instead, we provide
 /// a procedural macro that helps generate an implementation. Please check `macros/trace_object`.

src/plan/immix/global.rs

@@ -24,9 +24,9 @@ use std::sync::atomic::AtomicBool;
 use atomic::Ordering;
 use enum_map::EnumMap;
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct Immix<VM: VMBinding> {
     #[post_scan]
     #[space]

src/plan/markcompact/global.rs

@@ -25,9 +25,9 @@ use crate::vm::VMBinding;
 
 use enum_map::EnumMap;
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct MarkCompact<VM: VMBinding> {
     #[space]
     #[copy_semantics(CopySemantics::DefaultCopy)]

src/plan/marksweep/global.rs

@@ -16,7 +16,7 @@ use crate::util::metadata::side_metadata::{SideMetadataContext, SideMetadataSani
 use crate::util::VMWorkerThread;
 use crate::vm::VMBinding;
 use enum_map::EnumMap;
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 #[cfg(feature = "malloc_mark_sweep")]
 pub type MarkSweepSpace<VM> = crate::policy::marksweepspace::malloc_ms::MallocSpace<VM>;
@@ -28,7 +28,7 @@ pub type MarkSweepSpace<VM> = crate::policy::marksweepspace::native_ms::MarkSwee
 #[cfg(not(feature = "malloc_mark_sweep"))]
 use crate::policy::marksweepspace::native_ms::MAX_OBJECT_SIZE;
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct MarkSweep<VM: VMBinding> {
     #[parent]
     common: CommonPlan<VM>,

src/plan/mod.rs

@@ -24,6 +24,7 @@ pub(crate) use global::create_mutator;
 pub(crate) use global::create_plan;
 pub use global::AllocationSemantics;
 pub(crate) use global::GcStatus;
+pub(crate) use global::HasSpaces;
 pub use global::Plan;
 pub(crate) use global::PlanTraceObject;
 

src/plan/pageprotect/global.rs

@@ -18,9 +18,9 @@ use crate::{
 };
 use enum_map::EnumMap;
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct PageProtect<VM: VMBinding> {
     #[space]
     pub space: LargeObjectSpace<VM>,

src/plan/semispace/global.rs

@@ -18,11 +18,11 @@ use crate::util::opaque_pointer::VMWorkerThread;
 use crate::{plan::global::BasePlan, vm::VMBinding};
 use std::sync::atomic::{AtomicBool, Ordering};
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 use enum_map::EnumMap;
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct SemiSpace<VM: VMBinding> {
     pub hi: AtomicBool,
     #[space]

src/plan/sticky/immix/global.rs

@@ -21,12 +21,12 @@ use atomic::Ordering;
 use std::sync::atomic::AtomicBool;
 use std::sync::{Arc, Mutex};
 
-use mmtk_macros::PlanTraceObject;
+use mmtk_macros::{HasSpaces, PlanTraceObject};
 
 use super::gc_work::StickyImmixMatureGCWorkContext;
 use super::gc_work::StickyImmixNurseryGCWorkContext;
 
-#[derive(PlanTraceObject)]
+#[derive(HasSpaces, PlanTraceObject)]
 pub struct StickyImmix<VM: VMBinding> {
     #[parent]
     immix: immix::Immix<VM>,

src/policy/gc_work.rs

@@ -13,7 +13,7 @@ use crate::util::ObjectReference;
 use crate::vm::VMBinding;
 
 /// This trait defines policy-specific behavior for tracing objects.
-/// The procedural macro #[derive(PlanTraceObject)] will generate code
+/// The procedural macro #[derive(HasSpaces, PlanTraceObject)] will generate code
 /// that uses this trait. We expect any policy to implement this trait.
 /// For the sake of performance, the implementation
 /// of this trait should mark methods as `[inline(always)]`.