Crate shredder[][src]

Expand description


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!)


Atomic gc operations

Marker types

Various types used for plumbing, stuff you don’t need to care about

Helpful wrappers used for convenience methods


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


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


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.


A function for manually running a collection, ignoring the heuristic that governs normal garbage collector operations.

Returns how many Gcs 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 Mutexs inside Gcs.

A convenient alias for Gc<RefCell<T>>. Note that Gc<RefCell<T>> has additional specialized methods for working with RefCells inside Gcs.

A convenient alias for Gc<RwLock<T>>. Note that Gc<Mutex<T>> has additional specialized methods for working with Mutexs inside Gcs.

Derive Macros

The Finalize derive, powering #[derive(Finalize)]

The FinalizeFields derive, powering #[derive(FinalizeFields)]

The Scan derive, powering #[derive(Scan)]. Important details here!