Struct Cache 

pub struct Cache { /* private fields */ }

A thread-safe handle to an on-disk capsule cache. Cloning shares the same underlying cache.

Implementations

impl Cache

pub fn open(root: &Path, config: CacheConfig) -> Result<Cache, CacheError>

Open (or rebuild) a cache rooted at root with config.

Establishes root/{capsules,tmp}, reclaims any leftover tmp/*.part from an interrupted admission, then rebuilds the in-memory index by SCANNING capsules/ (disk is authoritative) and overlaying index.json for recency + pin state. A capsule file with no manifest entry is admitted with its identity recovered from the file and mtime-based recency; a manifest entry with no file is dropped.

pub fn put_file( &self, id: CapsuleIdentity, src: &Path, opts: PutOptions, ) -> Result<Admission, CacheError>

Admit the file at src under identity id. The file is stream-copied (never slurped), so this is the path for real (large) capsules. check_identity is IGNORED here (the body is not read).

pub fn put_bytes( &self, id: CapsuleIdentity, bytes: &[u8], opts: PutOptions, ) -> Result<Admission, CacheError>

Admit bytes under identity id. A convenience for small/test capsules — real capsules use Cache::put_file. With opts.check_identity, the bytes’ declared identity must equal id.

pub fn get(&self, id: &CapsuleIdentity) -> Option<CachedCapsule>

Fetch a cached capsule, marking it most-recently-used. None if not cached.

pub fn get_bytes( &self, id: &CapsuleIdentity, ) -> Result<Option<Vec<u8>>, CacheError>

Read a cached capsule’s bytes into memory (convenience for small/test capsules; real capsules stream from CachedCapsule::path). Updates recency. Ok(None) if not cached.

pub fn contains(&self, id: &CapsuleIdentity) -> bool

Whether id is currently cached.

pub fn holdings(&self) -> Vec<CapsuleIdentity>

Every capsule the cache currently holds — the node’s advertisable holdings.

pub fn remove(&self, id: &CapsuleIdentity) -> Result<bool, CacheError>

Remove a capsule (deleting its file + freeing its bytes). Returns whether it was present.

pub fn pin(&self, id: &CapsuleIdentity) -> Result<bool, CacheError>

Pin a capsule so eviction never reclaims it. Returns whether it was present (and is now pinned).

pub fn unpin(&self, id: &CapsuleIdentity) -> Result<bool, CacheError>

Unpin a capsule, making it eligible for eviction again. Returns whether it was present.

pub fn stats(&self) -> CacheStats

A snapshot of occupancy.

pub fn set_config(&self, config: CacheConfig) -> Result<Admission, CacheError>

Replace the configuration. Lowering max_bytes evicts (per the policy) until the cache fits the new capacity and returns the evicted set (the flywheel-retract signal).

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Cache

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Cache

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

Formats the value using the given formatter.