Struct SizedCache 

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

Available on crate feature std only.

A cache bounded by total byte-weight rather than entry count.

Each value is weighed by a user-supplied fn(&V) -> usize at insert time. The cache evicts least-recently-accessed entries until the new entry fits within max_weight.

An entry whose own weight exceeds max_weight is silently rejected: the insert returns None and the value is dropped. (No cache could honour such a request.)

Implementation

Arena-backed doubly-linked list with O(1) promote and O(1) eviction (eviction may loop until enough weight is reclaimed). Unlike the other cache types in this crate, SizedCache is not sharded — splitting the weight budget across shards would silently reject values that fit the global budget, which is the wrong contract for a byte-bound cache. Internal layout may evolve in future minor releases without changing this public surface.

Choice of unit

usize is unitless — the weigher decides. Common choices:

• |v: &Vec<u8>| v.len() — track payload bytes
• |v: &String| v.len() + std::mem::size_of::<String>() — include header
• |_: &T| std::mem::size_of::<T>() — fixed-size approximation

The weigher is a plain function pointer, not a closure — captured state would force Box<dyn Fn>-style indirection on every weigh call. If your weighing logic needs state, hoist it into the value itself.

Capacity reporting

capacity on SizedCache returns max_weight, not entry count. Use total_weight to query the dynamic in-use weight and max_weight as the explicit alias.

Example

use cache_mod::{Cache, SizedCache};

fn weigh(payload: &Vec<u8>) -> usize { payload.len() }

let cache: SizedCache<&'static str, Vec<u8>> =
    SizedCache::new(1024, weigh).expect("max_weight > 0");

cache.insert("small", vec![0u8; 64]);
assert_eq!(cache.total_weight(), 64);

Implementations

impl<K, V> SizedCache<K, V>

where K: Eq + Hash + Clone, V: Clone,

pub fn new( max_weight: usize, weigher: fn(&V) -> usize, ) -> Result<Self, CacheError>

Creates a cache with the given byte-weight ceiling.

Returns CacheError::InvalidCapacity if max_weight == 0.

Example

use cache_mod::SizedCache;

fn weigh(s: &String) -> usize { s.len() }

let cache: SizedCache<u32, String> =
    SizedCache::new(4096, weigh).expect("max_weight > 0");

pub fn max_weight(&self) -> usize

The configured byte-weight ceiling.

pub fn total_weight(&self) -> usize

Current total weight of all cached entries.

Trait Implementations

impl<K, V> Cache<K, V> for SizedCache<K, V>

where K: Eq + Hash + Clone, V: Clone,

fn capacity(&self) -> usize

For SizedCache, capacity is the configured max_weight — see the type-level docs.

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

Returns the value associated with key, if any, and counts as an access for the purposes of the eviction policy.

fn insert(&self, key: K, value: V) -> Option<V>

Inserts value under key. Returns the previously-stored value if key was already present.

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

Removes the entry for key and returns the value if present.

fn contains_key(&self, key: &K) -> bool

Returns true if the cache currently holds an entry for key.

fn len(&self) -> usize

Number of entries currently stored.

fn clear(&self)

Removes every entry. Capacity is preserved.

fn is_empty(&self) -> bool

Returns true when the cache holds no entries.