Struct SlruCache

Source

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

Expand description

An implementation of a Segmented Least Recently Used (SLRU) cache.

The cache is divided into two segments:

Probationary segment: Where new entries are initially placed
Protected segment: Where frequently accessed entries are promoted to

When the cache reaches capacity, the least recently used entry from the probationary segment is evicted. If the probationary segment is empty, entries from the protected segment may be demoted back to probationary.

§Examples

use cache_rs::slru::SlruCache;
use cache_rs::config::SlruCacheConfig;
use core::num::NonZeroUsize;

// Create an SLRU cache with a total capacity of 4,
// with a protected capacity of 2 (half protected, half probationary)
let config = SlruCacheConfig {
    capacity: NonZeroUsize::new(4).unwrap(),
    protected_capacity: NonZeroUsize::new(2).unwrap(),
    max_size: u64::MAX,
};
let mut cache = SlruCache::init(config, None);

// Add some items
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);
cache.put("d", 4);

// Access "a" to promote it to the protected segment
assert_eq!(cache.get(&"a"), Some(&1));

// Add a new item, which will evict the least recently used item
// from the probationary segment (likely "b")
cache.put("e", 5);
assert_eq!(cache.get(&"b"), None);

Implementations§

Source §

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

Source

pub fn cap(&self) -> NonZeroUsize

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

Source

pub fn protected_max_size(&self) -> NonZeroUsize

Returns the maximum size of the protected segment.

Source

pub fn len(&self) -> usize

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

Source

pub fn is_empty(&self) -> bool

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

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 get<Q>(&mut self, key: &Q) -> Option<&V>
where K: Borrow<Q>, 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.

If a value is returned from the probationary segment, it is promoted to the protected segment.

Source

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>
where K: Borrow<Q>, 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.

If a value is returned from the probationary segment, it is promoted to the protected segment.

Source

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

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

Source §

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

Source

pub fn put(&mut self, key: K, value: V) -> Option<(K, V)>
where V: Clone,

Inserts a key-value pair into the cache.

If the cache already contained this key, the old value is replaced and returned. Otherwise, if the cache is at capacity, the least recently used item from the probationary segment will be evicted. If the probationary segment is empty, the least recently used item from the protected segment will be demoted to the probationary segment.

The inserted key-value pair is always placed in the probationary segment.

Source

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

Insert a key-value pair with explicit size tracking.

The size parameter specifies how much of max_size this entry consumes. Use size=1 for count-based caches.

Source

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

Removes a key from the cache, returning the value at the key if the key was previously 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.

Source

pub fn clear(&mut self)

Clears the cache, removing all key-value pairs.

Source §

impl<K: Hash + Eq, V> SlruCache<K, V>
where V: Clone,

Source

pub fn init( config: SlruCacheConfig, hasher: Option<DefaultHashBuilder>, ) -> SlruCache<K, V, DefaultHashBuilder>

Creates a new SLRU cache from a configuration.

This is the only way to create an SLRU cache. All configuration is specified through the SlruCacheConfig struct.

§Arguments

config - Configuration specifying capacity, protected capacity, and optional size limit
hasher - Optional custom hash builder. If None, uses the default.

§Example

use cache_rs::SlruCache;
use cache_rs::config::SlruCacheConfig;
use core::num::NonZeroUsize;

// Simple capacity-only cache with 20% protected segment
let config = SlruCacheConfig {
    capacity: NonZeroUsize::new(100).unwrap(),
    protected_capacity: NonZeroUsize::new(20).unwrap(),
    max_size: u64::MAX,
};
let mut cache: SlruCache<&str, i32> = SlruCache::init(config, None);
cache.put("key", 42);

// Cache with size limit
let config = SlruCacheConfig {
    capacity: NonZeroUsize::new(1000).unwrap(),
    protected_capacity: NonZeroUsize::new(200).unwrap(),
    max_size: 10 * 1024 * 1024,  // 10MB
};
let cache: SlruCache<String, Vec<u8>> = SlruCache::init(config, None);