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::VMEdge>>,
    pub(crate) edge_logger: EdgeLogger<VM::VMEdge>,
    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::VMEdge>>

edge_logger: EdgeLogger<VM::VMEdge>

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 )

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

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.

Trait Implementations

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

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