https://github.com/zesterer/broom

An ergonomic tracing garbage collector that supports mark 'n sweep garbage collection
https://github.com/zesterer/broom

garbage-collector memory-management rust-lang

Last synced: about 16 hours ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/zesterer/broom
• Owner: zesterer
• Created: 2020-03-23T16:53:11.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2022-10-23T01:06:50.000Z (about 2 years ago)
• Last Synced: 2024-10-20T21:08:43.443Z (27 days ago)
• Topics: garbage-collector, memory-management, rust-lang
• Language: Rust
• Homepage: https://docs.rs/broom/
• Size: 39.1 KB
• Stars: 251
• Watchers: 6
• Forks: 9
• Open Issues: 5
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Broom

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

[![Cargo](https://img.shields.io/crates/v/broom.svg)](

https://crates.io/crates/broom)

[![Documentation](https://docs.rs/broom/badge.svg)](

https://docs.rs/broom)

[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](

https://github.com/zesterer/broom)

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

```rust

use broom::prelude::*;

// The type you want the heap to contain

pub enum Object {

    Num(f64),

    List(Vec>),

}

// Tell the garbage collector how to explore a graph of this object

impl Trace for Object {

    fn trace(&self, tracer: &mut Tracer) {

        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:

- Apache License 2.0, (http://www.apache.org/licenses/LICENSE-2.0)

- MIT license (http://opensource.org/licenses/MIT)