swmr_epoch/lib.rs
1//! # Epoch-Based Garbage Collection
2//!
3//! This module provides a minimal-locking, single-writer, multi-reader garbage collection system
4//! based on epoch-based reclamation. It is designed for scenarios where:
5//!
6//! - One thread (the writer) owns and updates shared data structures.
7//! - Multiple reader threads concurrently access the same data.
8//! - Readers need to safely access data without blocking the writer.
9//!
10//! ## Core Concepts
11//!
12//! **Epoch**: A logical timestamp that advances monotonically. The writer increments the epoch
13//! during garbage collection cycles. Readers "pin" themselves to an epoch, declaring that they
14//! are actively reading data from that epoch.
15//!
16//! **Pin**: When a reader calls `pin()`, it records the current epoch in its slot. This tells
17//! the writer: "I am reading data from this epoch; do not reclaim it yet."
18//!
19//! **Reclamation**: The writer collects retired objects and reclaims those from epochs that
20//! are older than the minimum epoch of all active readers.
21//!
22//! ## Typical Usage
23//!
24//! ```
25//! use swmr_epoch::{EpochGcDomain, EpochPtr};
26//!
27//! // 1. Create a shared GC domain and get the garbage collector
28//! let (mut gc, domain) = EpochGcDomain::new();
29//!
30//! // 2. Create an epoch-protected pointer
31//! let shared_ptr = EpochPtr::new(42i32);
32//!
33//! // 3. In each reader thread, register a local epoch
34//! let local_epoch = domain.register_reader();
35//!
36//! // 4. Readers pin themselves before accessing shared data
37//! let guard = local_epoch.pin();
38//! let value = shared_ptr.load(&guard);
39//! // ... use value ...
40//! // guard is automatically dropped, unpinning the thread
41//!
42//! // 5. Writer updates shared data and drives garbage collection
43//! shared_ptr.store(100i32, &mut gc);
44//! gc.collect(); // Reclaim garbage from old epochs
45//! ```
46
47pub(crate) mod domain;
48pub(crate) mod garbage;
49pub(crate) mod ptr;
50pub(crate) mod reader;
51pub(crate) mod state;
52mod sync;
53
54#[cfg(test)]
55mod tests;
56
57pub use domain::{EpochGcDomain, EpochGcDomainBuilder};
58pub use garbage::GcHandle;
59pub use ptr::EpochPtr;
60pub use reader::{LocalEpoch, PinGuard};