Function boehm_gc::register_finalizer [−] [src]

pub fn register_finalizer(
    ptr: *mut u8, 
    finalizer: extern "C" fn(_: *mut u8, _: *mut u8), 
    data: *mut u8, 
    mode: FinalizerMode
)

Attaches a finalizer function and metadata object to a garbage-collected pointer. The finalizer function will be run right before an object is collected, after it has become unreachable. The first argument to the finalizer function will be the object being collected (the ptr argument), while the second argument to the finalizer function will be the metadata object passed as the data argument.

The Boehm GC will attempt to build a graph of objects that need to be finalized (starting at ptr), perform a topological sort, and then finalize the objects in the order that the topological sort provides. This only works if the finalizer graph has no cycles. The Boehm GC offers a couple of different approaches to dealing with cycles in the finalizer graph:

  1. The Standard finalizer mode will naively do a topological sort and find the order in which things can be safely finalized. If there is a cycle in the graph, the Boehm GC will not finalize that pointer. If an object contains a pointer to itself, it will not be finalized (as this creates a cycle).
  2. The IgnoreSelf finalizer mode will behave similar to the Standard finalizer mode, but it will explicitly ignore any pointers from an object to itself. Objects that contain a pointer to themselves will be finalized in this mode.
  3. The NoOrder finalizer mode will throw all caution to the wind and finalize everything. It is up to the programmer to ensure that finalization code doesn't accidentally access finalized objects.

The Boehm GC provides mechanisms for breaking cycles in the finalizer chain but this crate does not yet expose them.