Struct CacheBlockLifecycle 

pub struct CacheBlockLifecycle { /* private fields */ }

Canonical logical ownership state for one backend cache session.

Backends keep concrete arrays, buffers, files, and completion objects in a separate storage map keyed by CacheBlockId. This catalog is the sole owner of leases, access order, protected-prefix status, and mutable tails.

Implementations

impl CacheBlockLifecycle

pub const fn new() -> Self

Creates an empty cache-session lifecycle.

pub fn insert( &mut self, id: CacheBlockId, protected_prefix: bool, ) -> Result<(), CacheLifecycleError>

Registers a newly materialized immutable block.

pub fn remove(&mut self, id: &CacheBlockId) -> Result<(), CacheLifecycleError>

Removes an unleased block from logical ownership.

pub fn replace( &mut self, removals: &[(CacheBlockId, usize)], replacement: Option<(CacheBlockId, bool)>, tail_layer: usize, tail: MutableCacheTail, ) -> Result<(), CacheLifecycleError>

Atomically replaces a set of blocks and updates one mutable tail.

The expected lease count makes a caller-owned truncation lease explicit: validation completes before any logical state is changed.

pub fn acquire(&mut self, id: &CacheBlockId) -> Result<(), CacheLifecycleError>

Acquires one exact logical lease and records demand access.

pub fn release(&mut self, id: &CacheBlockId) -> Result<(), CacheLifecycleError>

Releases one exact logical lease.

pub fn lease_count( &self, id: &CacheBlockId, ) -> Result<usize, CacheLifecycleError>

Returns the exact lease count for a block.

pub fn is_leased(&self, id: &CacheBlockId) -> Result<bool, CacheLifecycleError>

Returns whether a block currently has any logical owner.

pub fn first_leased(&self) -> Option<&CacheBlockId>

Returns the first leased block in stable identity order.

pub fn is_protected_prefix( &self, id: &CacheBlockId, ) -> Result<bool, CacheLifecycleError>

Returns whether the block is protected as an immutable prefix.

pub fn eviction_candidate( &self, candidates: impl IntoIterator<Item = CacheBlockId>, required: Option<&CacheBlockId>, recent_per_layer: usize, policy: CacheEvictionPolicy, ) -> Result<Option<CacheBlockId>, CacheLifecycleError>

Selects one eviction victim from backend-supplied physically eligible IDs.

pub fn recent_protection_counts( &self, candidates: impl IntoIterator<Item = CacheBlockId>, recent_per_layer: usize, ) -> Result<BTreeMap<usize, u64>, CacheLifecycleError>

Counts unprotected blocks retained by a per-layer recent window.

pub fn set_tail( &mut self, layer: usize, tail: MutableCacheTail, ) -> Option<MutableCacheTail>

Replaces one layer’s mutable tail, returning the prior state for rollback.

pub fn restore_tail(&mut self, layer: usize, tail: Option<MutableCacheTail>)

Restores a prior tail after a failed backend admission.

pub fn tail(&self, layer: usize) -> Option<MutableCacheTail>

Returns one layer’s mutable tail.

pub fn tails(&self) -> impl Iterator<Item = (usize, MutableCacheTail)> + '_

Iterates mutable tails in stable layer order.

pub fn clear(&mut self) -> Result<(), CacheLifecycleError>

Clears all blocks and tails only when no lease is active.

Trait Implementations

impl Debug for CacheBlockLifecycle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CacheBlockLifecycle

fn default() -> CacheBlockLifecycle

Returns the “default value” for a type.