Struct retainer::cache::Cache

pub struct Cache<K, V> { /* fields omitted */ }

Basic caching structure with asynchronous locking support.

This structure provides asynchronous access wrapped around a standard BTreeMap to avoid blocking event loops when a writer cannot gain a handle - which is what would happen with standard locking implementations.

Implementations

impl<K, V> Cache<K, V> where
    K: Ord + Clone, 

pub fn new() -> Self

Construct a new Cache.

pub fn with_label(&mut self, s: &str) -> &mut Self

Sets the label inside this cache for logging purposes.

pub async fn clear(&self)

Remove all entries from the cache.

pub async fn expired(&self) -> usize

Retrieve the number of expired entries inside the cache.

Note that this is calculated by walking the set of entries and should therefore not be used in performance sensitive situations.

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

Retrieve a reference to a value inside the cache.

The returned reference is bound inside a RwLockReadGuard.

pub async fn len(&self) -> usize

Retrieve the number of entries inside the cache.

This does include entries which may be expired but are not yet evicted. In future there may be an API addition to find the unexpired count, but as it's relatively expensive it has been omitted for the time being.

pub async fn insert<E>(&self, k: K, v: V, e: E) -> Option<CacheEntry<V>> where
    E: Into<CacheExpiration>, 

Insert a key/value pair into the cache with an associated expiration.

The third argument controls expiration, which can be provided using any type which implements Into<CacheExpiration>. This allows for various different syntax based on your use case. If you do not want expiration, see insert_untracked.

pub async fn insert_untracked(&self, k: K, v: V) -> Option<CacheEntry<V>>

Insert a key/value pair into the cache with no associated expiration.

pub async fn is_empty(&self) -> bool

Check whether the cache is empty.

pub async fn monitor(&self, sample: usize, threshold: f64, frequency: Duration)

Retrieve a Future used to monitor expired keys.

This future must be spawned on whatever runtime you are using inside your application; not doing this will result in keys never being expired.

For expiration logic, please see Cache::purge, as this is used under the hood.

pub async fn purge(&self, sample: usize, threshold: f64)

Cleanses the cache of expired entries.

Keys are expired using the same logic as the popular caching system Redis:

1. Wait until the next tick of frequency.
2. Take a sample of sample keys from the cache.
3. Remove any expired keys from the sample.
4. Based on threshold percentage: 4a. If more than threshold were expired, goto #2. 4b. If less than threshold were expired, goto #1.

This means that at any point you may have up to threshold percent of your cache storing expired entries (assuming the monitor just ran), so make sure to tune your frequency, sample size, and threshold accordingly.

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

Remove an entry from the cache and return any stored value.

pub async fn unexpired(&self) -> usize

Retrieve the number of unexpired entries inside the cache.

Note that this is calculated by walking the set of entries and should therefore not be used in performance sensitive situations.

pub async fn update<F>(&self, k: &K, f: F) where
    F: FnOnce(&mut V), 

Updates an entry in the cache without changing the expiration.

Trait Implementations

impl<K, V> Default for Cache<K, V> where
    K: Ord + Clone, 

Default implementation.

fn default() -> Self

Returns the "default value" for a type.