Crate tracing_rc

Cycle collecting reference counted pointers for Rust with a safe api.

This crate is most useful when you have a data structure with inter-dependent nodes of arbitrary lifetimes and no clear parent-children relationships.

If you can be certain that the layout of your data will be acyclic, or std::rc::Weak would be sufficient to prevent leaks, this type is probably not a good fit. If you know all of your data will be dropped after a certain phase of your program completes, you will probably prefer arena allocation through a crate like typed-arena, generational-arena, etc.

Concurrent Collection

Experimental support for concurrent collection may be enabled with the sync feature flag. When enabled, a sync::Agc type will be provided, paralleling std::sync::Arc. Note that you will need to call sync::collect instead of rc::collect to collect garbage generated by Agc values.

Basic Example

struct GraphNode<T: 'static> {
    data: T,
    edge: Option<Gc<GraphNode<T>>>,
}

impl<T> Trace for GraphNode<T> {
    fn visit_children(&self, visitor: &mut GcVisitor) {
        self.edge.visit_children(visitor);
    }
}

{
    let node_a = Gc::new(GraphNode {
        data: 10,
        edge: None,
    });
    let node_b = Gc::new(GraphNode {
        data: 11,
        edge: None,
    });
    let node_c = Gc::new(GraphNode {
        data: 12,
        edge: Some(node_a.clone()),
    });

    node_a.borrow_mut().edge = Some(node_b.clone());
    node_b.borrow_mut().edge = Some(node_c);

    let a = node_a.borrow();
    let b = a.edge.as_ref().unwrap().borrow();
    let c = b.edge.as_ref().unwrap().borrow();

    assert_eq!(a.data, c.edge.as_ref().unwrap().borrow().data);
    // all of the nodes go out of scope at this point and would normally be leaked.
}

// In this simple example, we always have cycles and our program is complete after this,
// so we can't take advantage of the young generation picking up acyclic pointers without
// tracing.
collect_full();

// All leaked nodes have been cleaned up!

Modules

rc

A non-sync cycle-collecting reference-counted smart pointer.

syncsync

An atomic cycle-collecting reference-counted smart pointer.

Macros

empty_trace

Implements a no-op Trace for a type.

sync_empty_tracesync

Implements a no-op Trace for a type.

Structs

CollectOptions

Provides settings which control how cycle-collection is performed.

Enums

CollectionType

Controls the style of collection carried out.

Derive Macros

SyncTracesync and proc_macro

Proc macro for deriving sync::Trace. By default, this will call Trace::visit_children on all members of the type.

Traceproc_macro

Proc macro for deriving Trace. By default, this will call Trace::visit_children on all members of the type.