Skip to content

Latest commit

 

History

History
98 lines (68 loc) · 2.84 KB

README.md

File metadata and controls

98 lines (68 loc) · 2.84 KB
Raw

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: