Struct BlobCacheSweeper 

pub struct BlobCacheSweeper;

Stateless namespace for sweeper operations against a BlobCache.

The sweeper holds no state of its own; every method is a free-function over &BlobCache. This keeps the surface easy to call from admin handlers, the runtime scheduler, and tests without owning a sweeper instance.

Implementations

impl BlobCacheSweeper

pub fn sweep_expired(cache: &BlobCache, limit: SweepLimit) -> SweepReport

Bounded sweep of expired L1 and L2 entries.

Pops due L1 deadlines across shards, revalidates them against the current entry, and evicts only entries whose effective expiry elapsed. Honors limit precisely.

Concurrency

One shard write lock is held at a time. A read on that shard may wait briefly; readers on other shards continue unimpeded. Persistent L2 deletion is published as one bounded WAL batch after the L1 locks are released.

pub fn reclaim_orphans(cache: &BlobCache, limit: SweepLimit) -> OrphanReport

Bounded reclamation of L2 orphan blob chains.

Orphan chains arise when a writer flushes the blob bytes to L2 pages but is killed before the metadata B+ tree commit (see the WAL-ordering note in docs/perf/blob-cache-l2-spike.md). Recovery cannot tell these pages apart from a successful write without cross-checking the metadata catalog, so they accumulate as wasted L2 capacity until the sweeper reclaims them.

The algorithm (once accessor #2 lands):

1. Walk the L2 free-list of allocated blob chains (cache.l2_blob_chains() — to-be-added).
2. For each chain root, look up the metadata B+ tree (cache.for_each_l2_record) and check whether any record points at this root.
3. Chains with no metadata reference are orphans — free their pages via the L2 API and accumulate bytes_reclaimed.

Concurrency

Same contract as BlobCacheSweeper::sweep_expired.

pub fn flush_namespace( cache: &BlobCache, namespace: &str, ) -> NamespaceFlushReport

Foreground-fast namespace flush.

Delegates to BlobCache::invalidate_namespace, which is O(1): it only bumps a per-namespace generation counter. Cached entries with the old generation become invisible immediately and are physically removed by later cache access or by BlobCacheSweeper::sweep_expired.

Foreground-fast contract

Returns within ~100 µs typical. The elapsed_micros field on the returned NamespaceFlushReport makes the contract observable so admin endpoints can alert on regressions.

Generation reporting

generation_before and generation_after are reported on a best-effort basis. Because BlobCache does not expose a public generation accessor, the sweeper reports them as (0, 0) when the flush call signals “namespace did not exist” and (0, 0) when it signals success — placeholder values until a current_generation public accessor is added (see flag #2). The namespace and elapsed_micros fields are accurate today.