Struct ExpiringSizedCache

pub struct ExpiringSizedCache<K, V> {
    pub ttl_millis: u64,
    pub size_limit: Option<usize>,
    /* private fields */
}

A cache enforcing time expiration and an optional maximum size. When a maximum size is specified, the values are dropped in the order of expiration date, e.g. the next value to expire is dropped. This cache is intended for high read scenarios to allow for concurrent reads while still enforcing expiration and an optional maximum cache size.

To accomplish this, there are a few trade-offs:

• Maximum cache size logic cannot support “LRU”, instead dropping the next value to expire
• Cache keys must implement Ord
• The cache’s size, reported by .len is only guaranteed to be accurate immediately after a call to either .evict or .retain_latest
• Eviction must be explicitly requested, either on its own or while inserting

Fields

ttl_millis: u64

size_limit: Option<usize>

Implementations

impl<K: Hash + Eq + Ord, V> ExpiringSizedCache<K, V>

pub fn new(ttl_millis: u64) -> Self

pub fn with_capacity(ttl_millis: u64, size: usize) -> Self

pub fn size_limit(&mut self, size: usize) -> Option<usize>

Set a size limit. When reached, the next entries to expire are evicted. Returns the previous value if one was set.

pub fn reserve(&mut self, more: usize)

Increase backing stores with enough capacity to store more

pub fn ttl_millis(&mut self, ttl_millis: u64) -> u64

Set ttl millis, return previous value

pub fn evict(&mut self) -> usize

Evict values that have expired. Returns number of dropped items.

pub fn retain_latest(&mut self, count: usize, evict: bool) -> usize

Retain only the latest count values, dropping the next values to expire. If evict, then also evict values that have expired. Returns number of dropped items.

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

Remove an entry, returning an unexpired value if it was present.

pub fn insert(&mut self, key: K, value: V) -> Result<Option<V>, Error>

Insert k/v pair without running eviction logic. See .insert_ttl_evict

pub fn insert_ttl( &mut self, key: K, value: V, ttl_millis: u64, ) -> Result<Option<V>, Error>

Insert k/v pair with explicit ttl. See .insert_ttl_evict

pub fn insert_evict( &mut self, key: K, value: V, evict: bool, ) -> Result<Option<V>, Error>

Insert k/v pair and run eviction logic. See .insert_ttl_evict

pub fn insert_ttl_evict( &mut self, key: K, value: V, ttl_millis: Option<u64>, evict: bool, ) -> Result<Option<V>, Error>

Optionally run eviction logic before inserting a k/v pair with an optional explicit TTL. If a size_limit was specified, the next entry to expire will be evicted to make space. Returns any existing unexpired value.

pub fn clear(&mut self)

Clear all cache entries. Does not release underlying containers

pub fn len(&self) -> usize

Return cache size. Note, this does not evict so may return a size that includes expired entries. Run evict or retain_latest first to ensure an accurate length.

pub fn is_empty(&self) -> bool

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

Retrieve unexpired entry

impl<V> ExpiringSizedCache<String, V>

pub fn get_borrowed(&self, key: &str) -> Option<&V>

Retrieve unexpired entry, accepting &str to check against String keys

let mut cache = ExpiringSizedCache::<String, &str>::new(2_000);
cache.insert(String::from("a"), "a").unwrap();
assert_eq!(cache.get_borrowed("a").unwrap(), &"a");

impl<T: Hash + Eq + PartialEq, V> ExpiringSizedCache<Vec<T>, V>

pub fn get_borrowed(&self, key: &[T]) -> Option<&V>

Retrieve unexpired entry, accepting &[T] to check against Vec<T> keys

let mut cache = ExpiringSizedCache::<Vec<usize>, &str>::new(2_000);
cache.insert(vec![0], "a").unwrap();
assert_eq!(cache.get_borrowed(&[0]).unwrap(), &"a");