Struct SizeBoundedMap 

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

A lock-free, size-bounded concurrent map.

Reads and writes go through a papaya HashMap; the approximate total size is tracked in an AtomicUsize. Eviction is approximate and happens at insert time under the caller’s control (see Self::evict_until_freed), which keeps get entirely lock-free.

Implementations

impl<K, V> SizeBoundedMap<K, V>

where K: Hash + Eq + Clone,

pub fn new(max_size_bytes: usize) -> Self

Creates a new map with the specified maximum size in bytes.

A max_size_bytes of 0 disables the cache: lookups always miss and inserts are no-ops.

pub fn is_disabled(&self) -> bool

Returns true when the cache is disabled (max_size_bytes == 0).

pub fn max_size(&self) -> usize

Returns the configured maximum size in bytes.

pub fn current_size(&self) -> usize

Returns the current approximate accounted size in bytes.

pub fn len(&self) -> usize

Returns the number of entries in the map.

pub fn is_empty(&self) -> bool

Returns true if the map is empty.

pub fn with_entry<Q, R>( &self, key: &Q, f: impl FnOnce(&Entry<V>) -> R, ) -> Option<R>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Applies f to the entry for key, if present.

Returns None when the key is absent or the cache is disabled. This gives callers access to the entry’s bookkeeping (e.g. inserted_at for TTL checks) without cloning more than they need.

pub fn insert_weighted( &self, key: K, value: V, size_bytes: usize, ) -> (Option<V>, usize)

where V: Clone,

Inserts value accounted at size_bytes, timestamped now.

See Self::insert_weighted_at.

pub fn insert_weighted_at( &self, key: K, value: V, size_bytes: usize, inserted_at: Instant, ) -> (Option<V>, usize)

where V: Clone,

Inserts value accounted at size_bytes with an explicit insertion timestamp (exposed for TTL tests that need to backdate entries).

If an entry already existed for this key, its accounted size is subtracted first so the running total reflects the replacement rather than ratcheting upward on every overwrite.

Returns the replaced value (if any) and the new approximate total size. Eviction is not performed here; callers decide if and how to evict based on the returned total (see Self::evict_until_freed).

pub fn claim_or<R>( &self, key: K, value: V, size_bytes: usize, decide: impl Fn(&Entry<V>) -> Option<R>, ) -> Claim<R>

where V: Clone,

Atomically installs value for key unless an existing entry is kept.

decide is consulted for an entry that is already present: it returns Some(reason) to keep that entry (nothing is written, reason is handed back) or None to replace it. A vacant slot is always claimed.

The read-modify-write is a single papaya compare-and-swap, so of many concurrent callers exactly one claims a given slot. A get followed by an insert cannot promise that: every caller can observe the vacancy and every caller then claims it, which is how single-flight guards leak duplicate producers.

decide may run more than once (the CAS retries when the entry changes underneath it), so it must be free of side effects.

When the cache is disabled nothing is stored and every caller is told it claimed the slot — with no storage there is nothing to deduplicate on.

pub fn remove_if(&self, key: K, predicate: impl Fn(&Entry<V>) -> bool) -> bool

Removes the entry for key when predicate accepts it, adjusting the accounted total. Returns whether an entry was removed.

The removal is a single atomic compare-and-remove, which is what makes this safe for withdrawing a marker a caller owns: if another writer has already replaced the entry, predicate sees the new value and can decline, so a concurrent legitimate write is never clobbered.

pub fn evict_until_freed<P: Ord>( &self, target_bytes: usize, priority: impl Fn(&K, &Entry<V>) -> Option<P>, ) -> EvictionStats

Removes evictable entries in ascending priority order until at least target_bytes have been freed (or no candidates remain).

priority returns Some(order_key) for evictable entries — smaller keys are evicted first — and None for entries that must be kept.