shredder

shredder is a library providing a garbage collected smart pointer: Gc. This is useful for times when you want shared access to some data, but the structure of the data has unpredictable cycles in it. (So Arc would not be appropriate.)

shredder has the following features:

• safe: detects error conditions on the fly, and protects you from undefined behavior
• ergonomic: no need to manually manage roots, just a regular smart pointer
• deref support: DerefGc gives you a garbage collected and Deref smart pointer where possible
• ready for fearless concurrency: works in multi-threaded contexts, with AtomicGc for cases where you need atomic operations
• limited stop-the world: regular processing will rarely be interrupted
• seamless destruction: regular drop for 'static data
• clean finalization: optional finalize for non-'static data
• concurrent collection: collection happens in the background, improving performance
• concurrent destruction: destructors are run in the background, improving performance

shredder has the following limitations:

• guarded access: accessing Gc data requires acquiring a guard (although you can use DerefGc in many cases to avoid this)
• multiple collectors: only a single global collector is supported
• can't handle Rc/Arc: requires all Gc objects have straightforward ownership semantics
• collection optimized for speed, not memory use: Gc and internal metadata is small, but there is bloat during collection (will fix!)
• no no-std support: The collector requires threading and other std features (will fix!)

Getting Started

Here is an easy example, showing how Gc works:

use std::cell::RefCell;

use shredder::{
    number_of_active_handles, number_of_tracked_allocations, run_with_gc_cleanup, Gc, Scan,
};

#[derive(Scan)]
struct Node {
    data: String,
    directed_edges: Vec<Gc<RefCell<Node>>>,
}

fn main() {
    // Using `run_with_gc_cleanup` is good practice, since it helps ensure destructors are run
    run_with_gc_cleanup(|| {
        let a = Gc::new(RefCell::new(Node {
            data: "A".to_string(),
            directed_edges: Vec::new(),
        }));

        let b = Gc::new(RefCell::new(Node {
            data: "B".to_string(),
            directed_edges: Vec::new(),
        }));

        // Usually would need `get` for `Gc` data, but `RefCell` is a special case
        a.borrow_mut().directed_edges.push(b.clone());
        b.borrow_mut().directed_edges.push(a);
        // We now have cyclical data!
    });
    // Everything was cleaned up!
    assert_eq!(number_of_tracked_allocations(), 0);
    assert_eq!(number_of_active_handles(), 0);
}

If you're playing with this and run into a problem, go ahead and make a Github issue. Eventually there will be a FAQ.

Help Wanted!

If you're interested in helping with shredder, feel free to reach out. I'm @Others on the Rust discord. Or just look for an issue marked help wanted or good first issue