Struct BlockGarbageCollector 

pub struct BlockGarbageCollector { /* private fields */ }

Production-grade block-level garbage collector.

Supports mark-and-sweep, reference counting, tri-color, and generational policies. All operations run in O(V + E) where V = blocks, E = DAG edges.

Implementations

impl BlockGarbageCollector

pub fn set_clock(&mut self, secs: u64)

Override the internal clock (useful in tests).

pub fn cid_hash(cid: &BgcBlockCid) -> u64

Derive a deterministic u64 from a CID for internal purposes.

impl BlockGarbageCollector

pub fn new(config: BgcCollectorConfig) -> Self

Create a new collector with the given configuration.

impl BlockGarbageCollector

pub fn register_block( &mut self, cid: BgcBlockCid, size_bytes: u64, refs: Vec<BgcBlockCid>, ) -> Result<(), BgcError>

Register a new block.

refs lists the CIDs this block holds direct references to (children).

pub fn unregister_block(&mut self, cid: BgcBlockCid) -> Result<(), BgcError>

Unregister a block, removing it from the registry and edge map.

Returns Err(BlockIsPinned) if the block is explicitly pinned.

pub fn touch(&mut self, cid: &BgcBlockCid) -> Result<(), BgcError>

Touch a block’s last_accessed timestamp.

pub fn get_block(&self, cid: &BgcBlockCid) -> Option<&BgcBlockRecord>

Return an immutable reference to a block record.

impl BlockGarbageCollector

pub fn pin(&mut self, cid: BgcBlockCid) -> Result<(), BgcError>

Explicitly pin a block so it is never collected.

pub fn unpin(&mut self, cid: BgcBlockCid) -> Result<(), BgcError>

Remove the explicit pin from a block.

pub fn add_root(&mut self, cid: BgcBlockCid)

Add a CID to the GC root set (always considered live).

pub fn remove_root(&mut self, cid: &BgcBlockCid)

Remove a CID from the GC root set.

pub fn is_pinned(&self, cid: &BgcBlockCid) -> bool

Return true if the block is currently pinned.

pub fn is_root(&self, cid: &BgcBlockCid) -> bool

Return true if the block is a GC root.

impl BlockGarbageCollector

pub fn increment_ref(&mut self, cid: &BgcBlockCid) -> Result<(), BgcError>

Increment the reference count of a block.

pub fn decrement_ref(&mut self, cid: &BgcBlockCid) -> Result<bool, BgcError>

Decrement the reference count of a block.

Returns Ok(true) if the block is now at ref_count == 0 (candidate for collection); Ok(false) otherwise.

impl BlockGarbageCollector

pub fn mark_phase(&self) -> BTreeSet<BgcBlockCid>

Mark phase: BFS from all roots and pinned blocks.

Returns the set of reachable (live) CIDs.

impl BlockGarbageCollector

pub fn sweep_phase( &mut self, reachable: &BTreeSet<BgcBlockCid>, ) -> BgcSweepResult

Sweep phase: remove all blocks not in reachable.

Respects min_age_secs and dry_run from the config.

impl BlockGarbageCollector

pub fn run_gc(&mut self, policy: BgcGcPolicy) -> Result<BgcGcResult, BgcError>

Run a complete GC cycle using the given policy.

impl BlockGarbageCollector

pub fn collect_orphans(&self, min_age_secs: u64) -> Vec<BgcBlockCid>

Return all CIDs that are unreachable, not pinned, and older than min_age_secs. Does not remove them.

pub fn collect_orphans_default(&self) -> Vec<BgcBlockCid>

Collect orphans using the internal min_age_secs from config.

impl BlockGarbageCollector

pub fn gc_stats(&self) -> BgcCollectorStats

Compute current collector statistics.

pub fn block_count(&self) -> usize

Return the number of registered blocks.

pub fn log_len(&self) -> usize

Return the number of GC log entries.

pub fn log_entries(&self) -> impl Iterator<Item = &BgcGcLogEntry>

Iterate over log entries (most recent last).

pub fn gc_log(&self) -> &VecDeque<BgcGcLogEntry>

Return the full GC log as a slice-like iterator.

impl BlockGarbageCollector

pub fn random_cid(&mut self) -> BgcBlockCid

Generate a pseudo-random CID for testing (uses xorshift).

pub fn cid_from_bytes(data: &[u8]) -> BgcBlockCid

Compute a deterministic CID from raw bytes (used in tests).

pub fn config(&self) -> &BgcCollectorConfig

Return the config (read-only).

pub fn config_mut(&mut self) -> &mut BgcCollectorConfig

Mutate the config (e.g. flip dry_run in tests).

pub fn update_edges( &mut self, cid: BgcBlockCid, new_refs: Vec<BgcBlockCid>, ) -> Result<(), BgcError>

Update edges for an already-registered block.

pub fn children_of(&self, cid: &BgcBlockCid) -> &[BgcBlockCid]

Return children of a block (direct DAG edges).

pub fn reconcile_pin_flags(&mut self)

Set the is_pinned flag to match the pin set (reconcile).

pub fn promote_generation(&mut self)

Promote all blocks in generation 0 to generation 1.

pub fn compact_edges(&mut self)

Compact: remove all edge entries for blocks that no longer exist.

pub fn clear(&mut self)

Clear entire state — useful in tests.

pub fn all_cids(&self) -> Vec<BgcBlockCid>

Return the set of all registered CIDs.

pub fn reachable_set(&self) -> BTreeSet<BgcBlockCid>

Return the reachable set (live blocks) without modifying state.