Module 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. A binding may call this either when a weak reference is created, or when a weak reference is traced during GC.

add_soft_candidate

Add a reference to the list of soft references. A binding may call this either when a weak reference is created, or when a weak reference is traced during GC.

add_weak_candidate

Add a reference to the list of weak references. A binding may call this either when a weak reference is created, or when a weak reference is traced during GC.

add_work_packet

Add a work packet to the given work bucket. Note that this simply adds the work packet to the given work bucket, and the scheduler will decide when to execute the work packet.

add_work_packets

Bulk add a number of work packets to the given work bucket. Note that this simply adds the work packets to the given work bucket, and the scheduler will decide when to execute the work packets.

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.

alloc_slow

Invoke the allocation slow path. This is only intended for use when a binding implements the fastpath on the binding side. When the binding handles fast path allocation and the fast path fails, it can use this method for slow path allocation. Calling before exhausting fast path allocaiton buffer will lead to bad performance.

bind_mutator

Request MMTk to create a mutator for the given thread. The ownership of returned boxed mutator is transferred to the binding, and the binding needs to take care of its lifetime. For performance reasons, A VM should store the returned mutator in a thread local storage that can be accessed efficiently. A VM may also copy and embed the mutator stucture to a thread-local data structure, and use that as a reference to the mutator (it is okay to drop the box once the content is copied – Note that Mutator may contain pointers so a binding may drop the box only if they perform a deep copy).

calloc

The standard calloc.

destroy_mutator

Report to MMTk that a mutator is no longer needed. All mutator state is flushed before it is destroyed. A binding should not attempt to use the mutator after this call. MMTk will not attempt to reclaim the memory for the mutator, so a binding should properly reclaim the memory for the mutator after this call.

flush_mutator

Flush the mutator’s local states.

free

The standard free. The addr in the arguments must be an address that is earlier returned from MMTk’s malloc(), calloc() or realloc().

free_bytes

Return free memory in bytes. MMTk accounts for memory in pages, thus this method always returns a value in page granularity.

gc_poll

Poll for GC. MMTk will decide if a GC is needed. If so, this call will block the current thread, and trigger a GC. Otherwise, it will simply return. Usually a binding does not need to call this function. MMTk will poll for GC during its allocation. However, if a binding uses counted malloc (which won’t poll for GC), they may want to poll for GC manually. This function should only be used by mutator threads.

get_all_finalizers

Pop all the finalizers that were registered for finalization. The returned objects may or may not be ready for finalization. After this call, MMTk’s finalizer processor should have no registered finalizer any more.

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.

get_finalizers_for

Pop finalizers that were registered and associated with a certain object. The returned objects may or may not be ready for finalization. This is useful for some VMs that may manually execute finalize method for an object.

handle_user_collection_request

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

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.

initialize_collection

Wrapper for crate::mmtk::MMTK::initialize_collection.

is_in_mmtk_spaces

Return true if the object lies in a region of memory where

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_in_mmtk_spaces(). For malloc spaces, MMTk does not map those addresses (malloc does the mmap), so this function will return false, but is_in_mmtk_spaces 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_in_mmtk_spaces(). This function is_mapped_address() may get removed at some point.

last_heap_address

Return the ending address of the heap. Note that currently MMTk uses a fixed address range as heap.

live_bytes_in_last_gc

Return a hash map for live bytes statistics in the last GC for each space.

malloc

The standard malloc. MMTk either uses its own allocator, or forward the call to a library malloc.

memory_region_copy

The subsuming memory region copy barrier by MMTk. This is called when the VM tries to copy a piece of heap memory to another. The data within the slice does not necessarily to be all valid pointers, but the VM binding will be able to filter out non-reference values on slot iteration.

memory_region_copy_post

The generic memory region copy post barrier by MMTk, which we expect a binding to call after it performs memory copy. This is called when the VM tries to copy a piece of heap memory to another. The data within the slice does not necessarily to be all valid pointers, but the VM binding will be able to filter out non-reference values on slot iteration.

memory_region_copy_pre

The generic memory region copy pre barrier by MMTk, which we expect a binding to call before it performs memory copy. This is called when the VM tries to copy a piece of heap memory to another. The data within the slice does not necessarily to be all valid pointers, but the VM binding will be able to filter out non-reference values on slot iteration.

mmtk_init

Initialize an MMTk instance. A VM should call this method after creating an crate::MMTK instance but before using any of the methods provided in MMTk (except process() and process_bulk()).

num_of_workers

Get the number of workers. MMTk spawns worker threads for the ‘threads’ defined in the options. So the number of workers is derived from the threads option. Note the feature single_worker overwrites the threads option, and force one worker thread.

object_reference_writeDeprecated

The subsuming write barrier by MMTk. For performance reasons, a VM should implement the write barrier fast-path on their side rather than just calling this function.

object_reference_write_post

The write barrier by MMTk. This is a post write barrier, which we expect a binding to call after it modifies an object. For performance reasons, a VM should implement the write barrier fast-path on their side rather than just calling this function.

object_reference_write_pre

The write barrier by MMTk. This is a pre write barrier, which we expect a binding to call before it modifies an object. For performance reasons, a VM should implement the write barrier fast-path on their side rather than just calling this function.

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. Returns true if the option is processed successfully.

process_bulk

Process multiple MMTk run-time options. Returns true if all the options are processed successfully.

realloc

The standard realloc.

start_worker

Wrapper for crate::scheduler::GCWorker::run.

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. MMTk accounts for memory in pages, thus this method always returns a value in page granularity.