Struct SieveCache 

pub struct SieveCache<K, V, S = RandomState> { /* private fields */ }

A sharded, weighted, thread-safe SIEVE cache.

Implementations

impl<K, V, S> SieveCache<K, V, S>

pub const DEFAULT_SHARDS: usize = 256

Default power-of-two shard count used by SieveCache::new.

impl<K, V> SieveCache<K, V, RandomState>

where K: Eq + Hash + Clone, V: Send + Sync + 'static,

pub fn new(total_capacity_bytes: usize) -> Self

Creates a cache with Self::DEFAULT_SHARDS shards.

total_capacity_bytes is split across shards, with any remainder assigned to the lowest-index shards.

pub fn with_shards(total_capacity_bytes: usize, num_shards: usize) -> Self

Creates a cache with an explicit shard count.

Panics

Panics if num_shards == 0 or if num_shards is not a power of two.

impl<K, V, S> SieveCache<K, V, S>

where K: Eq + Hash + Clone, V: Send + Sync + 'static, S: BuildHasher + Clone,

pub fn with_hasher( total_capacity_bytes: usize, num_shards: usize, hash_builder: S, ) -> Self

Creates a cache with an explicit shard count and hash builder.

total_capacity_bytes is divided across shards as evenly as possible.

Panics

Panics if num_shards == 0 or if num_shards is not a power of two.

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

Inserts or replaces key with a caller-supplied weighted charge.

Returns the previous value if the key was already present.

If the insert pushes the shard over capacity, eviction runs before this call returns. An oversized entry may therefore be admitted and then immediately evicted.

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

Looks up key, marks the entry visited, and returns a shared handle.

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

Removes key if present and returns the removed value.

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

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

Removes all entries matching predicate and returns the number removed.

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

Returns true if key is currently present.

pub fn len(&self) -> usize

Returns the current number of live entries across all shards.

pub fn is_empty(&self) -> bool

Returns true when the cache has no live entries.

pub fn total_charge(&self) -> usize

Returns the current total weighted charge across all shards.

pub fn total_capacity(&self) -> usize

Returns the configured total weighted capacity.

pub fn shard_count(&self) -> usize

Returns the number of shards in the cache.

pub fn shard_usage(&self, idx: usize) -> (usize, usize)

Returns (used_charge, capacity) for shard idx.

Panics

Panics if idx >= self.shard_count().