Trait mmtk::plan::Plan

pub trait Plan: 'static + HasSpaces + Sync + Downcast {
    // Required methods
    fn constraints(&self) -> &'static PlanConstraints;
    fn base(&self) -> &BasePlan<Self::VM>;
    fn base_mut(&mut self) -> &mut BasePlan<Self::VM>;
    fn schedule_collection(
        &'static self,
        _scheduler: &GCWorkScheduler<Self::VM>
    );
    fn get_allocator_mapping(
        &self
    ) -> &'static EnumMap<AllocationSemantics, AllocatorSelector>;
    fn prepare(&mut self, tls: VMWorkerThread);
    fn release(&mut self, tls: VMWorkerThread);
    fn collection_required(
        &self,
        space_full: bool,
        space: Option<SpaceStats<'_, Self::VM>>
    ) -> bool;
    fn get_used_pages(&self) -> usize;

    // Provided methods
    fn create_copy_config(&'static self) -> CopyConfig<Self::VM> { ... }
    fn common(&self) -> &CommonPlan<Self::VM> { ... }
    fn generational(&self) -> Option<&dyn GenerationalPlan<VM = Self::VM>> { ... }
    fn options(&self) -> &Options { ... }
    fn prepare_worker(&self, _worker: &mut GCWorker<Self::VM>) { ... }
    fn end_of_gc(&mut self, _tls: VMWorkerThread) { ... }
    fn notify_emergency_collection(&self) { ... }
    fn get_reserved_pages(&self) -> usize { ... }
    fn get_total_pages(&self) -> usize { ... }
    fn get_available_pages(&self) -> usize { ... }
    fn get_collection_reserved_pages(&self) -> usize { ... }
    fn get_free_pages(&self) -> usize { ... }
    fn last_collection_was_exhaustive(&self) -> bool { ... }
    fn sanity_check_object(&self, _object: ObjectReference) -> bool { ... }
    fn verify_side_metadata_sanity(&self) { ... }
}

A plan describes the global core functionality for all memory management schemes. All global MMTk plans should implement this trait.

The global instance defines and manages static resources (such as memory and virtual memory resources).

Constructor:

For the constructor of a new plan, there are a few things the constructor must do (please check existing plans and see what they do in the constructor):

1. Create a HeapMeta, and use this HeapMeta to initialize all the spaces.
2. Create a vector of all the side metadata specs with SideMetadataContext::new_global_specs(), the parameter is a vector of global side metadata specs that are specific to the plan.
3. Initialize all the spaces the plan uses with the heap meta, and the global metadata specs vector.
4. Invoke the verify_side_metadata_sanity() method of the plan. It will create a SideMetadataSanity object, and invoke verify_side_metadata_sanity() for each space (or invoke verify_side_metadata_sanity() in CommonPlan/BasePlan for the spaces in the common/base plan).

Methods in this trait:

Only methods that will be overridden by each specific plan should be included in this trait. The trait may provide a default implementation, and each plan can override the implementation. For methods that won’t be overridden, we should implement those methods in BasePlan (or CommonPlan) and call them from there instead. We should avoid having methods with the same name in both Plan and BasePlan, as this may confuse people, and they may call a wrong method by mistake.

Required Methods

fn constraints(&self) -> &'static PlanConstraints

Get the plan constraints for the plan. This returns a non-constant value. A constant value can be found in each plan’s module if needed.

fn base(&self) -> &BasePlan<Self::VM>

Get a immutable reference to the base plan. BasePlan is included by all the MMTk GC plans.

fn base_mut(&mut self) -> &mut BasePlan<Self::VM>

Get a mutable reference to the base plan. BasePlan is included by all the MMTk GC plans.

fn schedule_collection(&'static self, _scheduler: &GCWorkScheduler<Self::VM>)

Schedule work for the upcoming GC.

fn get_allocator_mapping( &self ) -> &'static EnumMap<AllocationSemantics, AllocatorSelector>

Get the allocator mapping between crate::AllocationSemantics and crate::util::alloc::AllocatorSelector. This defines what space this plan will allocate objects into for different semantics.

fn prepare(&mut self, tls: VMWorkerThread)

Prepare the plan before a GC. This is invoked in an initial step in the GC. This is invoked once per GC by one worker thread. tls is the worker thread that executes this method.

fn release(&mut self, tls: VMWorkerThread)

Release the plan after transitive closure. A plan can implement this method to call each policy’s release, or create any work packet that should be done in release. This is invoked once per GC by one worker thread. tls is the worker thread that executes this method.

fn collection_required( &self, space_full: bool, space: Option<SpaceStats<'_, Self::VM>> ) -> bool

Ask the plan if they would trigger a GC. If MMTk is in charge of triggering GCs, this method is called periodically during allocation. However, MMTk may delegate the GC triggering decision to the runtime, in which case, this method may not be called. This method returns true to trigger a collection.

Arguments

• space_full: the allocation to a specific space failed, must recover pages within ‘space’.
• space: an option to indicate if there is a space that has failed in an allocation.

fn get_used_pages(&self) -> usize

Get the number of pages that are used.

Provided Methods

fn create_copy_config(&'static self) -> CopyConfig<Self::VM>

Create a copy config for this plan. A copying GC plan MUST override this method, and provide a valid config.

fn common(&self) -> &CommonPlan<Self::VM>

Get the common plan. CommonPlan is included by most of MMTk GC plans.

fn generational(&self) -> Option<&dyn GenerationalPlan<VM = Self::VM>>

Return a reference to GenerationalPlan to allow access methods specific to generational plans if the plan is a generational plan.

fn options(&self) -> &Options

Get the current run time options.

fn prepare_worker(&self, _worker: &mut GCWorker<Self::VM>)

Prepare a worker for a GC. Each worker has its own prepare method. This hook is for plan-specific per-worker preparation. This method is invoked once per worker by the worker thread passed as the argument.

fn end_of_gc(&mut self, _tls: VMWorkerThread)

Inform the plan about the end of a GC. It is guaranteed that there is no further work for this GC. This is invoked once per GC by one worker thread. tls is the worker thread that executes this method.

fn notify_emergency_collection(&self)

Notify the plan that an emergency collection will happen. The plan should try to free as much memory as possible. The default implementation will force a full heap collection for generational plans.

fn get_reserved_pages(&self) -> usize

Get the number of pages that are reserved, including pages used by MMTk spaces, pages that will be used (e.g. for copying), and live pages allocated outside MMTk spaces as reported by the VM binding.

fn get_total_pages(&self) -> usize

Get the total number of pages for the heap.

fn get_available_pages(&self) -> usize

Get the number of pages that are still available for use. The available pages should always be positive or 0.

fn get_collection_reserved_pages(&self) -> usize

Get the number of pages that are reserved for collection. By default, we return 0. For copying plans, they need to override this and calculate required pages to complete a copying GC.

fn get_free_pages(&self) -> usize

Get the number of pages that are NOT used. This is clearly different from available pages. Free pages are unused, but some of them may have been reserved for some reason.

fn last_collection_was_exhaustive(&self) -> bool

Return whether last GC was an exhaustive attempt to collect the heap. For example, for generational GCs, minor collection is not an exhaustive collection. For example, for Immix, fast collection (no defragmentation) is not an exhaustive collection.

fn sanity_check_object(&self, _object: ObjectReference) -> bool

An object is firstly reached by a sanity GC. So the object is reachable in the current GC, and all the GC work has been done for the object (such as tracing and releasing). A plan can implement this to use plan specific semantics to check if the object is sane. Return true if the object is considered valid by the plan.

fn verify_side_metadata_sanity(&self)

Call space.verify_side_metadata_sanity for all spaces in this plan.

Implementations

impl<VM> dyn Plan<VM = VM>

where VM: Any + 'static,

pub fn is<__T: Plan<VM = VM>>(&self) -> bool

Returns true if the trait object wraps an object of type __T.

pub fn downcast<__T: Plan<VM = VM>>( self: Box<Self> ) -> Result<Box<__T>, Box<Self>>

Returns a boxed object from a boxed trait object if the underlying object is of type __T. Returns the original boxed trait if it isn’t.

pub fn downcast_rc<__T: Plan<VM = VM>>( self: Rc<Self> ) -> Result<Rc<__T>, Rc<Self>>

Returns an Rc-ed object from an Rc-ed trait object if the underlying object is of type __T. Returns the original Rc-ed trait if it isn’t.

pub fn downcast_ref<__T: Plan<VM = VM>>(&self) -> Option<&__T>

Returns a reference to the object within the trait object if it is of type __T, or None if it isn’t.

pub fn downcast_mut<__T: Plan<VM = VM>>(&mut self) -> Option<&mut __T>

Returns a mutable reference to the object within the trait object if it is of type __T, or None if it isn’t.

Implementors