Struct WrDiskCache 

pub struct WrDiskCache { /* private fields */ }

Write-back disk cache with LRU eviction and bounded memory usage.

WrDiskCache buffers disk writes before flushing them to persistent storage. It uses an LRU (Least Recently Used) eviction policy that never evicts dirty (unflushed) entries, guaranteeing no data loss under memory pressure.

Entries are keyed by their start offset in a BTreeMap, enabling O(log n) range lookups for read(). LRU ordering is preserved via a per-entry monotonic seq number — during eviction the clean entry with the smallest seq (oldest insertion) is removed first.

Implementations

impl WrDiskCache

pub fn new(max_size_mb: usize) -> Self

Create a new WrDiskCache with a maximum size specified in megabytes.

Arguments

• max_size_mb - Maximum cache capacity in megabytes

Example

let cache = WrDiskCache::new(16); // 16 MB max

pub fn with_max_size_bytes(max_size_bytes: usize) -> Self

Create a new WrDiskCache with a maximum size specified in bytes.

This provides finer-grained control than WrDiskCache::new which takes megabytes.

Arguments

• max_size_bytes - Maximum cache capacity in bytes

pub fn max_size_bytes(&self) -> usize

Returns the maximum cache size in bytes.

pub fn current_size_bytes(&self) -> usize

Returns the current approximate cache size in bytes (lock-free).

Note: This is an atomic snapshot and may be slightly stale if a write or eviction is concurrently in progress.

pub async fn write(&self, offset: u64, data: Bytes) -> Result<()>

Write data at the given offset into the cache.

If writing this entry would exceed max_size_bytes, LRU eviction is triggered. Only clean (already-flushed) entries are eligible for eviction — dirty entries are never evicted to prevent data loss. If insufficient clean entries exist to make room, the cache may temporarily exceed its limit until a flush occurs.

Zero-Copy

This method accepts bytes::Bytes which enables zero-copy slicing. The caller can pass a slice of a larger buffer without copying.

pub async fn read(&self, offset: u64, length: u64) -> Result<Option<Bytes>>

Read cached data at the given offset and length.

Returns Some(data) if the requested range is fully contained in a cached entry, or None if the data is not in the cache.

Complexity

O(log n) — a single BTreeMap::range lookup finds the unique candidate entry (the one with the largest start key <= offset). If that entry does not fully cover [offset, offset+length), no other entry can (entries with smaller keys end before offset; entries with larger keys start after offset).

Zero-Copy

Returns bytes::Bytes slice instead of Vec<u8>, avoiding memory allocation.

pub async fn flush(&self) -> Result<Vec<CacheEntry>>

Flush all dirty entries, returning them for persistence.

After flushing, entries remain in the cache but are marked as clean (eligible for future LRU eviction). The caller is responsible for writing the returned entries to durable storage.

The returned CacheEntry clones are O(1): bytes::Bytes is an Arc-backed buffer, so cloning only bumps a reference count — no data copy occurs.

pub async fn clear(&self) -> Result<()>

Clear all entries from the cache and reset size tracking.

pub async fn size(&self) -> usize

Returns the current total size of cached data in bytes.

pub async fn is_empty(&self) -> bool

Returns true if the cache contains no entries.

pub async fn count(&self) -> usize

Returns the number of entries in the cache.

pub async fn dirty_count(&self) -> usize

Returns the number of dirty (unflushed) entries.

Trait Implementations

impl Default for WrDiskCache

fn default() -> Self

Returns the “default value” for a type.