Struct GdsfCache

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

An implementation of a Greedy Dual-Size Frequency (GDSF) cache.

GDSF combines frequency, size, and aging to make eviction decisions. Items with higher frequency-to-size ratios and recent access patterns are prioritized for retention in the cache.

Examples

use cache_rs::gdsf::GdsfCache;
use core::num::NonZeroUsize;

// Create a GDSF cache with capacity 3
let mut cache = GdsfCache::new(NonZeroUsize::new(3).unwrap());

// Add items with different sizes
cache.put("small", 1, 1);  // key="small", value=1, size=1
cache.put("large", 2, 5);  // key="large", value=2, size=5
cache.put("medium", 3, 3); // key="medium", value=3, size=3

// Access items to increase their frequency
assert_eq!(cache.get(&"small"), Some(1));
assert_eq!(cache.get(&"small"), Some(1)); // Higher frequency

Implementations

impl<K: Hash + Eq, V: Clone, S: BuildHasher> GdsfCache<K, V, S>

pub fn with_hasher(cap: NonZeroUsize, hash_builder: S) -> Self

Creates a new GDSF cache with the specified capacity and hash builder.

Examples

use cache_rs::gdsf::GdsfCache;
use core::num::NonZeroUsize;
use std::collections::hash_map::RandomState;

let cache: GdsfCache<&str, u32, _> = GdsfCache::with_hasher(
    NonZeroUsize::new(10).unwrap(),
    RandomState::new()
);

pub fn cap(&self) -> NonZeroUsize

Returns the maximum number of key-value pairs the cache can hold.

pub fn len(&self) -> usize

Returns the current number of key-value pairs in the cache.

pub fn is_empty(&self) -> bool

Returns true if the cache contains no key-value pairs.

pub fn global_age(&self) -> f64

Returns the current global age value.

pub fn record_miss(&mut self, object_size: u64)

Records a cache miss for metrics tracking (to be called by simulation system)

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

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

Returns a reference to the value corresponding to the key.

The key may be any borrowed form of the cache’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Accessing an item increases its frequency count.

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

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

Returns a mutable reference to the value corresponding to the key.

The key may be any borrowed form of the cache’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Accessing an item increases its frequency count.

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

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

Returns true if the cache contains a value for the specified key.

The key may be any borrowed form of the cache’s key type, but Hash and Eq on the borrowed form must match those for the key type.

This does not modify the cache or update access frequency.

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

where K: Clone,

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

If the key already exists, the value is updated and the old value is returned. If the cache is full, items are evicted based on GDSF priority until there’s space.

Arguments

• key - The key to insert
• val - The value to associate with the key
• size - The size/cost of storing this item (must be > 0)

Examples

use cache_rs::gdsf::GdsfCache;
use core::num::NonZeroUsize;

let mut cache = GdsfCache::new(NonZeroUsize::new(2).unwrap());

cache.put("key1", "value1", 1);
cache.put("key2", "value2", 2);
assert_eq!(cache.len(), 2);

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

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

Removes a key from the cache, returning the value if the key was in the cache.

The key may be any borrowed form of the cache’s key type, but Hash and Eq on the borrowed form must match those for the key type.

pub fn clear(&mut self)

Clears the cache, removing all key-value pairs.

impl<K: Hash + Eq, V: Clone> GdsfCache<K, V, DefaultHashBuilder>

pub fn new(cap: NonZeroUsize) -> Self

Creates a new GDSF cache with the specified capacity.

Examples

use cache_rs::gdsf::GdsfCache;
use core::num::NonZeroUsize;

let cache: GdsfCache<&str, u32> = GdsfCache::new(NonZeroUsize::new(10).unwrap());

Trait Implementations

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

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

Returns all GDSF cache metrics as key-value pairs in deterministic order

Returns

A BTreeMap containing all metrics tracked by this GDSF cache instance

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

Returns the algorithm name for this cache implementation

Returns

“GDSF” - identifying this as a Greedy Dual-Size Frequency cache

impl<K: Debug, V: Debug, S: Debug> Debug for GdsfCache<K, V, S>

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

Formats the value using the given formatter.