mmtk/vm/
reference_glue.rs

1use crate::util::ObjectReference;
2use crate::util::VMWorkerThread;
3use crate::vm::VMBinding;
4
5/// VM-specific methods for reference processing, including weak references, and finalizers.
6/// We handle weak references and finalizers differently:
7/// * for weak references, we assume they are implemented as normal reference objects (also known as weak objects)
8///   with a referent that is actually weakly reachable. This trait provides a few methods to access
9///   the referent of such an reference object.
10/// * for finalizers, we provide a `Finalizable` trait, and require bindings to specify a type
11///   that implements `Finalizable`. When the binding registers or pops a finalizable object
12///   from MMTk, the specified type is used for the finalizable objects. For most languages,
13///   they can just use `ObjectReference` for the finalizable type, meaning that they are registering
14///   and popping a normal object reference as finalizable objects.
15pub trait ReferenceGlue<VM: VMBinding> {
16    /// The type of finalizable objects. This type is used when the binding registers and pops finalizable objects.
17    type FinalizableType: Finalizable;
18
19    // TODO: Should we also move the following methods about weak references to a trait (similar to the `Finalizable` trait)?
20
21    /// Weak and soft references always clear the referent
22    /// before enqueueing.
23    ///
24    /// Arguments:
25    /// * `new_reference`: The reference whose referent is to be cleared.
26    fn clear_referent(new_reference: ObjectReference);
27
28    /// Get the referent from a weak reference object.
29    ///
30    /// Arguments:
31    /// * `object`: Reference to the referent.  `None` if the object currently does not point to a
32    ///   referent.  This may happen if the reference has been cleared.
33    fn get_referent(object: ObjectReference) -> Option<ObjectReference>;
34
35    /// Set the referent in a weak reference object.
36    ///
37    /// Arguments:
38    /// * `reff`: The object reference for the reference.
39    /// * `referent`: The referent object reference.
40    fn set_referent(reff: ObjectReference, referent: ObjectReference);
41
42    /// For weak reference types, if the referent is cleared during GC, the reference
43    /// will be added to a queue, and MMTk will call this method to inform
44    /// the VM about the changes for those references. This method is used
45    /// to implement Java's ReferenceQueue.
46    /// Note that this method is called for each type of weak references during GC, and
47    /// the references slice will be cleared after this call is returned. That means
48    /// MMTk will no longer keep these references alive once this method is returned.
49    fn enqueue_references(references: &[ObjectReference], tls: VMWorkerThread);
50}
51
52use crate::scheduler::gc_work::ProcessEdgesWork;
53
54/// A finalizable object for MMTk. MMTk needs to know the actual object reference in the type,
55/// while a binding can use this type to store some runtime information about finalizable objects.
56/// For example, for bindings that allows multiple finalizer methods with one object, they can define
57/// the type as a tuple of `(object, finalize method)`, and register different finalizer methods to MMTk
58/// for the same object.
59/// The implementation should mark theird method implementations as inline for performance.
60pub trait Finalizable: std::fmt::Debug + Send {
61    /// Load the object reference.
62    fn get_reference(&self) -> ObjectReference;
63    /// Store the object reference.
64    fn set_reference(&mut self, object: ObjectReference);
65    /// Keep the heap references in the finalizable object alive. For example, the reference itself needs to be traced. However,
66    /// if the finalizable object includes other heap references, the implementation should trace them as well.
67    /// Note that trace_object() may move objects so we need to write the new reference in case that it is moved.
68    fn keep_alive<E: ProcessEdgesWork>(&mut self, trace: &mut E);
69}
70
71/// This provides an implementation of `Finalizable` for `ObjectReference`. Most bindings
72/// should be able to use `ObjectReference` as `ReferenceGlue::FinalizableType`.
73impl Finalizable for ObjectReference {
74    fn get_reference(&self) -> ObjectReference {
75        *self
76    }
77    fn set_reference(&mut self, object: ObjectReference) {
78        *self = object;
79    }
80    fn keep_alive<E: ProcessEdgesWork>(&mut self, trace: &mut E) {
81        *self = trace.trace_object(*self);
82    }
83}
mmtk/vm/reference_glue.rs

mmtk/vm/
reference_glue.rs
