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 core::num::NonZeroUsize;

// Create an SLRU cache with a total capacity of 4,
// with a protected capacity of 2 (half protected, half probationary)
let mut cache = SlruCache::new(
    NonZeroUsize::new(4).unwrap(),
    NonZeroUsize::new(2).unwrap()
);

// 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 with_hasher( total_cap: NonZeroUsize, protected_cap: NonZeroUsize, hash_builder: S, ) -> Self

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

§Parameters

total_cap: The total capacity of the cache. Must be a non-zero value.
protected_cap: The maximum capacity of the protected segment. Must be a non-zero value and less than or equal to total_cap.
hash_builder: The hash builder to use for the underlying hash map.

§Panics

Panics if protected_cap is greater than total_cap.

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 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 put(&mut self, key: K, value: V) -> Option<(K, V)>
where K: 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