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.

The default hashing algorithm is the one used by std::collections::HashMap, which is currently SipHash 1-3.

While its 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.