Struct netsblox_vm::gc::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>,

pub fn new<F>(arena_parameters: ArenaParameters, f: F) -> Arena<R>where F: for<'gc> FnOnce(&'gc Mutation<'gc>) -> <R as Rootable<'gc>>::Root,

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>( arena_parameters: ArenaParameters, f: F ) -> Result<Arena<R>, E>where F: for<'gc> FnOnce(&'gc Mutation<'gc>) -> Result<<R as Rootable<'gc>>::Root, E>,

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

pub fn mutate<F, T>(&self, f: F) -> Twhere F: for<'gc> FnOnce(&'gc Mutation<'gc>, &'gc <R as Rootable<'gc>>::Root) -> 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) -> Twhere F: for<'gc> FnOnce(&'gc Mutation<'gc>, &'gc mut <R as Rootable<'gc>>::Root) -> T,

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

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

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

pub fn total_allocated(&self) -> usize

Return total currently used memory.

pub fn remembered_size(&self) -> usize

pub fn allocation_debt(&self) -> f64

When the garbage collector is not sleeping, all allocated objects cause the arena to accumulate “allocation debt”. This debt is then be used to time incremental garbage collection based on the tuning parameters set in ArenaParameters. The allocation debt is measured in bytes, but will generally increase at a rate faster than that of allocation so that collection will always complete.

pub fn collect_debt(&mut self)

Run the incremental garbage collector 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.

pub fn collect_all(&mut self)

Run the current garbage collection cycle to completion, stopping once the garbage collector has entered the sleeping phase. If the garbage collector is currently sleeping, starts a new cycle and runs that cycle to completion.