Module mmtk::memory_manager [−][src]
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. |
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. |