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>,

pub fn new<F>(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.

Examples found in repository

examples/basic.rs (lines 85-96)

fn get_running_project(xml: &str, system: Rc<StdSystem<C>>) -> EnvArena {
    EnvArena::new(|mc| {
        let parser = ast::Parser::default();
        let ast = parser.parse(xml).unwrap();
        assert_eq!(ast.roles.len(), 1); // this should be handled more elegantly in practice - for the sake of this example, we only allow one role

        let (bytecode, init_info, locs, _) = ByteCode::compile(&ast.roles[0]).unwrap();

        let mut proj = Project::from_init(mc, &init_info, Rc::new(bytecode), Settings::default(), system);
        proj.input(mc, Input::Start); // this is equivalent to clicking the green flag button

        Env { proj: Gc::new(mc, RefLock::new(proj)), locs }
    })
}

pub fn try_new<F, E>(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) -> T

where 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.

Examples found in repository

examples/basic.rs (lines 139-152)

fn main() {
    // read in an xml file whose path is given as a command line argument
    let args = std::env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        panic!("usage: {} [xml file]", &args[0]);
    }
    let mut xml = String::new();
    std::fs::File::open(&args[1]).expect("failed to open file").read_to_string(&mut xml).expect("failed to read file");

    // create a new shared clock and start a thread that updates it at our desired interval
    let clock = Arc::new(Clock::new(UtcOffset::UTC, Some(Precision::Medium)));
    let clock_clone = clock.clone();
    std::thread::spawn(move || loop {
        std::thread::sleep(CLOCK_INTERVAL);
        clock_clone.update();
    });

    // create a custom config for the system - in this simple example we just implement the say/think blocks to print to stdout
    let config = Config::<C, StdSystem<C>> {
        request: None,
        command: Some(Rc::new(|_mc, key, command, _proc| match command {
            Command::Print { style: _, value } => {
                if let Some(value) = value {
                    println!("{value:?}");
                }
                key.complete(Ok(())); // any request that you handle must be completed - otherwise the calling process will hang forever
                CommandStatus::Handled
            }
            _ => CommandStatus::UseDefault { key, command }, // anything you don't handle should return the key and command to invoke the default behavior instead
        })),
    };

    // initialize our system with all the info we've put together
    let system = Rc::new(StdSystem::new_sync(CompactString::new(BASE_URL), None, config, clock.clone()));
    let mut env = get_running_project(&xml, system);

    // begin running the code - these are some helpers to make things more efficient in terms of memory and cpu resources
    let mut idle_sleeper = IdleAction::new(YIELDS_BEFORE_SLEEP, Box::new(|| std::thread::sleep(IDLE_SLEEP_TIME)));
    let mut next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
    loop {
        env.mutate(|mc, env| {
            let mut proj = env.proj.borrow_mut(mc);
            for _ in 0..1024 {
                // step the virtual machine forward by one bytecode instruction
                let res = proj.step(mc);
                if let ProjectStep::Error { error, proc } = &res {
                    // if we get an error, we can generate an error summary including a stack trace - here we just print out the result
                    let trace = ErrorSummary::extract(error, proc, &env.locs);
                    println!("error: {error:?}\ntrace: {trace:?}");
                }
                // this takes care of performing thread sleep if we get a bunch of no-ops from proj.step back to back
                idle_sleeper.consume(&res);
            }
        });
        // if it's time for us to do garbage collection, do it and reset the next collection time
        if clock.read(Precision::Low) >= next_collect {
            env.collect_all();
            next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
        }
    }
}

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

where 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 metrics(&self) -> &Metrics

pub fn collection_phase(&self) -> CollectionPhase

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 Collecting 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 Collecting, 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.

Examples found in repository

examples/basic.rs (line 155)

fn main() {
    // read in an xml file whose path is given as a command line argument
    let args = std::env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        panic!("usage: {} [xml file]", &args[0]);
    }
    let mut xml = String::new();
    std::fs::File::open(&args[1]).expect("failed to open file").read_to_string(&mut xml).expect("failed to read file");

    // create a new shared clock and start a thread that updates it at our desired interval
    let clock = Arc::new(Clock::new(UtcOffset::UTC, Some(Precision::Medium)));
    let clock_clone = clock.clone();
    std::thread::spawn(move || loop {
        std::thread::sleep(CLOCK_INTERVAL);
        clock_clone.update();
    });

    // create a custom config for the system - in this simple example we just implement the say/think blocks to print to stdout
    let config = Config::<C, StdSystem<C>> {
        request: None,
        command: Some(Rc::new(|_mc, key, command, _proc| match command {
            Command::Print { style: _, value } => {
                if let Some(value) = value {
                    println!("{value:?}");
                }
                key.complete(Ok(())); // any request that you handle must be completed - otherwise the calling process will hang forever
                CommandStatus::Handled
            }
            _ => CommandStatus::UseDefault { key, command }, // anything you don't handle should return the key and command to invoke the default behavior instead
        })),
    };

    // initialize our system with all the info we've put together
    let system = Rc::new(StdSystem::new_sync(CompactString::new(BASE_URL), None, config, clock.clone()));
    let mut env = get_running_project(&xml, system);

    // begin running the code - these are some helpers to make things more efficient in terms of memory and cpu resources
    let mut idle_sleeper = IdleAction::new(YIELDS_BEFORE_SLEEP, Box::new(|| std::thread::sleep(IDLE_SLEEP_TIME)));
    let mut next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
    loop {
        env.mutate(|mc, env| {
            let mut proj = env.proj.borrow_mut(mc);
            for _ in 0..1024 {
                // step the virtual machine forward by one bytecode instruction
                let res = proj.step(mc);
                if let ProjectStep::Error { error, proc } = &res {
                    // if we get an error, we can generate an error summary including a stack trace - here we just print out the result
                    let trace = ErrorSummary::extract(error, proc, &env.locs);
                    println!("error: {error:?}\ntrace: {trace:?}");
                }
                // this takes care of performing thread sleep if we get a bunch of no-ops from proj.step back to back
                idle_sleeper.consume(&res);
            }
        });
        // if it's time for us to do garbage collection, do it and reset the next collection time
        if clock.read(Precision::Low) >= next_collect {
            env.collect_all();
            next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
        }
    }
}

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 Collecting phase.