Struct UnifiedCache 

pub struct UnifiedCache<K, V> { /* private fields */ }

Unified cache backend with configurable eviction policies

Uses interior mutability via RwLock to allow &self methods, enabling easier use in concurrent contexts without borrow checker conflicts.

Implementations

impl<K, V> UnifiedCache<K, V>

where K: CacheKey, V: CacheValue,

pub fn new( max_size: usize, ttl: Duration, eviction_policy: EvictionPolicy, ) -> Self

pub fn get(&self, key: &K) -> Option<Arc<V>>

Get value from cache with zero-copy access by default.

Uses a read-first fast path and only attempts a non-blocking write lock for best-effort metadata/stat updates.

pub fn get_owned(&self, key: &K) -> Option<V>

Get owned value (explicitly clones when needed)

pub fn insert(&self, key: K, value: V, size_bytes: u64)

Insert value into cache with automatic eviction

pub fn stats(&self) -> CacheStats

Get cache statistics (returns owned clone)

pub fn clear(&self)

Clear all entries

pub fn remove(&self, key: &K)

Remove a single cache entry by exact key.

pub fn len(&self) -> usize

Get current size

pub fn is_empty(&self) -> bool

pub fn invalidate_prefix(&self, prefix: &str)

Invalidate cache entries matching a key prefix (selective eviction) This replaces the old “clear entire cache” behavior with granular eviction

Example

cache.invalidate_prefix("grep_file:/workspace/src/");
// Only removes entries for that specific file, not entire cache

pub fn invalidate_path(&self, path: &str)

Invalidate entries for a specific target path (e.g., file path) This is a convenience wrapper for file-based invalidation

Example

cache.invalidate_path("/workspace/src/main.rs");
// Removes all cache entries related to this file

pub fn invalidate_suffix(&self, suffix: &str)

Invalidate cache entries matching a key suffix (selective eviction)

Example

cache.invalidate_suffix(":/workspace/src/main.rs");
// Only removes entries for that specific file

pub fn invalidate_containing(&self, substring: &str)

Invalidate cache entries containing a substring (selective eviction)

Example

cache.invalidate_containing("/workspace/src/main.rs");
// Removes entries where the cache key contains this path

pub fn remove_where<F>(&self, predicate: F) -> usize

where F: FnMut(&K) -> bool,

Remove all entries that satisfy a predicate.

Returns the number of removed entries.

pub fn total_memory_bytes(&self) -> u64

Get total memory used by cache in bytes

pub fn estimate_entry_cost(entry: &CacheEntry<V>) -> u64

Estimate entry cost in bytes (for memory-aware decisions) This is a heuristic based on entry metadata

pub fn reduce_ttl(&self, factor: f64) -> Duration

Reduce TTL for all entries in cache (for pressure-based tuning) Returns the new TTL that was set

pub fn evict_under_pressure(&self, target_reduction_percent: u32) -> usize

Evict entries under memory pressure (aggressive cleanup)

When memory pressure increases:

1. Remove all expired entries first
2. Evict least useful entries until target percentage reached
3. Use access count and age for ranking

pub fn clear_least_used(&self, percent_to_clear: u32) -> usize

Clear a percentage of least-used entries (for aggressive cleanup under critical pressure) Returns number of entries removed

pub fn entries_by_usefulness(&self) -> Vec<(K, CacheEntry<V>)>

Get entries sorted by “usefulness” (access count and recency) Higher score = more useful (keep these)