Struct WriteBehindCache 

pub struct WriteBehindCache<S: BackingStore> { /* private fields */ }

Write-behind cache that defers writes to a BackingStore until flush is called.

Dirty tracking

Every put marks the entry as dirty. flush iterates all dirty entries, writes them to the backing store, and clears the dirty flag. flush_if_needed only flushes when the dirty count exceeds a threshold.

Eviction

Entries are evicted in insertion order (FIFO) when the cache exceeds capacity. Dirty entries are flushed before eviction so data is never silently lost.

Implementations

impl<S: BackingStore> WriteBehindCache<S>

pub fn new(capacity: usize, store: S) -> Self

Create a new write-behind cache with the given capacity and backing store.

pub fn put( &mut self, key: S::Key, value: S::Value, ) -> Result<(), WriteBehindError<S::Error>>

Insert or update (key, value). The entry is marked dirty.

If the cache is at capacity, the oldest entry is evicted (and flushed if dirty).

pub fn get( &mut self, key: &S::Key, ) -> Result<Option<&S::Value>, WriteBehindError<S::Error>>

Look up key. On a cache miss, attempts to load from the backing store (read-through).

pub fn delete( &mut self, key: &S::Key, ) -> Result<bool, WriteBehindError<S::Error>>

Remove key from the cache and the backing store.

pub fn flush(&mut self) -> Result<usize, WriteBehindError<S::Error>>

Flush all dirty entries to the backing store.

Returns the number of entries flushed.

pub fn flush_if_needed( &mut self, threshold: usize, ) -> Result<usize, WriteBehindError<S::Error>>

Flush only if the number of dirty entries exceeds threshold.

pub fn dirty_count(&self) -> usize

Return the number of dirty entries.

pub fn stats(&self) -> WriteBehindStats

Return a statistics snapshot.

pub fn store(&self) -> &S

Return a shared reference to the backing store.

pub fn store_mut(&mut self) -> &mut S

Return a mutable reference to the backing store.

pub fn is_dirty(&self, key: &S::Key) -> bool

Returns true if the entry for key is dirty.

pub fn contains(&self, key: &S::Key) -> bool

Returns true if the cache contains an entry for key.

pub fn len(&self) -> usize

Return the number of entries in the cache.

pub fn is_empty(&self) -> bool

Return true when the cache is empty.

pub fn flush_older_than( &mut self, max_age: Duration, ) -> Result<usize, WriteBehindError<S::Error>>

Flush only entries whose dirty age exceeds max_age.

“Dirty age” is the time since the entry was last modified. This allows the caller to implement time-based flush policies (e.g. flush all entries older than 5 seconds).

Returns the number of entries flushed.

pub fn dirty_keys(&self) -> Vec<S::Key>

Return a list of all dirty keys.

pub fn mark_clean(&mut self, key: &S::Key) -> bool

Mark an entry as clean without writing to the backing store.

Useful when the caller knows the backing store is already up to date (e.g. after an external write). Returns true if the entry was dirty and is now clean.

pub fn capacity(&self) -> usize

Return the capacity of the cache.