Struct ValueCache 

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

A concurrent cache with efficient eviction and single-allocation guarantees.

Backed by quick_cache (S3-FIFO eviction) for bounded hot-path caching, plus a lock-free papaya::HashMap weak index for deduplication. Together they guarantee that at most one Arc<V> allocation exists per key at any time.

A background task periodically sweeps dead Weak entries from the index to prevent unbounded memory growth.

Implementations

impl<K, V> ValueCache<K, V>

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

pub fn new(name: &'static str, size: usize, cleanup_interval_secs: u64) -> Self

Creates a new ValueCache with the given instance name (used as the cache metric label), bounded-cache capacity, and cleanup interval for the weak-reference index.

pub fn name(&self) -> &'static str

Returns the instance name of this cache.

pub fn len(&self) -> usize

Returns the number of entries currently held in the bounded cache.

This is the live occupancy (excludes the weak dedup index), and is periodically sampled as the value_cache_entries gauge for the occupancy-vs-capacity diagnosis.

pub fn is_empty(&self) -> bool

Returns true if the bounded cache currently holds no entries.

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

Inserts a value into the cache, returning the canonical crate::Arc.

The value is wrapped in Arc internally. If a live Arc for this key already exists (held by another consumer), the existing allocation is reused and the new value is dropped.

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

Removes a value from the bounded cache.

The weak index entry is intentionally kept — another consumer may still hold an Arc to this value, and the weak index must be able to deduplicate against it. Dead weak entries are cleaned up by the background task.

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

Returns an crate::Arc to the value, checking both the bounded cache and the weak index.

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

Returns true if the value exists in either the bounded cache or the weak index (with a live allocation).

pub fn cleanup_dead_entries(&self)

Removes all dead Weak entries from the weak index.

impl<V: Clone + Send + Sync + 'static> ValueCache<CryptoHash, V>

pub fn insert_hashed<T>(&self, value: Cow<'_, Hashed<T>>) -> Arc<V>

where T: Clone, V: From<Hashed<T>>,

Inserts a value constructed from a Hashed<T> into the cache, keyed by its hash, returning the canonical Arc<V>.

The value is wrapped in a Cow so that it is only cloned if it needs to be inserted in the cache.

pub fn insert_all_hashed<'a, T>( &self, values: impl IntoIterator<Item = Cow<'a, Hashed<T>>>, )

where T: Clone + 'a, V: From<Hashed<T>>,

Inserts multiple values constructed from Hashed<T>s into the cache.