Struct moka::unsync::Cache [−][src]
pub struct Cache<K, V, S = RandomState> { /* fields omitted */ }
Expand description
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
orinsert
.
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
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
.
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.
Inserts a key-value pair into the cache.
If the cache has this key present, the value is updated.
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.
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.
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.
Returns the max_capacity
of this cache.
Returns the time_to_live
of this cache.
Returns the time_to_idle
of this cache.