[−][src]Macro gc_arena::make_arena
Creates a new "garbage collected arena" type. The macro takes two parameters, the name you
would like to give the arena type, and the type of the arena root. The root type must implement
the Collect
trait, and be a type that takes a single generic lifetime parameter which is used
for any held Gc
pointer types.
An eample:
#[derive(Collect)] #[collect(empty_drop)] struct MyRoot<'gc> { ptr: Gc<'gc, i32>, } make_arena!(MyArena, MyRoot);
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.