Struct cascara::Cache

pub struct Cache<K, V, E = VoidEvict<K, V>, S = Storage<K, V>, A = TinyLFUCache, H = SipHasherBuilder> where
    K: Eq + Hash,
    E: OnEvict<K, V>,
    S: Store<K, V>,
    A: TinyLFU,
    H: BuildHasher,  { /* fields omitted */ }

Default implementation of Cache with TinyLFU admit policy.

Implementations

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

pub fn new(capacity: usize) -> Self

Create new cache with default window_size = 10000 for TinyLFU.

Arguments

• capacity: max items in cache

Example

use cascara::Cache;

let cache = Cache::<u8,u8>::new(100);

Panic

If capacity is 0.

pub fn with_window_size(capacity: usize, window_size: usize) -> Self

Create new cache with defined window size fo TinyLFU.

Arguments

• window_size: window size for TinyLFU (max. 10 000)
• capacity: max items in cache

Example

use cascara::Cache;

let cache = Cache::<u8,u8>::with_window_size(100,20);

Panic

If window_size or capacity is 0. If window_size > 10 000

impl<K, V, E> Cache<K, V, E> where
    K: Eq + Hash,
    E: OnEvict<K, V>, 

pub fn with_on_evict(capacity: usize, on_evict: E) -> Self

Create new cache with TinyLFU window size = 10 000 and callback for evicted items from cache.

Arguments

• capacity: max items in cache
• on_evict: will be call for every item evicted from cache.

Example

use cascara::{Cache, OnEvict};

#[derive(Default)]
struct Evict {}

impl OnEvict<u8, u8> for Evict {
    fn evict(&self, k: &u8, v: &u8) {
        println!("Evict item.  k={}, v={}", k, v);
    }
}

let cache = Cache::<u8,u8,Evict>::with_on_evict(100, Evict::default());

Panic

If capacity is 0.

pub fn with_on_evict_and_window_size(
    capacity: usize,
    on_evict: E,
    window_size: usize
) -> Self

Create new cache with defined window size for TinyLFU and callback for evicted items from cache.

Arguments

• capacity: max items in cache
• on_evict: will be call for every item evicted from cache.
• window_size: window size for TinyLFU (max. 10 000)

Example

use cascara::{Cache, OnEvict};

#[derive(Default)]
struct Evict {}

impl OnEvict<u8, u8> for Evict {
    fn evict(&self, k: &u8, v: &u8) {
        println!("Evict item.  k={}, v={}", k, v);
    }
}

let cache = Cache::<u8,u8,Evict>::with_on_evict_and_window_size(100, Evict::default(), 20);

Panic

If window_size or capacity is 0. If window_size > 10 000

impl<K, V, E, S, A, H> Cache<K, V, E, S, A, H> where
    K: Eq + Hash,
    E: OnEvict<K, V>,
    S: Store<K, V>,
    A: TinyLFU,
    H: BuildHasher, 

pub fn with_metrics(self) -> Self

Activate metric collecting in cache

Example

use cascara::Cache;

let cache = Cache::<u8,u8>::new(100).with_metrics();
assert!(cache.metrics().is_some());

pub fn capacity(&self) -> usize

Returns how many items can be hold in cache

Example

use cascara::Cache;

let cache = Cache::<u8,u8>::new(100);
assert_eq!(cache.capacity(), 100);

pub fn len(&self) -> usize

Returns actual number of items in cache

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(cache.insert(1,1).is_ok());
assert_eq!(cache.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if cache is empty

Example

use cascara::Cache;

let cache = Cache::<u8,u8>::new(100);
assert!(cache.is_empty());

pub fn room_left(&self) -> usize

Returns how many room left

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert_eq!(cache.room_left(), 100);
assert!(cache.insert(1,1).is_ok());
assert_eq!(cache.room_left(), 99);

pub fn contains(&self, k: &K) -> bool

Return true if item is in storage

Arguments

• k: item key

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(!cache.contains(&1));
assert!(cache.insert(1,1).is_ok());
assert!(cache.contains(&1));

pub fn get(&self, k: &K) -> Option<&V>

Return item ref if is in cache

Arguments

• k: item key

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(cache.insert(1,2).is_ok());
assert_eq!(cache.get(&1), Some(&2));

pub fn get_mut(&mut self, k: &K) -> Option<&mut V>

Return mutable item ref if is in cache

Arguments

• k: item key

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(cache.insert(1,1).is_ok());
let v = cache.get_mut(&1);
assert!(v.is_some());
if let Some(v) = v {
    *v = 2;
}
assert_eq!(cache.get(&1), Some(&2));

pub fn insert(&mut self, k: K, v: V) -> Result<Option<V>, ()>

Insert item into cache. Item can be rejected (return Err) if cache is full and estimate of new item is lower than sample item from cache. If item is inserted, than preview item value can be returned. Cache is cleaned and all expired items are removed before new is inserted.

Arguments

• k: item key
• v: item value

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(cache.insert(1,1).is_ok());
let v = cache.insert(1,2);
assert!(v.is_ok());
if let Ok(v) = v {
     assert_eq!(v, Some(1));
}

pub fn insert_with_ttl(
    &mut self,
    k: K,
    v: V,
    expiration: Duration
) -> Result<Option<V>, ()>

Insert item into cache with defined time to life in seconds. Returns preview item if exists with given key. Cache is cleaned and all expired items are removed before new is inserted.

If expiration time is 0 sec, than item is insert without ttl.

Arguments

• k: item key
• v: item value
• expiration: how many seconds should item lives

Example

use cascara::Cache;
use std::time::Duration;

let mut cache = Cache::new(100);
assert!(cache.insert_with_ttl(1,1, Duration::from_secs(1)).is_ok());
assert!(cache.contains(&1));
std::thread::sleep(Duration::from_secs(2));
assert!(!cache.contains(&1));

pub fn remove(&mut self, k: &K) -> Option<V>

Remove and return item from cache.

Arguments

• k: item key

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(cache.insert(1,2).is_ok());
assert!(cache.contains(&1));
assert_eq!(cache.remove(&1), Some(2));
assert!(!cache.contains(&1));

pub fn clear(&mut self)

Remove all items from cache.

Example

use cascara::Cache;

let mut cache = Cache::new(100);
assert!(cache.insert(1,1).is_ok());
assert!(cache.insert(2,2).is_ok());
assert!(cache.contains(&1));
assert!(cache.contains(&2));
cache.clear();
assert!(!cache.contains(&1));
assert!(!cache.contains(&2));

pub fn metrics(&self) -> Option<Metrics>

Return cache metrics

Example

use cascara::Cache;

let cache = Cache::<u8,u8>::new(100).with_metrics();
assert!(cache.metrics().is_some());

pub fn iter(&self) -> Iter<K, V, S>

An iterator visiting all entries in order. The iterator element type is (&'a K, &'a V).

Example

use cascara::Cache;

let mut cache = Cache::<u8, u8>::new(10);
assert!(cache.insert(1, 1).is_ok());
assert!(cache.insert(2, 2).is_ok());
assert!(cache.insert(3, 3).is_ok());
for (key, val) in cache.iter() {
    println!("key: {} val: {}", key, val);
}