Struct GdsfCache

Source

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

Expand description

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

Implementations§

Source §

pub fn current_size(&self) -> u64

Returns the current total size of cached content.

Source

pub fn max_size(&self) -> u64

Returns the maximum content size the cache can hold.

Source

pub fn global_age(&self) -> f64

Source

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

Source

pub fn get<Q>(&mut self, key: &Q) -> Option<V>
where K: Borrow<Q> + Clone, Q: ?Sized + Hash + Eq,

Source

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>
where K: Borrow<Q> + Clone, Q: ?Sized + Hash + Eq,

Source

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

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

GDSF is inherently size-aware: the size parameter affects priority calculation (priority = global_age + frequency / size), favoring small, frequently-accessed items.

§Arguments

key - The key to insert
val - The value to insert
size - Optional size in bytes. Use SIZE_UNIT (1) for count-based caching.

§Returns

Some(vec) containing evicted entries (not replaced entries)
None if no entries were evicted (zero allocation)

Source

pub fn clear(&mut self)

Source

pub fn contains<Q>(&self, key: &Q) -> bool
where K: Borrow<Q>, Q: ?Sized + Hash + Eq,

Check if key exists without updating its priority or access metadata.

Unlike get(), this method does NOT update the entry’s frequency or access metadata.

§Example

use cache_rs::GdsfCache;
use cache_rs::config::GdsfCacheConfig;
use core::num::NonZeroUsize;

let config = GdsfCacheConfig {
    capacity: NonZeroUsize::new(2).unwrap(),
    initial_age: 0.0,
    max_size: u64::MAX,
};
let mut cache = GdsfCache::init(config, None);
cache.put("a", 1, 10);
cache.put("b", 2, 10);

// contains() does NOT update priority
assert!(cache.contains(&"a"));

Source

pub fn peek<Q>(&self, key: &Q) -> Option<&V>
where K: Borrow<Q>, Q: ?Sized + Hash + Eq,

Returns a reference to the value without updating priority or access metadata.

Unlike get(), this does NOT recalculate the entry’s GDSF priority or change its position in the priority lists.

§Example

use cache_rs::GdsfCache;
use cache_rs::config::GdsfCacheConfig;
use core::num::NonZeroUsize;

let config = GdsfCacheConfig {
    capacity: NonZeroUsize::new(3).unwrap(),
    initial_age: 0.0,
    max_size: u64::MAX,
};
let mut cache = GdsfCache::init(config, None);
cache.put("a", 1, 1);

// peek does not change priority
assert_eq!(cache.peek(&"a"), Some(&1));
assert_eq!(cache.peek(&"missing"), None);

Source

pub fn remove<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 present.

Source §

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

Source

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

Creates a new GDSF cache from a configuration.

This is the recommended way to create a GDSF cache. All configuration is specified through the GdsfCacheConfig struct.

§Arguments

config - Configuration specifying capacity and optional size limit/initial age
hasher - Optional custom hash builder. Pass None to use the default.

§Example

use cache_rs::GdsfCache;
use cache_rs::config::GdsfCacheConfig;
use core::num::NonZeroUsize;

// Simple capacity-only cache
let config = GdsfCacheConfig {
    capacity: NonZeroUsize::new(100).unwrap(),
    initial_age: 0.0,
    max_size: u64::MAX,
};
let mut cache: GdsfCache<&str, i32> = GdsfCache::init(config, None);
cache.put("key", 42, 1);

// Cache with size limit (recommended for GDSF)
let config = GdsfCacheConfig {
    capacity: NonZeroUsize::new(1000).unwrap(),
    initial_age: 0.0,
    max_size: 10 * 1024 * 1024,  // 10MB
};
let cache: GdsfCache<String, Vec<u8>> = GdsfCache::init(config, None);