Module cache 

A shared byte budget for cached groups, repaid by write-time eviction.

Every group charges its cached bytes into a Pool through a crate-internal Charge, billed to its track’s Track account. The pool itself never evicts: it is a handful of atomic counters. While the pool is over capacity, each track accrues eviction debt as it writes (accrue), sized proportionally to what it wrote, and pays that debt by aborting its own oldest groups with Error::Evicted. Reclamation is therefore distributed across every writing track and converges on the capacity without any global eviction task.

Cross-track ordering comes from one statistic: the mean last-access time of the evictable population (every cached group except each track’s protected latest). A group accessed more recently than that mean is never evicted, so freshly read or fetched content in one track can’t die while another track holds staler content, and a track whose oldest group is staler than the mean accrues debt at double rate. Evicting old entries and inserting new ones both advance the mean, so the eviction frontier moves with cache turnover on its own.

The pool also owns the wall-clock LRU window (Pool::expiry): a non-latest group that nobody has read or written for that long is reclaimed, no matter what retention its track advertises. Track retention (max_age) is measured in media timestamps, so a congestion stall can’t age content out; the pool’s expiry is the orthogonal wall-clock bound that keeps unwatched content from pinning RAM.

Expiry is driven by Pool::gc, also called by each origin driver. Reads and writes clear the expiration timestamp without reading a clock. The next cleanup pass dates that activity at its supplied instant. Delayed cleanup extends retention; standalone pools must call gc too. Byte-pressure eviction still runs inline on writes.

A bare pool is inert by default (Pool::unbounded): publishers and subscribers that never set a capacity or expiry pay only a couple of atomic counters, and register nothing. A standalone origin enables DEFAULT_EXPIRY, while a relay creates one configured pool and shares it across every origin so the whole process caches into a single policy.

Structs

Config

The initial policy for a Pool.

Pool

A shared cache policy and byte budget; cloning shares both.

PoolWeak

A handle to a Pool that does not keep the budget alive.

Constants

DEFAULT_EXPIRY

Default idle window for standalone origins and relays.