Struct CacheBuilder

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

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.

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.

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.

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.

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 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. The immediate delivery mode is used for the listener.

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 is is memory safe or not to call the panicked lister again.

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

Sets the eviction listener closure to the cache with a custom Configuration. Use this method if you want to change the delivery mode to the queued mode.

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 is is memory safe or not to call the panicked lister 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 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.

pub fn thread_pool_enabled(self, v: bool) -> Self

Specify whether or not to enable the thread pool for housekeeping tasks. These tasks include removing expired entries and updating the LRU queue and LFU filter. true to enable and false to disable. (Default: true)

If disabled, the housekeeping tasks will be executed by a client thread when necessary.

NOTE: The default value will be changed to false in a future release (v0.10.0 or v0.11.0).

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.