Struct L1Cache 

pub struct L1Cache { /* private fields */ }

In-process cache with per-entry TTL, backed by quick_cache.

Used as the L1 layer in the dual-layer cache architecture. Clone is cheap and shares the underlying store.

It never holds more than capacity entries. quick_cache evicts with a scan-resistant policy (a CLOCK-Pro variant close to S3-FIFO): a run of keys written once and never read does not flush the entries being read, as it would under LRU. Capacity is split into shards, capacity / 128 rounded down to a power of two, from 1 to 64 (4 at the default 1,000), and a full shard evicts even while others have room.

No read returns an expired entry. An expired entry leaves memory when a read finds it, when eviction reaches it, or when Self::entry_count or Self::run_pending_tasks sweeps; until then it counts against capacity.

Implementations

impl L1Cache

pub fn new(capacity: usize) -> Self

Create a new L1 cache that holds at most capacity entries.

pub fn get(&self, key: &str) -> Option<Vec<u8>>

Retrieve cached bytes by key, or None if absent or expired.

pub fn get_with_swr(&self, key: &str, threshold_ratio: f64) -> L1SwrRead

Retrieve cached bytes with stale-while-revalidate classification.

An entry is fresh until it has lived threshold_ratio of its own TTL (±10% jitter, drawn once when the entry is inserted so a hot read never touches the entropy source), stale from then until hard expiry, and a miss after that. The freshness window derives from the TTL the entry was inserted with: a direct write carries the caller’s full TTL, an L2 backfill carries the capped backfill TTL — see CacheKit’s L1 documentation.

Semantics mirror cachekit-py’s swr_threshold_ratio (elapsed lifetime > ratio × TTL ⇒ stale). Hard expiry is checked on every read: an expired entry is never returned, so SWR can never serve past it.

This is a pure read — it does not track refresh state. Callers own refresh scheduling and deduplication (the #[cachekit] macro uses CacheKit::single_flight).

pub fn set(&self, key: &str, value: &[u8], ttl: Duration)

Insert or overwrite an entry with the given TTL.

An overwrite is a new entry: its TTL and freshness window start now.

pub fn delete(&self, key: &str)

Remove an entry by key.

pub fn entry_count(&self) -> u64

Number of entries currently held.

Sweeps expired entries first (see Self::run_pending_tasks), so the figure is exact at the time of the call. The sweep visits every entry: poll this, don’t put it on a hot path.

pub fn run_pending_tasks(&self)

Remove every expired entry now, one shard at a time.

Reads never return an expired entry, so this only frees the memory and the capacity they hold. It visits every entry, holding each shard’s write lock while it walks that shard.

Trait Implementations

impl Clone for L1Cache

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.