Struct ConcurrentGdsfCache 

pub struct ConcurrentGdsfCache<K, V, S = DefaultHashBuilder> { /* private fields */ }

A thread-safe GDSF cache with segmented storage for high concurrency.

GDSF (Greedy Dual-Size Frequency) is designed for caching variable-size objects. The put method requires specifying the object size in addition to key and value.

Implementations

impl<K, V> ConcurrentGdsfCache<K, V, DefaultHashBuilder>

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

pub fn init( config: ConcurrentGdsfCacheConfig, hasher: Option<DefaultHashBuilder>, ) -> Self

Creates a new concurrent GDSF cache from a configuration.

This is the recommended way to create a concurrent GDSF cache.

Arguments

• config - The cache configuration specifying capacity, max size, and segments
• hasher - Optional custom hash builder. If None, uses the default hash builder.

impl<K, V, S> ConcurrentGdsfCache<K, V, S>

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

pub fn capacity(&self) -> usize

Returns the total capacity across all segments (in size units).

pub fn segment_count(&self) -> usize

Returns the number of segments in the cache.

pub fn len(&self) -> usize

Returns the total number of entries across all segments.

pub fn is_empty(&self) -> bool

Returns true if the cache contains no entries.

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

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

Gets a value from the cache.

This clones the value to avoid holding the lock. For zero-copy access, use get_with() instead.

pub fn get_with<Q, F, R>(&self, key: &Q, f: F) -> Option<R>

where K: Borrow<Q> + Clone, Q: ?Sized + Hash + Eq, F: FnOnce(&V) -> R,

Gets a value and applies a function to it while holding the lock.

This is more efficient than get() when you only need to read from the value, as it avoids cloning.

pub fn put(&self, key: K, value: V, size: u64) -> Option<Vec<(K, V)>>

where K: Clone,

Inserts a key-value pair with its size into the cache.

GDSF uses size for priority calculation. Use SIZE_UNIT (1) for count-based caching. Returns None if no entries were evicted. Returns Some(vec) containing all (key, value) pairs evicted from the cache as part of this operation to make room for the new entry.

Overwriting an existing key without triggering eviction returns None.

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

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

Removes a key from the cache, returning the value if it existed.

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

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

Checks if the cache contains a key without updating priority.

This is a pure existence check that does not update the entry’s priority or frequency.

Example

if cache.contains(&"key".to_string()) {
    println!("Key exists!");
}

pub fn peek<Q>(&self, key: &Q) -> Option<V>

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

Returns a clone of the value without updating priority or access metadata.

Unlike get(), this does NOT recalculate the entry’s GDSF priority or change its position. Returns a cloned value because the internal lock cannot be held across the return boundary.

Example

let value = cache.peek(&"key".to_string());

pub fn clear(&self)

Clears all entries from the cache.

pub fn current_size(&self) -> u64

Returns the current total size of cached content across all segments.

pub fn max_size(&self) -> u64

Returns the maximum content size the cache can hold across all segments.

Trait Implementations

impl<K, V, S> CacheMetrics for ConcurrentGdsfCache<K, V, S>

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

fn metrics(&self) -> BTreeMap<String, f64>

Returns all metrics as key-value pairs in deterministic order

fn algorithm_name(&self) -> &'static str

Algorithm name for identification

impl<K, V, S> Debug for ConcurrentGdsfCache<K, V, S>

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

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K: Send, V: Send, S: Send> Send for ConcurrentGdsfCache<K, V, S>

impl<K: Send, V: Send, S: Send + Sync> Sync for ConcurrentGdsfCache<K, V, S>