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. 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.
• 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.
• 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
  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.
• 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 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 the size of all the live objects in bytes in the last GC. MMTk usually accounts for memory in pages. This is a special method that we count the size of every live object in a GC, and sum up the total bytes. We provide this method so users can compare with used_bytes (which does page accounting), and know if the heap is fragmented. The value returned by this method is only updated when we finish tracing in a GC. A recommended timing to call this method is at the end of a GC (e.g. when the runtime is about to resume threads).
• 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 edge 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 edge 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 edge 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.