Finalizable type (#609)

This PR adds a binding-defined type for finalizable objects. For some languages like Julia, their finalizers are actually object + function pointer, and one object can be registered with multiple finalize functions. To support this, we allow a binding to define their finalizable object type. By default, we provide an implementation that the finalizable is just an `ObjectReference`. 

This PR also adds APIs to allow a binding to manually pop finalizable objects that have been registered. This is cherry-picked from #578. This allows bindings to implement the finalize-on-exit behavior, or any other language-specific finalize behavior (e.g. Julia allows manually finalizing objects).

Author: qinsoon

src/memory_manager.rs

@@ -22,6 +22,7 @@ use crate::util::heap::layout::vm_layout_constants::HEAP_END;
 use crate::util::heap::layout::vm_layout_constants::HEAP_START;
 use crate::util::opaque_pointer::*;
 use crate::util::{Address, ObjectReference};
+use crate::vm::ReferenceGlue;
 use crate::vm::VMBinding;
 use std::sync::atomic::Ordering;
 
@@ -472,7 +473,10 @@ pub fn harness_end<VM: VMBinding>(mmtk: &'static MMTK<VM>) {
 /// Arguments:
 /// * `mmtk`: A reference to an MMTk instance
 /// * `object`: The object that has a finalizer
-pub fn add_finalizer<VM: VMBinding>(mmtk: &'static MMTK<VM>, object: ObjectReference) {
+pub fn add_finalizer<VM: VMBinding>(
+    mmtk: &'static MMTK<VM>,
+    object: <VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType,
+) {
     if *mmtk.options.no_finalizer {
         warn!("add_finalizer() is called when no_finalizer = true");
     }
@@ -488,9 +492,11 @@ pub fn add_finalizer<VM: VMBinding>(mmtk: &'static MMTK<VM>, object: ObjectRefer
 ///
 /// Arguments:
 /// * `mmtk`: A reference to an MMTk instance.
-pub fn get_finalized_object<VM: VMBinding>(mmtk: &'static MMTK<VM>) -> Option<ObjectReference> {
+pub fn get_finalized_object<VM: VMBinding>(
+    mmtk: &'static MMTK<VM>,
+) -> Option<<VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType> {
     if *mmtk.options.no_finalizer {
-        warn!("get_object_for_finalization() is called when no_finalizer = true");
+        warn!("get_finalized_object() is called when no_finalizer = true");
     }
 
     mmtk.finalizable_processor
@@ -499,6 +505,46 @@ pub fn get_finalized_object<VM: VMBinding>(mmtk: &'static MMTK<VM>) -> Option<Ob
         .get_ready_object()
 }
 
+/// Pop all the finalizers that were registered for finalization. The returned objects may or may not be ready for
+/// finalization. After this call, MMTk's finalizer processor should have no registered finalizer any more.
+///
+/// This is useful for some VMs which require all finalizable objects to be finalized on exit.
+///
+/// Arguments:
+/// * `mmtk`: A reference to an MMTk instance.
+pub fn get_all_finalizers<VM: VMBinding>(
+    mmtk: &'static MMTK<VM>,
+) -> Vec<<VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType> {
+    if *mmtk.options.no_finalizer {
+        warn!("get_all_finalizers() is called when no_finalizer = true");
+    }
+
+    mmtk.finalizable_processor
+        .lock()
+        .unwrap()
+        .get_all_finalizers()
+}
+
+/// Pop finalizers that were registered and associated with a certain object. The returned objects may or may not be ready for finalization.
+/// This is useful for some VMs that may manually execute finalize method for an object.
+///
+/// Arguments:
+/// * `mmtk`: A reference to an MMTk instance.
+/// * `object`: the given object that MMTk will pop its finalizers
+pub fn get_finalizers_for<VM: VMBinding>(
+    mmtk: &'static MMTK<VM>,
+    object: ObjectReference,
+) -> Vec<<VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType> {
+    if *mmtk.options.no_finalizer {
+        warn!("get_finalizers() is called when no_finalizer = true");
+    }
+
+    mmtk.finalizable_processor
+        .lock()
+        .unwrap()
+        .get_finalizers_for(object)
+}
+
 /// Get the number of workers. MMTk spawns worker threads for the 'threads' defined in the options.
 /// So the number of workers is derived from the threads option. Note the feature single_worker overwrites
 /// the threads option, and force one worker thread.

src/mmtk.rs

@@ -11,6 +11,7 @@ use crate::util::options::{Options, UnsafeOptionsWrapper};
 use crate::util::reference_processor::ReferenceProcessors;
 #[cfg(feature = "sanity")]
 use crate::util::sanity::sanity_checker::SanityChecker;
+use crate::vm::ReferenceGlue;
 use crate::vm::VMBinding;
 use std::default::Default;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -43,7 +44,8 @@ pub static SFT_MAP: InitializeOnce<SFTMap<'static>> = InitializeOnce::new();
 pub struct MMTK<VM: VMBinding> {
     pub(crate) plan: Box<dyn Plan<VM = VM>>,
     pub(crate) reference_processors: ReferenceProcessors,
-    pub(crate) finalizable_processor: Mutex<FinalizableProcessor>,
+    pub(crate) finalizable_processor:
+        Mutex<FinalizableProcessor<<VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType>>,
     pub(crate) options: Arc<UnsafeOptionsWrapper>,
     pub(crate) scheduler: Arc<GCWorkScheduler<VM>>,
     #[cfg(feature = "sanity")]
@@ -76,7 +78,9 @@ impl<VM: VMBinding> MMTK<VM> {
         MMTK {
             plan,
             reference_processors: ReferenceProcessors::new(),
-            finalizable_processor: Mutex::new(FinalizableProcessor::new()),
+            finalizable_processor: Mutex::new(FinalizableProcessor::<
+                <VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType,
+            >::new()),
             options,
             scheduler,
             #[cfg(feature = "sanity")]

src/util/finalizable_processor.rs

@@ -1,6 +1,8 @@
 use crate::scheduler::gc_work::ProcessEdgesWork;
 use crate::scheduler::{GCWork, GCWorker};
-use crate::util::{ObjectReference, VMWorkerThread};
+use crate::util::ObjectReference;
+use crate::util::VMWorkerThread;
+use crate::vm::Finalizable;
 use crate::vm::{Collection, VMBinding};
 use crate::MMTK;
 use std::marker::PhantomData;
@@ -9,18 +11,18 @@ use std::marker::PhantomData;
 // TODO: we should consider if we want to merge FinalizableProcessor with ReferenceProcessor,
 // and treat final reference as a special reference type in ReferenceProcessor.
 #[derive(Default)]
-pub struct FinalizableProcessor {
+pub struct FinalizableProcessor<F: Finalizable> {
     /// Candidate objects that has finalizers with them
-    candidates: Vec<ObjectReference>,
+    candidates: Vec<F>,
     /// Index into candidates to record where we are up to in the last scan of the candidates.
     /// Index after nursery_index are new objects inserted after the last GC.
     nursery_index: usize,
     /// Objects that can be finalized. They are actually dead, but we keep them alive
     /// until the binding pops them from the queue.
-    ready_for_finalize: Vec<ObjectReference>,
+    ready_for_finalize: Vec<F>,
 }
 
-impl FinalizableProcessor {
+impl<F: Finalizable> FinalizableProcessor<F> {
     pub fn new() -> Self {
         Self {
             candidates: vec![],
@@ -29,22 +31,12 @@ impl FinalizableProcessor {
         }
     }
 
-    pub fn add(&mut self, object: ObjectReference) {
+    pub fn add(&mut self, object: F) {
         self.candidates.push(object);
     }
 
-    fn get_forwarded_finalizable<E: ProcessEdgesWork>(
-        e: &mut E,
-        object: ObjectReference,
-    ) -> ObjectReference {
-        e.trace_object(object)
-    }
-
-    fn return_for_finalize<E: ProcessEdgesWork>(
-        e: &mut E,
-        object: ObjectReference,
-    ) -> ObjectReference {
-        e.trace_object(object)
+    fn forward_finalizable_reference<E: ProcessEdgesWork>(e: &mut E, finalizable: &mut F) {
+        finalizable.keep_alive::<E>(e);
     }
 
     pub fn scan<E: ProcessEdgesWork>(&mut self, tls: VMWorkerThread, e: &mut E, nursery: bool) {
@@ -55,29 +47,29 @@ impl FinalizableProcessor {
         // theoratically we could do the following loop at any time in a GC (not necessarily after closure phase).
         // But we have to iterate through candidates after closure.
         self.candidates.append(&mut self.ready_for_finalize);
+        debug_assert!(self.ready_for_finalize.is_empty());
 
-        for reff in self
-            .candidates
-            .drain(start..)
-            .collect::<Vec<ObjectReference>>()
-        {
+        for mut f in self.candidates.drain(start..).collect::<Vec<F>>() {
+            let reff = f.get_reference();
             trace!("Pop {:?} for finalization", reff);
             if reff.is_live() {
-                let res = FinalizableProcessor::get_forwarded_finalizable(e, reff);
-                trace!("{:?} is live, push {:?} back to candidates", reff, res);
-                self.candidates.push(res);
+                FinalizableProcessor::<F>::forward_finalizable_reference(e, &mut f);
+                trace!("{:?} is live, push {:?} back to candidates", reff, f);
+                self.candidates.push(f);
                 continue;
             }
 
-            let retained = FinalizableProcessor::return_for_finalize(e, reff);
-            self.ready_for_finalize.push(retained);
-            trace!(
-                "{:?} is not live, push {:?} to ready_for_finalize",
-                reff,
-                retained
-            );
+            // We should not at this point mark the object as live. A binding may register an object
+            // multiple times with different finalizer methods. If we mark the object as live here, and encounter
+            // the same object later in the candidates list (possibly with a different finalizer method),
+            // we will erroneously think the object never died, and won't push it to the ready_to_finalize
+            // queue.
+            // So we simply push the object to the ready_for_finalize queue, and mark them as live objects later.
+            self.ready_for_finalize.push(f);
         }
-        e.flush();
+
+        // Keep the finalizable objects alive.
+        self.forward_finalizable(e, nursery);
 
         self.nursery_index = self.candidates.len();
 
@@ -87,20 +79,51 @@ impl FinalizableProcessor {
     pub fn forward_candidate<E: ProcessEdgesWork>(&mut self, e: &mut E, _nursery: bool) {
         self.candidates
             .iter_mut()
-            .for_each(|reff| *reff = FinalizableProcessor::get_forwarded_finalizable(e, *reff));
+            .for_each(|f| FinalizableProcessor::<F>::forward_finalizable_reference(e, f));
         e.flush();
     }
 
     pub fn forward_finalizable<E: ProcessEdgesWork>(&mut self, e: &mut E, _nursery: bool) {
         self.ready_for_finalize
             .iter_mut()
-            .for_each(|reff| *reff = FinalizableProcessor::get_forwarded_finalizable(e, *reff));
+            .for_each(|f| FinalizableProcessor::<F>::forward_finalizable_reference(e, f));
         e.flush();
     }
 
-    pub fn get_ready_object(&mut self) -> Option<ObjectReference> {
+    pub fn get_ready_object(&mut self) -> Option<F> {
         self.ready_for_finalize.pop()
     }
+
+    pub fn get_all_finalizers(&mut self) -> Vec<F> {
+        let mut ret = std::mem::take(&mut self.candidates);
+        let ready_objects = std::mem::take(&mut self.ready_for_finalize);
+
+        ret.extend(ready_objects);
+        ret
+    }
+
+    pub fn get_finalizers_for(&mut self, object: ObjectReference) -> Vec<F> {
+        // Drain filter for finalizers that equal to 'object':
+        // * for elements that equal to 'object', they will be removed from the original vec, and returned.
+        // * for elements that do not equal to 'object', they will be left in the original vec.
+        // TODO: We should replace this with `vec.drain_filter()` when it is stablized.
+        let drain_filter = |vec: &mut Vec<F>| -> Vec<F> {
+            let mut i = 0;
+            let mut ret = vec![];
+            while i < vec.len() {
+                if vec[i].get_reference() == object {
+                    let val = vec.remove(i);
+                    ret.push(val);
+                } else {
+                    i += 1;
+                }
+            }
+            ret
+        };
+        let mut ret: Vec<F> = drain_filter(&mut self.candidates);
+        ret.extend(drain_filter(&mut self.ready_for_finalize));
+        ret
+    }
 }
 
 #[derive(Default)]

src/vm/mod.rs

@@ -27,6 +27,7 @@ pub use self::collection::Collection;
 pub use self::collection::GCThreadContext;
 pub use self::object_model::specs::*;
 pub use self::object_model::ObjectModel;
+pub use self::reference_glue::Finalizable;
 pub use self::reference_glue::ReferenceGlue;
 pub use self::scanning::EdgeVisitor;
 pub use self::scanning::Scanning;

src/vm/reference_glue.rs

@@ -3,8 +3,22 @@ use crate::util::ObjectReference;
 use crate::util::VMWorkerThread;
 use crate::vm::VMBinding;
 
-/// VM-specific methods for reference processing.
+/// VM-specific methods for reference processing, including weak references, and finalizers.
+/// We handle weak references and finalizers differently:
+/// * for weak references, we assume they are implemented as normal reference objects (also known as weak objects)
+///   with a referent that is actually weakly reachable. This trait provides a few methods to access
+///   the referent of such an reference object.
+/// * for finalizers, we provide a `Finalizable` trait, and require bindings to specify a type
+///   that implements `Finalizable`. When the binding registers or pops a finalizable object
+///   from MMTk, the specified type is used for the finalizable objects. For most languages,
+///   they can just use `ObjectReference` for the finalizable type, meaning that they are registering
+///   and popping a normal object reference as finalizable objects.
 pub trait ReferenceGlue<VM: VMBinding> {
+    /// The type of finalizable objects. This type is used when the binding registers and pops finalizable objects.
+    type FinalizableType: Finalizable;
+
+    // TODO: Should we also move the following methods about weak references to a trait (similar to the `Finalizable` trait)?
+
     /// Weak and soft references always clear the referent
     /// before enqueueing.
     ///
@@ -16,20 +30,20 @@ pub trait ReferenceGlue<VM: VMBinding> {
         });
     }
 
-    /// Get the referent from a reference.
+    /// Get the referent from a weak reference object.
     ///
     /// Arguments:
     /// * `object`: The object reference.
     fn get_referent(object: ObjectReference) -> ObjectReference;
 
-    /// Set the referent in a reference.
+    /// Set the referent in a weak reference object.
     ///
     /// Arguments:
     /// * `reff`: The object reference for the reference.
     /// * `referent`: The referent object reference.
     fn set_referent(reff: ObjectReference, referent: ObjectReference);
 
-    /// For reference types, if the referent is cleared during GC, the reference
+    /// For weak reference types, if the referent is cleared during GC, the reference
     /// will be added to a queue, and MMTk will call this method to inform
     /// the VM about the changes for those references. This method is used
     /// to implement Java's ReferenceQueue.
@@ -38,3 +52,39 @@ pub trait ReferenceGlue<VM: VMBinding> {
     /// MMTk will no longer keep these references alive once this method is returned.
     fn enqueue_references(references: &[ObjectReference], tls: VMWorkerThread);
 }
+
+use crate::scheduler::gc_work::ProcessEdgesWork;
+
+/// A finalizable object for MMTk. MMTk needs to know the actual object reference in the type,
+/// while a binding can use this type to store some runtime information about finalizable objects.
+/// For example, for bindings that allows multiple finalizer methods with one object, they can define
+/// the type as a tuple of `(object, finalize method)`, and register different finalizer methods to MMTk
+/// for the same object.
+/// The implementation should mark theird method implementations as inline for performance.
+pub trait Finalizable: std::fmt::Debug + Send {
+    /// Load the object reference.
+    fn get_reference(&self) -> ObjectReference;
+    /// Store the object reference.
+    fn set_reference(&mut self, object: ObjectReference);
+    /// Keep the heap references in the finalizable object alive. For example, the reference itself needs to be traced. However,
+    /// if the finalizable object includes other heap references, the implementation should trace them as well.
+    /// Note that trace_object() may move objects so we need to write the new reference in case that it is moved.
+    fn keep_alive<E: ProcessEdgesWork>(&mut self, trace: &mut E);
+}
+
+/// This provides an implementation of `Finalizable` for `ObjectReference`. Most bindings
+/// should be able to use `ObjectReference` as `ReferenceGlue::FinalizableType`.
+impl Finalizable for ObjectReference {
+    #[inline(always)]
+    fn get_reference(&self) -> ObjectReference {
+        *self
+    }
+    #[inline(always)]
+    fn set_reference(&mut self, object: ObjectReference) {
+        *self = object;
+    }
+    #[inline(always)]
+    fn keep_alive<E: ProcessEdgesWork>(&mut self, trace: &mut E) {
+        *self = trace.trace_object(*self);
+    }
+}

vmbindings/dummyvm/src/reference_glue.rs

@@ -6,6 +6,8 @@ use crate::DummyVM;
 pub struct VMReferenceGlue {}
 
 impl ReferenceGlue<DummyVM> for VMReferenceGlue {
+    type FinalizableType = ObjectReference;
+
     fn set_referent(_reference: ObjectReference, _referent: ObjectReference) {
         unimplemented!()
     }