Struct mmtk::MMTK

pub struct MMTK<VM: VMBinding> {

    pub(crate) options: Arc<Options>,
    pub(crate) state: Arc<GlobalState>,
    pub(crate) plan: UnsafeCell<Box<dyn Plan<VM = VM>>>,
    pub(crate) reference_processors: ReferenceProcessors,
    pub(crate) finalizable_processor: Mutex<FinalizableProcessor<<VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType>>,
    pub(crate) scheduler: Arc<GCWorkScheduler<VM>>,
    pub(crate) sanity_checker: Mutex<SanityChecker<VM::VMSlot>>,
    pub(crate) slot_logger: SlotLogger<VM::VMSlot>,
    pub(crate) gc_trigger: Arc<GCTrigger<VM>>,
    pub(crate) gc_requester: Arc<GCRequester<VM>>,
    pub(crate) stats: Arc<Stats>,
    inside_harness: AtomicBool,
    inside_sanity: AtomicBool,
    pub(crate) analysis_manager: Arc<AnalysisManager<VM>>,
}

An MMTk instance. MMTk allows multiple instances to run independently, and each instance gives users a separate heap. Note that multi-instances is not fully supported yet

Fields

options: Arc<Options>

state: Arc<GlobalState>

plan: UnsafeCell<Box<dyn Plan<VM = VM>>>

reference_processors: ReferenceProcessors

finalizable_processor: Mutex<FinalizableProcessor<<VM::VMReferenceGlue as ReferenceGlue<VM>>::FinalizableType>>

scheduler: Arc<GCWorkScheduler<VM>>

sanity_checker: Mutex<SanityChecker<VM::VMSlot>>

slot_logger: SlotLogger<VM::VMSlot>

gc_trigger: Arc<GCTrigger<VM>>

gc_requester: Arc<GCRequester<VM>>

stats: Arc<Stats>

inside_harness: AtomicBool

inside_sanity: AtomicBool

analysis_manager: Arc<AnalysisManager<VM>>

Analysis counters. The feature analysis allows us to periodically stop the world and collect some statistics.

Implementations

impl<VM: VMBinding> MMTK<VM>

pub(crate) fn new(options: Arc<Options>) -> Self

Create an MMTK instance. This is not public. Bindings should use MMTKBuilder::build.

pub fn initialize_collection(&'static self, tls: VMThread)

Initialize the GC worker threads that are required for doing garbage collections. This is a mandatory call for a VM during its boot process once its thread system is ready.

Internally, this function will invoke Collection::spawn_gc_thread() to spawn GC worker threads.

Arguments

• tls: The thread that wants to enable the collection. This value will be passed back to the VM in Collection::spawn_gc_thread() so that the VM knows the context.

pub fn prepare_to_fork(&'static self)

Prepare an MMTk instance for calling the fork() system call.

The fork() system call is available on Linux and some UNIX variants, and may be emulated on other platforms by libraries such as Cygwin. The properties of the fork() system call requires the users to do some preparation before calling it.

• Multi-threading: If fork() is called when the process has multiple threads, it will only duplicate the current thread into the child process, and the child process can only call async-signal-safe functions, notably exec(). For VMs that that use multi-process concurrency, it is imperative that when calling fork(), only one thread may exist in the process.

• File descriptors: The child process inherits copies of the parent’s set of open file descriptors. This may or may not be desired depending on use cases.

This function helps VMs that use fork() for multi-process concurrency. It instructs all GC threads to save their contexts and return from their entry-point functions. Currently, such threads only include GC workers, and the entry point is crate::memory_manager::start_worker. A subsequent call to MMTK::after_fork() will re-spawn the threads using their saved contexts. The VM must not allocate objects in the MMTk heap before calling MMTK::after_fork().

TODO: Currently, the MMTk core does not keep any files open for a long time. In the future, this function and the after_fork function may be used for handling open file descriptors across invocations of fork(). One possible use case is logging GC activities and statistics to files, such as performing heap dumps across multiple GCs.

If a VM intends to execute another program by calling fork() and immediately calling exec, it may skip this function because the state of the MMTk instance will be irrelevant in that case.

Caution!

This function sends an asynchronous message to GC threads and returns immediately, but it is only safe for the VM to call fork() after the underlying native threads of the GC threads have exited. After calling this function, the VM should wait for their underlying native threads to exit in VM-specific manner before calling fork().

pub fn after_fork(&'static self, tls: VMThread)

Call this function after the VM called the fork() system call.

This function will re-spawn MMTk threads from saved contexts.

Arguments

• tls: The thread that wants to respawn MMTk threads after forking. This value will be passed back to the VM in Collection::spawn_gc_thread() so that the VM knows the context.

pub fn harness_begin(&self, tls: VMMutatorThread)

Generic hook to allow benchmarks to be harnessed. MMTk will trigger a GC to clear any residual garbage and start collecting statistics for the benchmark. This is usually called by the benchmark harness as its last step before the actual benchmark.

pub fn harness_end(&'static self)

Generic hook to allow benchmarks to be harnessed. MMTk will stop collecting statistics, and print out the collected statistics in a defined format. This is usually called by the benchmark harness right after the actual benchmark.

pub(crate) fn sanity_begin(&self)

pub(crate) fn sanity_end(&self)

pub(crate) fn is_in_sanity(&self) -> bool

pub(crate) fn set_gc_status(&self, s: GcStatus)

pub fn gc_in_progress(&self) -> bool

Return true if a collection is in progress.

pub fn gc_in_progress_proper(&self) -> bool

Return true if a collection is in progress and past the preparatory stage.

pub fn is_emergency_collection(&self) -> bool

Return true if the current GC is an emergency GC.

An emergency GC happens when a normal GC cannot reclaim enough memory to satisfy allocation requests. Plans may do full-heap GC, defragmentation, etc. during emergency in order to free up more memory.

VM bindings can call this function during GC to check if the current GC is an emergency GC. If it is, the VM binding is recommended to retain fewer objects than normal GCs, to the extent allowed by the specification of the VM or langauge. For example, the VM binding may choose not to retain objects used for caching. Specifically, for Java virtual machines, that means not retaining referents of SoftReference which is primarily designed for implementing memory-sensitive caches.

pub fn is_user_triggered_collection(&self) -> bool

Return true if the current GC is trigger manually by the user/binding.

pub fn handle_user_collection_request( &self, tls: VMMutatorThread, force: bool, exhaustive: bool ) -> bool

The application code has requested a collection. This is just a GC hint, and we may ignore it.

Returns whether a GC was ran or not. If MMTk triggers a GC, this method will block the calling thread and return true when the GC finishes. Otherwise, this method returns false immediately.

Arguments

• tls: The mutator thread that requests the GC
• force: The request cannot be ignored (except for NoGC)
• exhaustive: The requested GC should be exhaustive. This is also a hint.

pub fn trigger_internal_collection_request(&self)

MMTK has requested stop-the-world activity (e.g., stw within a concurrent gc).

pub fn get_plan(&self) -> &dyn Plan<VM = VM>

Get a reference to the plan.

pub unsafe fn get_plan_mut(&self) -> &mut dyn Plan<VM = VM>

Get the plan as mutable reference.

Safety

This is unsafe because the caller must ensure that the plan is not used by other threads.

pub fn get_options(&self) -> &Options

Get the run time options.

pub fn enumerate_objects<F>(&self, f: F)

where F: FnMut(ObjectReference),

Enumerate objects in all spaces in this MMTK instance.

The call-back function f is called for every object that has the valid object bit (VO bit), i.e. objects that are allocated in the heap of this MMTK instance, but has not been reclaimed, yet.

Notes about object initialization and finalization

When this function visits an object, it only guarantees that its VO bit must have been set. It is not guaranteed if the object has been “fully initialized” in the sense of the programming language the VM is implementing. For example, the object header and the type information may not have been written.

It will also visit objects that have been “finalized” in the sense of the programming langauge the VM is implementing, as long as the object has not been reclaimed by the GC, yet. Be careful. If the object header is destroyed, it may not be safe to access such objects in the high-level language.

Interaction with allocation and GC

This function does not mutate the heap. It is safe if multiple threads execute this function concurrently during mutator time.

It has undefined behavior if allocation or GC happens while this function is being executed. The VM binding must ensure no threads are allocating and GC does not start while executing this function. One way to do this is stopping all mutators before calling this function.

Some high-level languages may provide an API that allows the user to allocate objects and trigger GC while enumerating objects. One example is ObjectSpace::each_object in Ruby. The VM binding may use the callback of this function to save all visited object references and let the user visit those references after this function returns. Make sure those saved references are in the root set or in an object that will live through GCs before the high-level language finishes visiting the saved object references.

pub(crate) fn aggregate_live_bytes_in_last_gc( &self, live_bytes_per_space: [usize; 16] ) -> HashMap<&'static str, LiveBytesStats>

Aggregate a hash map of live bytes per space with the space stats to produce a map of live bytes stats for the spaces.

pub fn debug_print_vm_maps( &self, out: &mut impl Write, space_name: Option<&str> ) -> Result<(), Error>

Print VM maps. It will print the memory ranges used by spaces as well as some attributes of the spaces.

• “I”: The space is immortal. Its objects will never die.
• “N”: The space is non-movable. Its objects will never move.

Arguments:

• out: the place to print the VM maps.
• space_name: If None, print all spaces; if Some(n), only print the space whose name is n.

pub fn initialize_vm_space_object(&self, object: ObjectReference)

Initialize object metadata for a VM space object. Objects in the VM space are allocated/managed by the binding. This function provides a way for the binding to set object metadata in MMTk for an object in the space.

Trait Implementations

impl<VM: VMBinding> Send for MMTK<VM>

impl<VM: VMBinding> Sync for MMTK<VM>