Module mmtk::memory_manager

VM-to-MMTk interface: safe Rust APIs.

This module provides a safe Rust API for mmtk-core. We expect the VM binding to inherit and extend this API by:

1. adding their VM-specific functions
2. exposing the functions to native if necessary. And the VM binding needs to manage the unsafety for exposing this safe API to FFI.

For example, for mutators, this API provides a Box<Mutator>, and requires a &mut Mutator for allocation. A VM binding can borrow a mutable reference directly from Box<Mutator>, and call alloc(). Alternatively, it can turn the Box pointer to a native pointer (*mut Mutator), and forge a mut reference from the native pointer. Either way, the VM binding code needs to guarantee the safety.

Functions

add_finalizer	Register a finalizable object. MMTk will retain the liveness of the object even if it is not reachable from the program. Note that finalization upon exit is not supported.
add_phantom_candidate	Add a reference to the list of phantom references.
add_soft_candidate	Add a reference to the list of soft references.
add_weak_candidate	Add a reference to the list of weak references.
alloc	Allocate memory for an object. For performance reasons, a VM should implement the allocation fast-path on their side rather than just calling this function.
bind_mutator	Request MMTk to create a mutator for the given thread. For performance reasons, A VM should store the returned mutator in a thread local storage that can be accessed efficiently.
destroy_mutator	Reclaim a mutator that is no longer needed.
enable_collection	Allow MMTk to trigger garbage collection. A VM should only call this method when it is ready for the mechanisms required for collection during the boot process. MMTk will invoke Collection::spawn_worker_thread() to create GC threads during this funciton call.
flush_mutator	Flush the mutator’s local states.
free_bytes	Return free memory in bytes.
gc_init	Initialize an MMTk instance. A VM should call this method after creating an MMTK instance but before using any of the methods provided in MMTk. This method will attempt to initialize a logger. If the VM would like to use its own logger, it should initialize the logger before calling this method.
get_allocator_mapping	Return an AllocatorSelector for the given allocation semantic. This method is provided so that VM compilers may call it to help generate allocation fast-path.
get_finalized_object	Get an object that is ready for finalization. After each GC, if any registered object is not alive, this call will return one of the objects. MMTk will retain the liveness of those objects until they are popped through this call. Once an object is popped, it is the responsibility of the VM to make sure they are properly finalized before reclaimed by the GC. This call is non-blocking, and will return None if no object is ready for finalization.
handle_user_collection_request	Trigger a garbage collection as requested by the user.
harness_begin	Generic hook to allow benchmarks to be harnessed. We do a full heap GC, and then start recording statistics for MMTk.
harness_end	Generic hook to allow benchmarks to be harnessed. We stop collecting statistics, and print stats values.
is_live_object	Is the object alive?
is_mapped_address	Is the address in the mapped memory? The runtime can use this function to check if an address is mapped by MMTk. Note that this is different than is_mapped_object(). For malloc spaces, MMTk does not map those addresses (malloc does the mmap), so this function will return false, but is_mapped_object will return true if the address is actually a valid object in malloc spaces. To check if an object is in our heap, the runtime should always use is_mapped_object(). This function is_mapped_address() may get removed at some point.
is_mapped_object	Is the object in the mapped memory? The runtime can use this function to check if an object is in MMTk heap.
last_heap_address	Return the ending address of the heap. Note that currently MMTk uses a fixed address range as heap.
modify_check	Check that if a garbage collection is in progress and if the given object is not movable. If it is movable error messages are logged and the system exits.
post_alloc	Perform post-allocation actions, usually initializing object metadata. For many allocators none are required. For performance reasons, a VM should implement the post alloc fast-path on their side rather than just calling this function.
process	Process MMTk run-time options.
start_control_collector	Run the main loop for the GC controller thread. This method does not return.
start_worker	Run the main loop of a GC worker. This method does not return.
starting_heap_address	Return the starting address of the heap. Note that currently MMTk uses a fixed address range as heap.
total_bytes	Return the total memory in bytes.
used_bytes	Return used memory in bytes.