Crate shredder[−][src]
Expand description
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 andDeref
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 useDerefGc
in many cases to avoid this) - multiple collectors: only a single global collector is supported
- can’t handle
Rc
/Arc
: requires allGc
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!)
Modules
Atomic gc operations
Marker types
Various types used for plumbing, stuff you don’t need to care about
Helpful wrappers used for convenience methods
Macros
Implements an empty Scan
implementation for a Send + 'static
type
A Send + 'static
type can be safely marked as GcSafe
, and this macro eases that
implementation
Structs
A Gc
, but with the ability to Deref
to its contents!
A smart-pointer for data tracked by shredder
garbage collector
A guard object that lets you access the underlying data of a Gc
.
It exists as data needs protection from being scanned while it’s being concurrently modified.
A GcSafe
version of &T
A GcSafe
version of &mut T
Scanner is a struct used to manage the scanning of data, sort of analogous to Hasher
Usually you will only care about this while implementing Scan
Traits
A trait implementing an alternative to Drop
, useful for non-GcDrop
data.
A trait that lets you finalize all fields of a piece of data
A trait capturing the ability of data to be scanned for references to data in a Gc
.
A trait that allows something that is Scan
to be converted to a dyn
ref.
Functions
A function for manually running a collection, ignoring the heuristic that governs normal garbage collector operations.
Returns how many Gc
s are currently in use.
Returns how many underlying allocations are currently allocated.
A convenience method for helping ensure your destructors are run.
Sets the percent more data that’ll trigger collection.
Block the current thread until the background thread has finished running the destructors for all data that was marked as garbage at the point this method was called.
Type Definitions
A convenient alias for Gc<Mutex<T>>
.
Note that Gc<Mutex<T>>
has additional specialized methods for working with Mutex
s inside
Gc
s.
A convenient alias for Gc<RefCell<T>>
.
Note that Gc<RefCell<T>>
has additional specialized methods for working with RefCell
s inside
Gc
s.
A convenient alias for Gc<RwLock<T>>
.
Note that Gc<Mutex<T>>
has additional specialized methods for working with Mutex
s inside
Gc
s.
Derive Macros
The Finalize
derive, powering #[derive(Finalize)]
The FinalizeFields
derive, powering #[derive(FinalizeFields)]
The Scan
derive, powering #[derive(Scan)]
. Important details here!