Struct moka::sync::CacheBuilder

pub struct CacheBuilder<K, V, C> { /* private fields */ }

Available on crate feature sync only.

Builds a Cache or SegmentedCache with various configuration knobs.

Example: Expirations

use moka::sync::Cache;
use std::time::Duration;

let cache = Cache::builder()
    // Max 10,000 entries
    .max_capacity(10_000)
    // Time to live (TTL): 30 minutes
    .time_to_live(Duration::from_secs(30 * 60))
    // Time to idle (TTI):  5 minutes
    .time_to_idle(Duration::from_secs( 5 * 60))
    // Create the cache.
    .build();

// This entry will expire after 5 minutes (TTI) if there is no get().
cache.insert(0, "zero");

// This get() will extend the entry life for another 5 minutes.
cache.get(&0);

// Even though we keep calling get(), the entry will expire
// after 30 minutes (TTL) from the insert().

Implementations

impl<K, V> CacheBuilder<K, V, Cache<K, V, RandomState>>

where K: Eq + Hash + Send + Sync + 'static, V: Clone + Send + Sync + 'static,

pub fn new(max_capacity: u64) -> Self

Construct a new CacheBuilder that will be used to build a Cache or SegmentedCache holding up to max_capacity entries.

pub fn segments( self, num_segments: usize ) -> CacheBuilder<K, V, SegmentedCache<K, V, RandomState>>

Sets the number of segments of the cache.

Panics

Panics if num_segments is zero.

pub fn build(self) -> Cache<K, V, RandomState>

Builds a Cache<K, V>.

If you want to build a SegmentedCache<K, V>, call segments method before calling this method.

Panics

Panics if configured with either time_to_live or time_to_idle higher than 1000 years. This is done to protect against overflow when computing key expiration.

pub fn build_with_hasher<S>(self, hasher: S) -> Cache<K, V, S>

where S: BuildHasher + Clone + Send + Sync + 'static,

Builds a Cache<K, V, S> with the given hasher of type S.

Examples

This example uses AHash hasher from AHash crate.

// Cargo.toml
// [dependencies]
// ahash = "0.8"
// moka = ...

use moka::sync::Cache;

// The type of this cache is: Cache<i32, String, ahash::RandomState>
let cache = Cache::builder()
    .max_capacity(100)
    .build_with_hasher(ahash::RandomState::default());
cache.insert(1, "one".to_string());

Note: If you need to add a type annotation to your cache, you must use the form of Cache<K, V, S> instead of Cache<K, V>. That S is the type of the build hasher, and its default is the RandomState from std::collections::hash_map module . If you use a different build hasher, you must specify S explicitly.

Here is a good example:

struct Good {
    // Specifying the type in Cache<K, V, S> format.
    cache: Cache<i32, String, ahash::RandomState>,
}

// Storing the cache from above example. This should compile.
Good { cache };

Here is a bad example. This struct cannot store the above cache because it does not specify S:

struct Bad {
    // Specifying the type in Cache<K, V> format.
    cache: Cache<i32, String>,
}

// This should not compile.
Bad { cache };
// => error[E0308]: mismatched types
//    expected struct `std::collections::hash_map::RandomState`,
//       found struct `ahash::RandomState`

Panics

Panics if configured with either time_to_live or time_to_idle higher than 1000 years. This is done to protect against overflow when computing key expiration.

impl<K, V> CacheBuilder<K, V, SegmentedCache<K, V, RandomState>>

where K: Eq + Hash + Send + Sync + 'static, V: Clone + Send + Sync + 'static,

pub fn build(self) -> SegmentedCache<K, V, RandomState>

Builds a SegmentedCache<K, V>.

If you want to build a Cache<K, V>, do not call segments method before calling this method.

Panics

Panics if configured with either time_to_live or time_to_idle higher than 1000 years. This is done to protect against overflow when computing key expiration.

pub fn build_with_hasher<S>(self, hasher: S) -> SegmentedCache<K, V, S>

where S: BuildHasher + Clone + Send + Sync + 'static,

Builds a SegmentedCache<K, V, S> with the given hasher.

Examples

This example uses AHash hasher from AHash crate.

// Cargo.toml
// [dependencies]
// ahash = "0.8"
// moka = ...

use moka::sync::SegmentedCache;

// The type of this cache is: SegmentedCache<i32, String, ahash::RandomState>
let cache = SegmentedCache::builder(4)
    .max_capacity(100)
    .build_with_hasher(ahash::RandomState::default());
cache.insert(1, "one".to_string());

Note: If you need to add a type annotation to your cache, you must use the form of SegmentedCache<K, V, S> instead of SegmentedCache<K, V>. That S is the type of the build hasher, whose default is the RandomState from std::collections::hash_map module . If you use a different build hasher, you must specify S explicitly.

Here is a good example:

struct Good {
    // Specifying the type in SegmentedCache<K, V, S> format.
    cache: SegmentedCache<i32, String, ahash::RandomState>,
}

// Storing the cache from above example. This should compile.
Good { cache };

Here is a bad example. This struct cannot store the above cache because it does not specify S:

struct Bad {
    // Specifying the type in SegmentedCache<K, V> format.
    cache: SegmentedCache<i32, String>,
}

// This should not compile.
Bad { cache };
// => error[E0308]: mismatched types
//    expected struct `std::collections::hash_map::RandomState`,
//       found struct `ahash::RandomState`

Panics

Panics if configured with either time_to_live or time_to_idle higher than 1000 years. This is done to protect against overflow when computing key expiration.

impl<K, V, C> CacheBuilder<K, V, C>

pub fn name(self, name: &str) -> Self

Sets the name of the cache. Currently the name is used for identification only in logging messages.

pub fn max_capacity(self, max_capacity: u64) -> Self

Sets the max capacity of the cache.

pub fn initial_capacity(self, number_of_entries: usize) -> Self

Sets the initial capacity (number of entries) of the cache.

pub fn eviction_policy(self, policy: EvictionPolicy) -> Self

Sets the eviction (and admission) policy of the cache.

The default policy is TinyLFU. See EvictionPolicy for more details.

pub fn weigher( self, weigher: impl Fn(&K, &V) -> u32 + Send + Sync + 'static ) -> Self

Sets the weigher closure to the cache.

The closure should take &K and &V as the arguments and returns a u32 representing the relative size of the entry.

pub fn eviction_listener( self, listener: impl Fn(Arc<K>, V, RemovalCause) + Send + Sync + 'static ) -> Self

Sets the eviction listener closure to the cache.

The closure should take Arc<K>, V and RemovalCause as the arguments.

Panics

It is very important to make the listener closure not to panic. Otherwise, the cache will stop calling the listener after a panic. This is an intended behavior because the cache cannot know whether it is memory safe or not to call the panicked listener again.

pub fn time_to_live(self, duration: Duration) -> Self

Sets the time to live of the cache.

A cached entry will be expired after the specified duration past from insert.

Panics

CacheBuilder::build* methods will panic if the given duration is longer than 1000 years. This is done to protect against overflow when computing key expiration.

pub fn time_to_idle(self, duration: Duration) -> Self

Sets the time to idle of the cache.

A cached entry will be expired after the specified duration past from get or insert.

Panics

CacheBuilder::build* methods will panic if the given duration is longer than 1000 years. This is done to protect against overflow when computing key expiration.

pub fn expire_after( self, expiry: impl Expiry<K, V> + Send + Sync + 'static ) -> Self

Sets the given expiry to the cache.

See the example for per-entry expiration policy in the Cache documentation.

pub fn support_invalidation_closures(self) -> Self

Enables support for Cache::invalidate_entries_if method.

The cache will maintain additional internal data structures to support invalidate_entries_if method.

Trait Implementations

impl<K, V> Default for CacheBuilder<K, V, Cache<K, V, RandomState>>

where K: Eq + Hash + Send + Sync + 'static, V: Clone + Send + Sync + 'static,

fn default() -> Self

Returns the “default value” for a type.