Struct moka::unsync::Cache

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

An in-memory cache that is not thread-safe.

Cache utilizes a hash table std::collections::HashMap from the standard library for the central key-value storage. Cache performs a best-effort bounding of the map using an entry replacement algorithm to determine which entries to evict when the capacity is exceeded.

Characteristic difference between unsync and sync/future caches

If you use a cache from a single thread application, unsync::Cache may outperform other caches for updates and retrievals because other caches have some overhead on syncing internal data structures between threads.

However, other caches may outperform unsync::Cache on the same operations when expiration polices are configured on a multi-core system. unsync::Cache evicts expired entries as a part of update and retrieval operations while others evict them using a dedicated background thread.

Examples

Cache entries are manually added using an insert method, and are stored in the cache until either evicted or manually invalidated.

Here’s an example of reading and updating a cache by using the main thread:

 use moka::unsync::Cache;

 const NUM_KEYS: usize = 64;

 fn value(n: usize) -> String {
     format!("value {}", n)
 }

 // Create a cache that can store up to 10,000 entries.
 let mut cache = Cache::new(10_000);

 // Insert 64 entries.
 for key in 0..NUM_KEYS {
     cache.insert(key, value(key));
 }

 // Invalidate every 4 element of the inserted entries.
 for key in (0..NUM_KEYS).step_by(4) {
     cache.invalidate(&key);
 }

 // Verify the result.
 for key in 0..NUM_KEYS {
     if key % 4 == 0 {
         assert_eq!(cache.get(&key), None);
     } else {
         assert_eq!(cache.get(&key), Some(&value(key)));
     }
 }

Expiration Policies

Cache supports the following expiration policies:

• Time to live: A cached entry will be expired after the specified duration past from insert.
• Time to idle: A cached entry will be expired after the specified duration past from get or insert.

See the CacheBuilder’s doc for how to configure a cache with them.

Hashing Algorithm

By default, Cache uses a hashing algorithm selected to provide resistance against HashDoS attacks. It will the same one used by std::collections::HashMap, which is currently SipHash 1-3.

While SipHash’s performance is very competitive for medium sized keys, other hashing algorithms will outperform it for small keys such as integers as well as large keys such as long strings. However those algorithms will typically not protect against attacks such as HashDoS.

The hashing algorithm can be replaced on a per-Cache basis using the build_with_hasher method of the CacheBuilder. Many alternative algorithms are available on crates.io, such as the aHash crate.

Implementations

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

pub fn new(max_capacity: usize) -> Self

Constructs a new Cache<K, V> that will store up to the max_capacity entries.

To adjust various configuration knobs such as initial_capacity or time_to_live, use the CacheBuilder.

impl<K, V, S> Cache<K, V, S> where
    K: Hash + Eq,
    S: BuildHasher + Clone, 

pub fn get<Q>(&mut self, key: &Q) -> Option<&V> where
    Rc<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Returns an immutable reference of the value corresponding to the key.

The key may be any borrowed form of the cache’s key type, but Hash and Eq on the borrowed form must match those for the key type.

pub fn insert(&mut self, key: K, value: V)

Inserts a key-value pair into the cache.

If the cache has this key present, the value is updated.

pub fn invalidate<Q>(&mut self, key: &Q) where
    Rc<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Discards any cached value for the key.

The key may be any borrowed form of the cache’s key type, but Hash and Eq on the borrowed form must match those for the key type.

pub fn invalidate_all(&mut self)

Discards all cached values.

Like the invalidate method, this method does not clear the historic popularity estimator of keys so that it retains the client activities of trying to retrieve an item.

pub fn invalidate_entries_if(&mut self, predicate: impl FnMut(&K, &V) -> bool)

Discards cached values that satisfy a predicate.

invalidate_entries_if takes a closure that returns true or false. invalidate_entries_if will apply the closure to each cached value, and if the closure returns true, the value will be invalidated.

Like the invalidate method, this method does not clear the historic popularity estimator of keys so that it retains the client activities of trying to retrieve an item.

pub fn max_capacity(&self) -> usize

Returns the max_capacity of this cache.

pub fn time_to_live(&self) -> Option<Duration>

Returns the time_to_live of this cache.

pub fn time_to_idle(&self) -> Option<Duration>

Returns the time_to_idle of this cache.