Crate shredder

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

Modules

atomic

Atomic gc operations

marker

Marker types

plumbing

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

wrappers

Helpful wrappers used for convenience methods

Macros

impl_empty_scan_for_send_static

Implements an empty Scan implementation for a Send + 'static type

mark_send_static_gc_safe

A Send + 'static type can be safely marked as GcSafe, and this macro eases that implementation

Structs

DerefGc

A Gc, but with the ability to Deref to its contents!

Gc

A smart-pointer for data tracked by shredder garbage collector

GcGuard

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.

R

A GcSafe version of &T

RMut

A GcSafe version of &mut T

Scanner

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

Finalize

A trait implementing an alternative to Drop, useful for non-GcDrop data.

FinalizeFields

A trait that lets you finalize all fields of a piece of data

Scan

A trait capturing the ability of data to be scanned for references to data in a Gc.

ToScan

A trait that allows something that is Scan to be converted to a dyn ref.

Functions

collect

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

number_of_active_handles

Returns how many Gcs are currently in use.

number_of_tracked_allocations

Returns how many underlying allocations are currently allocated.

run_with_gc_cleanup

A convenience method for helping ensure your destructors are run.

set_gc_trigger_percent

Sets the percent more data that’ll trigger collection.

synchronize_destructors

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

GMutex

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

GRefCell

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

GRwLock

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

Derive Macros

Finalize

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

FinalizeFields

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

Scan

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