auto_cc/
lib.rs

1//! A small utility function to perform automatic collections with [`bacon_rajan_cc`](../bacon_rajan_cc/index.html).
2
3pub extern crate bacon_rajan_cc;
4
5use bacon_rajan_cc::{
6    Cc,
7    Trace,
8    number_of_roots_buffered,
9    collect_cycles,
10};
11
12const CC_MAX_ROOTS: usize = 128;
13
14/// Wraps [`Cc::new`](struct.Cc.html) with some logic to automatically track the number of root objects in a garbage cycle
15/// and automatically collecting them when needed.
16/// 
17/// This function allows a maximum of `128` buffered roots before triggering a collection.
18/// 
19/// This function will perform a collection _before_ allocating a new [`Cc::new`](struct.Cc.html),
20/// so it is recommended to manually call [`collect_cycles`](collect/fn.collect_cycles.html) after any code
21/// where cycles are likely to be created has finished to perform final cleanup.
22/// 
23/// This function is meant to be a drop-in replacement for [`Cc::new`](struct.Cc.html) where needed,
24/// but does not modify or otherwise touch [`Cc<T>`](struct.Cc.html).
25/// 
26/// [`Cc::new`](struct.Cc.html) should be preferred unless it is known that an arbitrary number of cycles
27/// are likely to be created outside of the programmer's control and cleaning them up during normal
28/// execution is desirable.
29/// 
30/// # Example
31/// ```rust
32/// use auto_cc::cc;
33/// 
34/// let x = cc( 42u8 );
35/// ```
36#[inline( always )]
37pub fn cc<T: Trace>( value: T ) -> Cc<T> {
38    if number_of_roots_buffered() >= CC_MAX_ROOTS {
39        collect_cycles();
40    }
41
42    Cc::new( value )
43}
44
45
46#[cfg( test )]
47mod tests {
48    use std::cell::RefCell;
49
50    use super::{
51        CC_MAX_ROOTS,
52
53        Trace,
54        Cc,
55        cc,
56
57        bacon_rajan_cc::{
58            Tracer,
59            number_of_roots_buffered,
60            collect_cycles
61        },
62    };
63
64    fn create_cycle() {
65        struct List( Vec<Cc<RefCell<List>>> );
66        impl Trace for List {
67            fn trace( &self, tracer: &mut Tracer ) {
68                self.0.trace( tracer );
69            }
70        }
71
72        {
73            let a = cc( RefCell::new( List( Vec::new() ) ) );
74            let b = cc( RefCell::new( List( Vec::new() ) ) );
75
76            {
77                let mut a = a.borrow_mut();
78                a.0.push( b.clone() );
79            }
80
81            {
82                let mut b = b.borrow_mut();
83                b.0.push( a.clone() );
84            }
85        }
86    }
87
88    #[test]
89    fn auto_collection() {
90        // there obviously won't be any roots when we first start
91        assert_eq!( number_of_roots_buffered(), 0, "start" );
92
93        // each cycle has 2 items, so we create exactly INITIAL_ROOTS `Cc` objects
94        // putting us right at the collection threshold so the next cycle created
95        // will trip automatic collection
96        for _ in 0 .. CC_MAX_ROOTS / 2 {
97            create_cycle();
98        }
99
100        // verify we have all of our dead cycles
101        assert_eq!( number_of_roots_buffered(), CC_MAX_ROOTS, "before collection" );
102
103        // creating another cycle should trip automatic collection
104        create_cycle();
105
106        // we should have exactly 1 dead cycle, because collection happens before allocation
107        assert_eq!( number_of_roots_buffered(), 2, "after collection" );
108
109        // remove the last cycle
110        collect_cycles();
111
112        // ensure it's actually gone
113        assert_eq!( number_of_roots_buffered(), 0, "finished" );
114    }
115}
auto_cc/lib.rs

auto_cc/
lib.rs
