Struct Arena 

pub struct Arena<R>
where
    R: for<'a> Rootable<'a>,
{ /* private fields */ }

A generic, garbage collected arena.

Garbage collected arenas allow for isolated sets of garbage collected objects with zero-overhead garbage collected pointers. It provides incremental mark and sweep garbage collection which must be manually triggered outside the mutate method, and works best when units of work inside mutate can be kept relatively small. It is designed primarily to be a garbage collector for scripting language runtimes.

The arena API is able to provide extremely cheap Gc pointers because it is based around “generativity”. During construction and access, the root type is branded by a unique, invariant lifetime 'gc which ensures that Gc pointers must be contained inside the root object hierarchy and cannot escape the arena callbacks or be smuggled inside another arena. This way, the arena can be sure that during mutation, all Gc pointers come from the arena we expect them to come from, and that they’re all either reachable from root or have been allocated during the current mutate call. When not inside the mutate callback, the arena knows that all Gc pointers must be either reachable from root or they are unreachable and safe to collect. In this way, incremental garbage collection can be achieved (assuming “sufficiently small” calls to mutate) that is both extremely safe and zero overhead vs what you would write in C with raw pointers and manually ensuring that invariants are held.

Implementations

impl<R> Arena<R>

where R: for<'a> Rootable<'a>, for<'a> Root<'a, R>: Sized,

pub fn new<F>(f: F) -> Arena<R>

where F: for<'gc> FnOnce(&'gc Mutation<'gc>) -> Root<'gc, R>,

Create a new arena with the given garbage collector tuning parameters. You must provide a closure that accepts a &Mutation<'gc> and returns the appropriate root.

pub fn try_new<F, E>(f: F) -> Result<Arena<R>, E>

where F: for<'gc> FnOnce(&'gc Mutation<'gc>) -> Result<Root<'gc, R>, E>,

Similar to new, but allows for constructor that can fail.

pub fn map_root<R2>( self, f: impl for<'gc> FnOnce(&'gc Mutation<'gc>, Root<'gc, R>) -> Root<'gc, R2>, ) -> Arena<R2>

where R2: for<'a> Rootable<'a>, for<'a> Root<'a, R2>: Sized,

pub fn try_map_root<R2, E>( self, f: impl for<'gc> FnOnce(&'gc Mutation<'gc>, Root<'gc, R>) -> Result<Root<'gc, R2>, E>, ) -> Result<Arena<R2>, E>

where R2: for<'a> Rootable<'a>, for<'a> Root<'a, R2>: Sized,

impl<R> Arena<R>

where R: for<'a> Rootable<'a>,

pub fn mutate<F, T>(&self, f: F) -> T

where F: for<'gc> FnOnce(&'gc Mutation<'gc>, &'gc Root<'gc, R>) -> T,

The primary means of interacting with a garbage collected arena. Accepts a callback which receives a &Mutation<'gc> and a reference to the root, and can return any non garbage collected value. The callback may “mutate” any part of the object graph during this call, but no garbage collection will take place during this method.

pub fn mutate_root<F, T>(&mut self, f: F) -> T

where F: for<'gc> FnOnce(&'gc Mutation<'gc>, &'gc mut Root<'gc, R>) -> T,

An alternative version of Arena::mutate which allows mutating the root set, at the cost of an extra write barrier.

pub fn metrics(&self) -> &Metrics

pub fn collection_phase(&self) -> CollectionPhase

impl<R> Arena<R>

where R: for<'a> Rootable<'a>, for<'a> Root<'a, R>: Collect,

pub fn collect_debt(&mut self)

Run incremental garbage collection until the allocation debt is <= 0.0.

There is no minimum unit of work enforced here, so it may be faster to only call this method when the allocation debt is above some threshold.

This method will always return at least once when collection enters the Sleeping phase, i.e. it will never transition from the Sweeping phase to the Marking phase without returning in-between.

pub fn mark_debt(&mut self) -> Option<MarkedArena<'_, R>>

Run only the marking part of incremental garbage collection until allocation debt is <= 0.0.

This does not transition collection past the Marked phase. Does nothing if the collection phase is Marked or Sweeping, otherwise acts like Arena::collect_debt.

pub fn collect_all(&mut self)

Run the current garbage collection cycle to completion, stopping once garbage collection has restarted in the sleep phase. If the collector is currently in the sleep phase, this restarts the collection and performs a full collection before transitioning back to the sleep phase.

pub fn mark_all(&mut self) -> Option<MarkedArena<'_, R>>

Runs all of the remaining marking part of the current garbage collection cycle.

Similarly to Arena::mark_debt, this does not transition collection past the Marked phase, and does nothing if the collector is currently in the Marked phase or the Sweeping phase.