Struct PageCache 

pub struct PageCache { /* private fields */ }

Bounded, MVCC-safe page cache with frequency-aware CLOCK eviction and an optional persistent backing directory.

When a crate::memory::MemoryGovernor is attached (with_governor) the cache reports its live bytes to the governor (S1E-003): every insert/eviction resizes one per-cache crate::memory::Reservation, the governor’s denial of growth sheds the coldest entries, and evict_reclaimable is the entry point the governor drives under escalation step 2. Without a governor the cache behaves exactly as before.

Implementations

impl PageCache

pub fn new(capacity_bytes: u64) -> Self

pub fn with_governor(self, governor: MemoryGovernor, class: MemoryClass) -> Self

Attach a crate::memory::MemoryGovernor (S1E-003): the cache keeps one reservation sized to its live bytes, so the governor’s per-class accounting always reflects this cache, and growth the governor denies sheds the coldest entries. Any already-cached bytes (e.g. loaded by with_persistence) are accounted — and evicted down if the governor cannot grant them — immediately.

pub fn stats(&self) -> CacheStats

Cumulative hit/miss counts since construction (or the last reset_stats). Cheap (Relaxed atomic loads).

pub fn reset_stats(&self)

Zero the hit/miss counters (e.g. to measure a single query’s locality).

pub fn with_persistence(self, dir: PathBuf) -> Self

Enable persistence: load any cached pages from <dir> and spill future evictions/inserts there. Files are raw page bytes (ciphertext when the table is encrypted).

pub fn insert(&mut self, page: CachedPage)

Insert a page (replaces any entry with the same key). Spills to the persistent backing directory when enabled.

pub fn get( &mut self, content_hash: &[u8; 32], snapshot: Snapshot, ) -> Option<Bytes>

Fetch the page visible to snapshot (the entry’s committed epoch must be <= snapshot.epoch), promoting its frequency. O(1).

pub fn try_get( &self, content_hash: &[u8; 32], snapshot: Snapshot, ) -> Option<Bytes>

Non-blocking probe used by the parallel (rayon) read path: returns a hit without contending on a write lock when one is held. Some on hit; None on miss (or if the value is not visible to snapshot). The caller treats any None as “fall through to disk”.

pub fn used_bytes(&self) -> u64

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn flush_to_disk(&self)

Flush all live entries to the persistent backing dir (best-effort).

pub fn evict_reclaimable(&mut self, budget: u64) -> u64

Governor entry point (S1E-003 step 2): evict at least budget bytes of reclaimable entries (coldest first), returning the bytes actually freed. Without an attached governor the cache is self-bounded and this is a plain manual trim.