1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

//! Epoch-based garbage collection.
//!
//! # Pointers
//!
//! Concurrent collections are built using atomic pointers. This module provides [`Atomic`], which
//! is just a shared atomic pointer to a heap-allocated object. Loading an [`Atomic`] yields a
//! [`Ptr`], which is an epoch-protected pointer through which the loaded object can be safely
//! read.
//!
//! # Pinning
//!
//! Before an [`Atomic`] can be loaded, the current thread must be pinned. By pinning a thread we
//! declare that any object that gets removed from now on must not be destructed just yet. Garbage
//! collection of newly removed objects is suspended until the thread gets unpinned.
//!
//! # Garbage
//!
//! Objects that get removed from concurrent collections must be stashed away until all currently
//! pinned threads get unpinned. Such objects can be stored into a [`Garbage`], where they are kept
//! until the right time for their destruction comes.
//!
//! There is a global shared instance of [`Garbage`], which can only deallocate memory. It cannot
//! drop objects or run arbitrary destruction procedures. Removed objects can be stored into it by
//! calling [`defer_free`] or [`defer_drop`].
//!
//! [`Atomic`]: struct.Atomic.html
//! [`Garbage`]: struct.Garbage.html
//! [`Ptr`]: struct.Ptr.html
//! [`defer_free`]: struct.Scope.html#method.defer_free
//! [`defer_drop`]: struct.Scope.html#method.defer_drop

mod atomic;
mod garbage;
mod thread;

pub use self::atomic::{Atomic, Owned, Ptr};
pub use self::garbage::Garbage;
pub use self::thread::{Scope, is_pinned, pin, unprotected};

#[cfg(feature = "internals")]
pub use self::garbage::destroy_global;