Struct caches::SegmentedCache

pub struct SegmentedCache<K, V, FH = DefaultHashBuilder, RH = DefaultHashBuilder> { /* private fields */ }

SegmentedCache is a fixed size Segmented LRU Cache.

Example

use caches::{Cache, SegmentedCache};

let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put(1, 1);
cache.put(2, 2);

assert_eq!(cache.probationary_len(), 2);
assert_eq!(cache.protected_len(), 0);

assert_eq!(cache.get(&1), Some(&1));
*cache.get_mut(&2).unwrap() = 22;

assert_eq!(cache.probationary_len(), 0);
assert_eq!(cache.protected_len(), 2);

cache.put(3, 3);
cache.put(4, 4);

assert_eq!(cache.probationary_len(), 2);
assert_eq!(cache.protected_len(), 2);

assert_eq!(cache.peek(&3), Some(&3));
assert_eq!(cache.peek_mut(&4), Some(&mut 4));

assert_eq!(cache.probationary_len(), 2);
assert_eq!(cache.protected_len(), 2);

assert_eq!(cache.remove(&2), Some(22));
assert_eq!(cache.len(), 3);

cache.purge();
assert_eq!(cache.len(), 0);

Implementations

impl<K: Hash + Eq, V> SegmentedCache<K, V>

pub fn new(
    probationary_size: usize,
    protected_size: usize
) -> Result<Self, CacheError>

Create a SegmentedCache with size and default configurations.

pub fn builder(
    probationary_size: usize,
    protected_size: usize
) -> SegmentedCacheBuilder

Returns a SegmentedCacheBuilder to help build a SegmentedCache.

Example

use caches::{Cache, SegmentedCacheBuilder, SegmentedCache};
use rustc_hash::FxHasher;
use std::hash::BuildHasherDefault;

let mut cache = SegmentedCache::<u64, u64>::builder(3, 3)
    .set_probationary_hasher(BuildHasherDefault::<FxHasher>::default())
    .set_protected_hasher(BuildHasherDefault::<FxHasher>::default())
    .finalize()
    .unwrap();

cache.put(1, 1);

impl<K: Hash + Eq, V, FH: BuildHasher, RH: BuildHasher> SegmentedCache<K, V, FH, RH>

pub fn from_builder(
    builder: SegmentedCacheBuilder<FH, RH>
) -> Result<Self, CacheError>

Create a [AdaptiveCache] from SegmentedCacheBuilder.

Example

use caches::{Cache, SegmentedCache, SegmentedCacheBuilder};
use rustc_hash::FxHasher;
use std::hash::BuildHasherDefault;

let builder = SegmentedCacheBuilder::new(5, 5);

let mut cache = SegmentedCache::from_builder(builder).unwrap();
cache.put(1, 1);

pub fn put_protected(&mut self, k: K, v: V) -> PutResult<K, V>

put_protected will force to put an entry in protected LRU

pub fn peek_lru_from_probationary(&mut self) -> Option<(&K, &V)>

Returns the value corresponding to the least recently used item or None if the cache is empty. Like peek, peek_lru_from_probationary does not update the probationary LRU list so the item’s position will be unchanged.

pub fn peek_lru_mut_from_probationary(&mut self) -> Option<(&K, &mut V)>

Returns the mutable value corresponding to the least recently used item or None if the cache is empty. Like peek, peek_lru_mut_from_probationary does not update the probationary LRU list so the item’s position will be unchanged.

pub fn peek_mru_from_probationary(&mut self) -> Option<(&K, &V)>

Returns the value corresponding to the most recently used item or None if the cache is empty. Like peek, peek_mru_from_probationary does not update the probationary LRU list so the item’s position will be unchanged.

pub fn peek_mru_mut_from_probationary(&mut self) -> Option<(&K, &mut V)>

Returns the mutable value corresponding to the most recently used item or None if the cache is empty. Like peek, peek_mru_mut_from_probationary does not update the probationary LRU list so the item’s position will be unchanged.

pub fn peek_lru_from_protected(&self) -> Option<(&K, &V)>

Returns the value corresponding to the least recently used item or None if the cache is empty. Like peek, peek_lru_from_protected does not update the protected LRU list so the item’s position will be unchanged.

pub fn peek_lru_mut_from_protected(&mut self) -> Option<(&K, &mut V)>

Returns the mutable value corresponding to the least recently used item or None if the cache is empty. Like peek, peek_lru_mut_from_protected does not update the protected LRU list so the item’s position will be unchanged.

pub fn peek_mru_from_protected(&self) -> Option<(&K, &V)>

Returns the value corresponding to the most recently used item or None if the cache is empty. Like peek, peek_mru_from_protected does not update the protected LRU list so the item’s position will be unchanged.

pub fn peek_mru_mut_from_protected(&mut self) -> Option<(&K, &mut V)>

Returns the mutable value corresponding to the most recently used item or None if the cache is empty. Like peek, peek_mru_mut_from_protected does not update the protected LRU list so the item’s position will be unchanged.

pub fn remove_lru_from_probationary(&mut self) -> Option<(K, V)>

Removes and returns the key and value corresponding to the least recently used item or None if the probationary cache is empty.

pub fn remove_lru_from_protected(&mut self) -> Option<(K, V)>

Removes and returns the key and value corresponding to the least recently used item or None if the protected cache is empty.

pub fn protected_len(&self) -> usize

Returns the number of key-value pairs that are currently in the protected LRU.

pub fn probationary_len(&self) -> usize

Returns the number of key-value pairs that are currently in the probationary LRU.

pub fn probationary_cap(&self) -> usize

Returns the capacity of probationary LRU.

pub fn protected_cap(&self) -> usize

Returns the capacity of protected LRU.

Trait Implementations

impl<K: Hash + Eq, V, FH: BuildHasher, RH: BuildHasher> Cache<K, V> for SegmentedCache<K, V, FH, RH>

fn put(&mut self, k: K, v: V) -> PutResult<K, V>

Puts a key-value pair into cache, returns a PutResult.

Example

use caches::{Cache, SegmentedCache};
use caches::PutResult;
let mut cache = SegmentedCache::new(2, 2).unwrap();

assert_eq!(PutResult::Put, cache.put(1, "a"));
assert_eq!(PutResult::Put, cache.put(2, "b"));
assert_eq!(PutResult::Update("b"), cache.put(2, "beta"));
assert_eq!(PutResult::Put, cache.put(3, "c"));

assert_eq!(cache.get(&1), Some(&"a"));
assert_eq!(cache.get(&2), Some(&"beta"));

fn get<'a, Q>(&mut self, k: &'a Q) -> Option<&'a V>where
    KeyRef<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized,

Returns a reference to the value of the key in the cache or None if it is not present in the cache. Moves the key to the head of the protected segment LRU list if it exists.

Example

use caches::{Cache, SegmentedCache};
let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put("apple", 8);
cache.put("banana", 4);
cache.put("banana", 6);
cache.put("pear", 2);

assert_eq!(cache.get(&"banana"), Some(&6));

fn get_mut<'a, Q>(&mut self, k: &'a Q) -> Option<&'a mut V>where
    KeyRef<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized,

Returns a mutable reference to the value of the key in the cache or None if it is not present in the cache. Moves the key to the head of the protected segment LRU list if it exists.

Example

use caches::{Cache, SegmentedCache};
let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put("apple", 8);
cache.put("banana", 4);
cache.put("banana", 6);
cache.put("pear", 2);

assert_eq!(cache.get_mut(&"banana"), Some(&mut 6));

fn peek<'a, Q>(&self, k: &'a Q) -> Option<&'a V>where
    KeyRef<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized,

Returns a reference to the value corresponding to the key in the cache or None if it is not present in the cache. Unlike get, peek does not update the LRU list so the key’s position will be unchanged.

Example

use caches::{Cache, SegmentedCache};
let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put(1, "a");
cache.put(2, "b");

assert_eq!(cache.peek(&1), Some(&"a"));
assert_eq!(cache.peek(&2), Some(&"b"));

fn peek_mut<'a, Q>(&mut self, k: &'a Q) -> Option<&'a mut V>where
    KeyRef<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized,

Returns a mutable reference to the value corresponding to the key in the cache or None if it is not present in the cache. Unlike get, peek does not update the LRU list so the key’s position will be unchanged.

Example

use caches::{Cache, SegmentedCache};
let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put(1, "a");
cache.put(2, "b");

assert_eq!(cache.peek_mut(&1), Some(&mut "a"));
assert_eq!(cache.peek_mut(&2), Some(&mut "b"));

fn contains<Q>(&self, k: &Q) -> boolwhere
    KeyRef<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized,

Returns a bool indicating whether the given key is in the cache. Does not update the cache.

Example

use caches::{Cache, SegmentedCache};
let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put(1, "a");
cache.put(2, "b");
cache.put(3, "c");

assert!(!cache.contains(&1));
assert!(cache.contains(&2));
assert!(cache.contains(&3));

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

Removes and returns the value corresponding to the key from the cache or None if it does not exist.

Example

use caches::{Cache, SegmentedCache};

let mut cache = SegmentedCache::new(2, 2).unwrap();

cache.put(2, "a");

assert_eq!(cache.remove(&1), None);
assert_eq!(cache.remove(&2), Some("a"));
assert_eq!(cache.remove(&2), None);
assert_eq!(cache.len(), 0);

fn purge(&mut self)

Clears the contents of the cache.

Example

use caches::{SegmentedCache, Cache};

let mut cache: SegmentedCache<isize, &str> = SegmentedCache::new(2, 2).unwrap();
assert_eq!(cache.len(), 0);

cache.put(1, "a");
assert_eq!(cache.len(), 1);

cache.put(2, "b");
assert_eq!(cache.len(), 2);

cache.purge();
assert_eq!(cache.len(), 0);

fn len(&self) -> usize

Returns the number of key-value pairs that are currently in the the cache.

Example

use caches::lru::SegmentedCache;
use caches::Cache;
let mut cache = SegmentedCache::new(2, 2).unwrap();
assert_eq!(cache.len(), 0);

cache.put(1, "a");
assert_eq!(cache.len(), 1);

cache.put(2, "b");
assert_eq!(cache.len(), 2);

// because no entry is in protected LRU, so this operation will evict
cache.put(3, "c");
assert_eq!(cache.len(), 2);

// now 3 is put in protected LRU
cache.put(3, "cc");
assert_eq!(cache.len(), 2);

// we can put 4-"d" in probationary LRU, and the size of cache is 3
cache.put(4, "d");
assert_eq!(cache.len(), 3);

fn cap(&self) -> usize

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

Example

use caches::lru::SegmentedCache;
use caches::Cache;
let mut cache: SegmentedCache<isize, &str> = SegmentedCache::new(2, 2).unwrap();
assert_eq!(cache.cap(), 4);

fn is_empty(&self) -> bool

Returns a bool indicating whether the cache is empty or not.