Struct mmtk::mmtk::MMTK

source ·
pub struct MMTK<VM: VMBinding> {
Show 14 fields 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>>,
}
Expand description

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§

source§

impl<VM: VMBinding> MMTK<VM>

source

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

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

source

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.
source

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().

source

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.
source

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.

source

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.

source

pub(crate) fn sanity_begin(&self)

source

pub(crate) fn sanity_end(&self)

source

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

source

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

source

pub fn gc_in_progress(&self) -> bool

Return true if a collection is in progress.

source

pub fn gc_in_progress_proper(&self) -> bool

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

source

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.

source

pub fn is_user_triggered_collection(&self) -> bool

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

source

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.
source

pub fn trigger_internal_collection_request(&self)

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

source

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

Get a reference to the plan.

source

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.

source

pub fn get_options(&self) -> &Options

Get the run time options.

source

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

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.

Trait Implementations§

source§

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

source§

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

Auto Trait Implementations§

§

impl<VM> !RefUnwindSafe for MMTK<VM>

§

impl<VM> Unpin for MMTK<VM>

§

impl<VM> !UnwindSafe for MMTK<VM>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.