Macro gc_arena::make_arena

macro_rules! make_arena {
    ($arena:ident, $root:ident) => { ... };
    ($v:vis $arena:ident, $root:ident) => { ... };
    (@impl $v:vis $arena:ident, $root:ident) => { ... };
}

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.