Struct StorageGarbageCollector 

pub struct StorageGarbageCollector {
    pub config: StorageGcConfig,
    pub objects: HashMap<GcObjectId, GcObject>,
    pub roots: HashSet<GcObjectId>,
    pub gc_runs: VecDeque<StorageGcRun>,
    pub phase: GcPhase,
    pub next_run_id: u64,
}

Production-grade mark-and-sweep garbage collector for content-addressed storage.

Objects form a directed acyclic graph (DAG) via GcObject::links. GC roots and pinned objects anchor the live set; everything else that has no external references (ref_count == 0) is eligible for collection.

Fields

config: StorageGcConfig

Runtime configuration.

objects: HashMap<GcObjectId, GcObject>

All tracked objects keyed by id.

roots: HashSet<GcObjectId>

Set of explicit GC roots.

gc_runs: VecDeque<StorageGcRun>

History of completed GC runs (capped at 256 entries).

phase: GcPhase

Current collector phase.

next_run_id: u64

Counter used to assign monotonically increasing run ids.

Implementations

impl StorageGarbageCollector

pub fn new(config: StorageGcConfig) -> Self

Create a new collector with the given configuration.

pub fn add_object(&mut self, object: GcObject) -> Result<(), GcError>

Add a new object. Returns GcError::ObjectAlreadyExists if an object with the same id is already tracked.

pub fn remove_object(&mut self, id: &GcObjectId) -> Result<GcObject, GcError>

Remove and return an object.

Returns errors when:

• The object does not exist.
• The object is pinned.
• The object has ref_count > 0.

pub fn add_root(&mut self, id: &GcObjectId) -> bool

Mark an object as a GC root.

Returns true if the object exists (and was added as root), false otherwise.

pub fn remove_root(&mut self, id: &GcObjectId) -> bool

Remove an object from the GC root set.

Returns true if the object was a root (and has been removed).

pub fn increment_ref(&mut self, id: &GcObjectId) -> bool

Increment the external reference count for an object.

Returns true if the object was found, false otherwise.

pub fn decrement_ref(&mut self, id: &GcObjectId) -> bool

Decrement the external reference count (floor 0).

Returns true if the object was found. When ref_count reaches 0 and the object is neither a root nor pinned, it becomes a collection candidate on the next GC run.

pub fn pin(&mut self, id: &GcObjectId) -> bool

Pin an object so it is never swept.

Returns true if the object was found.

pub fn unpin(&mut self, id: &GcObjectId) -> bool

Unpin an object so it can be swept when unreachable.

Returns true if the object was found.

pub fn should_run(&self) -> bool

Returns true when live_bytes / max_live_bytes ≥ sweep_threshold_fraction.

pub fn mark_reachable(&mut self, now: u64) -> HashSet<GcObjectId>

BFS traversal from all roots and pinned objects.

Every reachable object gets last_marked = Some(now). Returns the set of reachable ids.

pub fn run_gc(&mut self, now: u64) -> StorageGcRun

Perform a full mark-and-sweep GC run.

Steps:

1. Mark all objects reachable from roots / pinned objects.
2. Sweep unreachable, unpinned, ref_count==0 objects.
3. Record and return a StorageGcRun.

pub fn live_bytes(&self) -> u64

Total bytes across all currently tracked objects.

pub fn reachable_bytes(&self, reachable: &HashSet<GcObjectId>) -> u64

Total bytes across the supplied reachable set.

pub fn object_count(&self) -> usize

Number of tracked objects.

pub fn root_count(&self) -> usize

Number of GC-root objects.

pub fn stats(&self) -> StorageGcStats

Return aggregate statistics.