Module mmtk::memory_manager

source ·
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:

  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

  • 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 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 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 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 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.
  • 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.
  • 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.
  • 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.
  • 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).
  • The standard 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.
  • 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.
  • 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 the mutator’s local states.
  • The standard free. The addr in the arguments must be an address that is earlier returned from MMTk’s malloc(), calloc() or realloc().
  • Return free memory in bytes. MMTk accounts for memory in pages, thus this method always returns a value in page granularity.
  • 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().
  • 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.
  • 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.
  • 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 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.
  • 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 the current active malloc’d bytes. Here MMTk only accounts for bytes that are done through those ‘counted malloc’ functions.
  • Trigger a garbage collection as requested by the user.
  • Generic hook to allow benchmarks to be harnessed. We do a full heap GC, and then start recording statistics for MMTk.
  • Generic hook to allow benchmarks to be harnessed. We stop collecting statistics, and print stats values.
  • Initialize the scheduler and GC workers that are required for doing garbage collections. This is a mandatory call for a VM during its boot process once its thread system is ready. This should only be called once. This call will invoke Collection::spawn_gc_thread() to create GC threads.
  • Return true if the object lies in a region of memory where
  • Is the object alive?
  • 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.
  • Check if addr is the address of an object reference to an MMTk object.
  • Check whether an object is currently pinned
  • Return the ending address of the heap. Note that currently MMTk uses a fixed address range as heap.
  • 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).
  • The standard malloc. MMTk either uses its own allocator, or forward the call to a library malloc.
  • 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.
  • 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.
  • 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.
  • 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()).
  • 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.
  • 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.
  • 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.
  • 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 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
  • 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 MMTk run-time options. Returns true if the option is processed successfully.
  • Process multiple MMTk run-time options. Returns true if all the options are processed successfully.
  • The standard realloc.
  • 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().
  • 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.
  • Run the main loop for the GC controller thread. This method does not return.
  • Run the main loop of a GC worker. This method does not return.
  • Return the starting address of the heap. Note that currently MMTk uses a fixed address range as heap.
  • Return the total memory in bytes.
  • Unpin an object. Returns true if the unpinning operation has been performed, i.e., the object status changed from pinned to non-pinned
  • Return used memory in bytes. MMTk accounts for memory in pages, thus this method always returns a value in page granularity.