Module memory_manager

Expand description

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:

adding their VM-specific functions
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.
alloc_slow: Invoke the allocation slow path of alloc. Like alloc, this function may trigger GC and call crate::vm::Collection::block_for_gc or crate::vm::Collection::out_of_memory. The caller needs to be aware of that.
alloc_slow_with_options: Invoke the allocation slow path of alloc_with_options.
alloc_with_options: Allocate memory for an object.
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.
counted_calloc: The standard calloc except that with the feature malloc_counted_size, MMTk will count the allocated memory into its heap size. Thus the method requires a reference to an MMTk instance.
counted_malloc: The standard malloc except that with the feature malloc_counted_size, MMTk will count the allocated memory into its heap size. Thus the method requires a reference to an MMTk instance. MMTk either uses its own allocator, or forward the call to a library malloc.
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.
find_object_from_internal_pointer: Find if there is an object with VO bit set for the given address range. This should be used instead of crate::memory_manager::is_mmtk_object for conservative stack scanning if the binding may have internal pointers on the stack.
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.
free_with_size: The standard free except that with the feature malloc_counted_size, MMTk will count the allocated memory into its heap size. Thus the method requires a reference to an MMTk instance, and the size of the memory to free. The addr in the arguments must be an address that is earlier returned from MMTk’s malloc(), calloc() or realloc().
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.
get_malloc_bytes: Get the current active malloc’d bytes. Here MMTk only accounts for bytes that are done through those ‘counted malloc’ functions.
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.
is_mmtk_object: Check if addr is the raw address of an object reference to an MMTk object.
is_pinned: Check whether an object is currently pinned
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.
pin_object: Pin an object. MMTk will make sure that the object does not move during GC. Note that action cannot happen in some plans, eg, semispace. It returns true if the pinning operation has been performed, i.e., the object status changed from non-pinned to pinned
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.
realloc_with_old_size: The standard realloc except that with the feature malloc_counted_size, MMTk will count the allocated memory into its heap size. Thus the method requires a reference to an MMTk instance, and the size of the existing memory that will be reallocated. The addr in the arguments must be an address that is earlier returned from MMTk’s malloc(), calloc() or realloc().
set_vm_space: Add an externally mmapped region to the VM space. A VM space can be set through MMTk options (vm_space_start and vm_space_size), and can also be set through this function call. A VM space can be discontiguous. This function can be called multiple times, and all the address ranges passed as arguments in the function will be considered as part of the VM space. Currently we do not allow removing regions from VM space.
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.
unpin_object: Unpin an object. Returns true if the unpinning operation has been performed, i.e., the object status changed from pinned to non-pinned
used_bytes: Return used memory in bytes. MMTk accounts for memory in pages, thus this method always returns a value in page granularity.