Struct caches::AdaptiveCache

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

AdaptiveCache is a fixed size Adaptive Replacement Cache (ARC). ARC is an enhancement over the standard LRU cache in that tracks both frequency and recency of use. This avoids a burst in access to new entries from evicting the frequently used older entries. It adds some additional tracking overhead to a RawLRU cache with default evict callback policy, computationally it is roughly 2x the cost, and the extra memory overhead is linear with the size of the cache. ARC has been patented by IBM, but is similar to the TwoQueueCache (2Q) which requires setting parameters.

Example

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(4).unwrap();

// fill recent
(0..4).for_each(|i| {
    cache.put(i, i);
});

// move to frequent
cache.get(&0);
cache.get(&1);
assert_eq!(cache.frequent_len(), 2);

// evict from recent
cache.put(4, 4);
assert_eq!(cache.recent_evict_len(), 1);

// current state
// recent:          (MRU) [4, 3] (LRU)
// frequent:        (MRU) [1, 0] (LRU)
// recent evict:    (MRU) [2] (LRU)
// frequent evict:  (MRU) [] (LRU)

// Add 2, should cause hit on recent_evict
cache.put(2, 2);
assert_eq!(cache.recent_evict_len(), 1);
assert_eq!(cache.partition(), 1);
assert_eq!(cache.frequent_len(), 3);

// Current state
// recent LRU:      (MRU) [4] (LRU)
// frequent LRU:    (MRU) [2, 1, 0] (LRU)
// recent evict:    (MRU) [3] (LRU)
// frequent evict:  (MRU) [] (LRU)

// Add 4, should migrate to frequent
cache.put(4, 4);
assert_eq!(cache.recent_len(), 0);
assert_eq!(cache.frequent_len(), 4);

// Current state
// recent LRU:      (MRU) [] (LRU)
// frequent LRU:    (MRU) [4, 2, 1, 0] (LRU)
// recent evict:    (MRU) [3] (LRU)
// frequent evict:  (MRU) [] (LRU)

// Add 5, should evict to b2
cache.put(5, 5);
assert_eq!(cache.recent_len(), 1);
assert_eq!(cache.frequent_len(), 3);
assert_eq!(cache.frequent_evict_len(), 1);

// Current state
// recent:          (MRU) [5] (LRU)
// frequent:        (MRU) [4, 2, 1] (LRU)
// recent evict:    (MRU) [3] (LRU)
// frequent evict:  (MRU) [0] (LRU)

// Add 0, should decrease p
cache.put(0, 0);
assert_eq!(cache.recent_len(), 0);
assert_eq!(cache.frequent_len(), 4);
assert_eq!(cache.recent_evict_len(), 2);
assert_eq!(cache.frequent_evict_len(), 0);
assert_eq!(cache.partition(), 0);

// Current state
// recent:         (MRU) [] (LRU)
// frequent:       (MRU) [0, 4, 2, 1] (LRU)
// recent evict:   (MRU) [5, 3] (LRU)
// frequent evict: (MRU) [0] (LRU)

Implementations

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

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

Create a AdaptiveCache with size and default configurations.

pub fn builder(size: usize) -> AdaptiveCacheBuilder

Returns a AdaptiveCacheBuilder to help build a AdaptiveCache.

Example

use caches::{AdaptiveCacheBuilder, AdaptiveCache, Cache};
use rustc_hash::FxHasher;
use std::hash::BuildHasherDefault;

let mut cache = AdaptiveCache::<u64, u64>::builder(3)
    .set_recent_hasher(BuildHasherDefault::<FxHasher>::default())
    .set_recent_evict_hasher(BuildHasherDefault::<FxHasher>::default())
    .set_frequent_hasher(BuildHasherDefault::<FxHasher>::default())
    .set_frequent_evict_hasher(BuildHasherDefault::<FxHasher>::default())
    .finalize::<u64, u64>()
    .unwrap();

cache.put(1, 1);

impl<K: Hash + Eq, V, RH: BuildHasher, REH: BuildHasher, FH: BuildHasher, FEH: BuildHasher> AdaptiveCache<K, V, RH, REH, FH, FEH>

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

Create a AdaptiveCache from AdaptiveCacheBuilder.

Example

use caches::{Cache, AdaptiveCacheBuilder, AdaptiveCache};
use rustc_hash::FxHasher;
use std::hash::BuildHasherDefault;

let builder = AdaptiveCacheBuilder::new(5);

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

pub fn partition(&self) -> usize

Returns the current partition value of the cache.

pub fn recent_len(&self) -> usize

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

pub fn frequent_len(&self) -> usize

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

pub fn recent_evict_len(&self) -> usize

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

pub fn frequent_evict_len(&self) -> usize

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

pub fn recent_keys(&self) -> KeysMRUIter<'_, K, V>

An iterator visiting all keys of recent LRU in most-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.recent_keys() {
    println!("key: {}", key);
}

pub fn recent_keys_lru(&self) -> KeysLRUIter<'_, K, V>

An iterator visiting all keys of recent LRU in less-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.recent_keys_lru() {
    println!("key: {}", key);
}

pub fn recent_values(&self) -> ValuesMRUIter<'_, K, V>

An iterator visiting all values in most-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_values() {
    println!("val: {}",  val);
}

pub fn recent_values_lru(&self) -> ValuesLRUIter<'_, K, V>

An iterator visiting all values of recent LRU in less-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_values_lru() {
    println!("val: {}", val);
}

pub fn recent_values_mut(&mut self) -> ValuesMRUIterMut<'_, K, V>

An iterator visiting all values of recent in most-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_values_mut() {
    println!("val: {}", val);
}

pub fn recent_values_lru_mut(&mut self) -> ValuesLRUIterMut<'_, K, V>

An iterator visiting all values of recent LRU in less-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_values_lru_mut() {
    println!("val: {}", val);
}

pub fn recent_iter(&self) -> MRUIter<'_, K, V>

An iterator visiting all entries of recent LRU in most-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.recent_iter() {
    println!("key: {} val: {}", key, val);
}

pub fn recent_iter_lru(&self) -> LRUIter<'_, K, V>

An iterator visiting all entries of recent LRU in less-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.recent_iter_lru() {
    println!("key: {} val: {}", key, val);
}

pub fn recent_iter_mut(&mut self) -> MRUIterMut<'_, K, V>

An iterator visiting all entries of recent LRU in most-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

let mut ctr = 2i32;
// write dirty blocks to disk.
for (block_id, block) in cache.recent_iter_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr -= 1;
}

pub fn recent_iter_lru_mut(&mut self) -> LRUIterMut<'_, K, V>

An iterator visiting all entries of recent LRU in less-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

let mut ctr = 0i32;

// write dirty blocks to disk.
for (block_id, block) in cache.frequent_iter_lru_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr += 1;
}

pub fn recent_evict_keys(&self) -> KeysMRUIter<'_, K, V>

An iterator visiting all keys of recent evict LRU in most-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.recent_evict_keys() {
    println!("key: {}", key);
}

pub fn recent_evict_keys_lru(&self) -> KeysLRUIter<'_, K, V>

An iterator visiting all keys of recent evict LRU in less-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.recent_evict_keys_lru() {
    println!("key: {}", key);
}

pub fn recent_evict_values(&self) -> ValuesMRUIter<'_, K, V>

An iterator visiting all values of recent evict LRU in most-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_evict_values() {
    println!("val: {}",  val);
}

pub fn recent_evict_values_lru(&self) -> ValuesLRUIter<'_, K, V>

An iterator visiting all values of recent evict LRU in less-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_evict_values_lru() {
    println!("val: {}", val);
}

pub fn recent_evict_values_mut(&mut self) -> ValuesMRUIterMut<'_, K, V>

An iterator visiting all values of recent evict in most-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_evict_values_mut() {
    println!("val: {}", val);
}

pub fn recent_evict_values_lru_mut(&mut self) -> ValuesLRUIterMut<'_, K, V>

An iterator visiting all values of recent evict LRU in less-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.recent_evict_values_lru_mut() {
    println!("val: {}", val);
}

pub fn recent_evict_iter(&self) -> MRUIter<'_, K, V>

An iterator visiting all entries of recent evict LRU in most-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.recent_evict_iter() {
    println!("key: {} val: {}", key, val);
}

pub fn recent_evict_iter_lru(&self) -> LRUIter<'_, K, V>

An iterator visiting all entries of recent evict LRU in less-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.recent_evict_iter_lru() {
    println!("key: {} val: {}", key, val);
}

pub fn recent_evict_iter_mut(&mut self) -> MRUIterMut<'_, K, V>

An iterator visiting all entries of recent evict LRU in most-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

// evict [0, 1, 2] to recent evict list
cache.put(3, HddBlock { idx: 3, dirty: false, data: [0x00; 512]});
cache.put(4, HddBlock { idx: 4, dirty: true,  data: [0x55; 512]});
cache.put(5, HddBlock { idx: 5, dirty: true,  data: [0x77; 512]});

let mut ctr = 2i32;
// write dirty blocks to disk.
for (block_id, block) in cache.recent_evict_iter_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr -= 1;
}

pub fn recent_evict_iter_lru_mut(&mut self) -> LRUIterMut<'_, K, V>

An iterator visiting all entries of recent evict LRU in less-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

// evict [0, 1, 2] to frequent list
cache.put(3, HddBlock { idx: 3, dirty: false, data: [0x00; 512]});
cache.put(4, HddBlock { idx: 4, dirty: true,  data: [0x55; 512]});
cache.put(5, HddBlock { idx: 5, dirty: true,  data: [0x77; 512]});

let mut ctr = 0i32;

// write dirty blocks to disk.
for (block_id, block) in cache.recent_evict_iter_lru_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr += 1;
}

pub fn frequent_keys(&self) -> KeysMRUIter<'_, K, V>

An iterator visiting all keys of frequent LRU in most-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.frequent_keys() {
    println!("key: {}", key);
}

pub fn frequent_keys_lru(&self) -> KeysLRUIter<'_, K, V>

An iterator visiting all keys of frequent LRU in less-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.frequent_keys_lru() {
    println!("key: {}", key);
}

pub fn frequent_values(&self) -> ValuesMRUIter<'_, K, V>

An iterator visiting all values of frequent LRU in most-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_values() {
    println!("val: {}",  val);
}

pub fn frequent_values_lru(&self) -> ValuesLRUIter<'_, K, V>

An iterator visiting all values of frequent LRU in less-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_values_lru() {
    println!("val: {}", val);
}

pub fn frequent_values_mut(&mut self) -> ValuesMRUIterMut<'_, K, V>

An iterator visiting all values of frequent LRU in most-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_values_mut() {
    println!("val: {}", val);
}

pub fn frequent_values_lru_mut(&mut self) -> ValuesLRUIterMut<'_, K, V>

An iterator visiting all values of frequent LRU in less-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_values_lru_mut() {
    println!("val: {}", val);
}

pub fn frequent_iter(&self) -> MRUIter<'_, K, V>

An iterator visiting all entries of frequent LRU in most-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.frequent_iter() {
    println!("key: {} val: {}", key, val);
}

pub fn frequent_iter_lru(&self) -> LRUIter<'_, K, V>

An iterator visiting all entries of frequent LRU in less-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.frequent_iter_lru() {
    println!("key: {} val: {}", key, val);
}

pub fn frequent_iter_mut(&mut self) -> MRUIterMut<'_, K, V>

An iterator visiting all entries of frequent LRU in most-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

// upgrade to frequent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

let mut ctr = 2i32;
// write dirty blocks to disk.
for (block_id, block) in cache.frequent_iter_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr -= 1;
}

pub fn frequent_iter_lru_mut(&mut self) -> LRUIterMut<'_, K, V>

An iterator visiting all entries of frequent LRU in less-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

// upgrade to frequent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

let mut ctr = 0i32;

// write dirty blocks to disk.
for (block_id, block) in cache.frequent_iter_lru_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr += 1;
}

pub fn frequent_evict_keys(&self) -> KeysMRUIter<'_, K, V>

An iterator visiting all keys of frequent evict LRU in most-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.frequent_evict_keys() {
    println!("key: {}", key);
}

pub fn frequent_evict_keys_lru(&self) -> KeysLRUIter<'_, K, V>

An iterator visiting all keys of frequent evict LRU in less-recently used order. The iterator element type is &'a K.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for key in cache.frequent_evict_keys_lru() {
    println!("key: {}", key);
}

pub fn frequent_evict_values(&self) -> ValuesMRUIter<'_, K, V>

An iterator visiting all values of frequent evict LRU in most-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_evict_values() {
    println!("val: {}",  val);
}

pub fn frequent_evict_values_lru(&self) -> ValuesLRUIter<'_, K, V>

An iterator visiting all values of frequent evict LRU in less-recently used order. The iterator element type is &'a V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_evict_values_lru() {
    println!("val: {}", val);
}

pub fn frequent_evict_values_mut(&mut self) -> ValuesMRUIterMut<'_, K, V>

An iterator visiting all values of frequent evict LRU in most-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_evict_values_mut() {
    println!("val: {}", val);
}

pub fn frequent_evict_values_lru_mut(&mut self) -> ValuesLRUIterMut<'_, K, V>

An iterator visiting all values of frequent evict LRU in less-recently used order. The iterator element type is &'a mut V.

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for val in cache.frequent_evict_values_lru_mut() {
    println!("val: {}", val);
}

pub fn frequent_evict_iter(&self) -> MRUIter<'_, K, V>

An iterator visiting all entries of frequent evict LRU in most-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.frequent_evict_iter() {
    println!("key: {} val: {}", key, val);
}

pub fn frequent_evict_iter_lru(&self) -> LRUIter<'_, K, V>

An iterator visiting all entries of frequent evict LRU in less-recently used order. The iterator element type is (&'a K, &'a V).

Examples

use caches::{Cache, AdaptiveCache};

let mut cache = AdaptiveCache::new(3).unwrap();
cache.put("a", 1);
cache.put("b", 2);
cache.put("c", 3);

for (key, val) in cache.frequent_evict_iter_lru() {
    println!("key: {} val: {}", key, val);
}

pub fn frequent_evict_iter_mut(&mut self) -> MRUIterMut<'_, K, V>

An iterator visiting all entries of frequent evict LRU in most-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

// upgrade to frequent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

let mut ctr = 2i32;
// write dirty blocks to disk.
for (block_id, block) in cache.frequent_evict_iter_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr -= 1;
}

pub fn frequent_evict_iter_lru_mut(&mut self) -> LRUIterMut<'_, K, V>

An iterator visiting all entries of frequent evict LRU in less-recently-used order, giving a mutable reference on V. The iterator element type is (&'a K, &'a mut V).

Examples

use caches::{Cache, AdaptiveCache};

struct HddBlock {
    idx: u64,
    dirty: bool,
    data: [u8; 512]
}

let mut cache = AdaptiveCache::new(3).unwrap();

// put in recent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

// upgrade to frequent list
cache.put(0, HddBlock { idx: 0, dirty: false, data: [0x00; 512]});
cache.put(1, HddBlock { idx: 1, dirty: true,  data: [0x55; 512]});
cache.put(2, HddBlock { idx: 2, dirty: true,  data: [0x77; 512]});

let mut ctr = 0i32;

// write dirty blocks to disk.
for (block_id, block) in cache.frequent_evict_iter_lru_mut() {
    if block.dirty {
        // write block to disk
        block.dirty = false
    }
    assert_eq!(*block_id, ctr);
    ctr += 1;
}

Trait Implementations

impl<K: Hash + Eq, V, RH: BuildHasher, REH: BuildHasher, FH: BuildHasher, FEH: BuildHasher> Cache<K, V> for AdaptiveCache<K, V, RH, REH, FH, FEH>

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 LRU list if it exists.

Example

use caches::{Cache, AdaptiveCache};
let mut cache = AdaptiveCache::new(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 LRU list if it exists.

Example

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

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

assert_eq!(cache.get_mut(&"apple"), None);
assert_eq!(cache.get_mut(&"banana"), Some(&mut 6));
assert_eq!(cache.get_mut(&"pear"), Some(&mut 2));

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, AdaptiveCache};
let mut cache = AdaptiveCache::new(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_mut, peek_mut does not update the LRU list so the key’s position will be unchanged.

Example

use caches::{Cache, AdaptiveCache};
let mut cache = AdaptiveCache::new(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 LRU list.

Example

use caches::{Cache, AdaptiveCache};
let mut cache = AdaptiveCache::new(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, AdaptiveCache};
let mut cache = AdaptiveCache::new(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::{Cache, AdaptiveCache};
let mut cache: AdaptiveCache<isize, &str> = AdaptiveCache::new(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::{Cache, AdaptiveCache};
let mut cache = AdaptiveCache::new(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.put(3, "c");
assert_eq!(cache.len(), 2);

fn cap(&self) -> usize

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

Example

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

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

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

fn is_empty(&self) -> bool

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