Skip to content
/ broom Public

An ergonomic tracing garbage collector that supports mark 'n sweep garbage collection

Notifications You must be signed in to change notification settings

zesterer/broom

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Broom

An ergonomic tracing garbage collector that supports mark 'n sweep garbage collection.

Cargo Documentation License

Features

  • Ergonomic API
  • Mark and sweep heap cleaning
  • Easy (and safe) mutation of heap values, despite cycles
  • Zero-cost access to heap objects through handles

Example

use broom::prelude::*;

// The type you want the heap to contain
pub enum Object {
    Num(f64),
    List(Vec<Handle<Self>>),
}

// Tell the garbage collector how to explore a graph of this object
impl Trace<Self> for Object {
    fn trace(&self, tracer: &mut Tracer<Self>) {
        match self {
            Object::Num(_) => {},
            Object::List(objects) => objects.trace(tracer),
        }
    }
}

// Create a new heap
let mut heap = Heap::default();

// Temporary objects are cheaper than rooted objects, but don't survive heap cleans
let a = heap.insert_temp(Object::Num(42.0));
let b = heap.insert_temp(Object::Num(1337.0));

// Turn the numbers into a rooted list
let c = heap.insert(Object::List(vec![a, b]));

// Change one of the numbers - this is safe, even if the object is self-referential!
*heap.get_mut(a).unwrap() = Object::Num(256.0);

// Create another number object
let d = heap.insert_temp(Object::Num(0.0));

// Clean up unused heap objects
heap.clean();

// a, b and c are all kept alive because c is rooted and a and b are its children
assert!(heap.contains(a));
assert!(heap.contains(b));
assert!(heap.contains(c));

// Because `d` was temporary and unused, it did not survive the heap clean
assert!(!heap.contains(d));

Who this crate is for

  • People writing dynamically-typed languages in Rust that want a simple, reliable garbage collector
  • People that want to have complex graph data structures with mutation and cycles but who don't want memory leaks

Who this crate is not for

  • People that want garbage collection when writing ordinary Rust code

Performance

This crate makes no specific promises about performance. It is designed with a 'best attempt' approach; this means that it should be fast enough for most purposes but is probably not competitive with garbage collectors that have had years of development work ploughed into them.

TODO

There are a few things I want to do with broom if I get the time:

  • Smarter cleanup strategies than mark 'n sweep
  • Partial cleans to prevent garbage collection lag spikes

If you're interested in working on any of these things, feel free to open a pull request!

License

Broom is licensed under either of:

About

An ergonomic tracing garbage collector that supports mark 'n sweep garbage collection

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages