Struct moka::sync::SegmentedCache

pub struct SegmentedCache<K, V, S = RandomState> { /* private fields */ }

A thread-safe concurrent in-memory cache, with multiple internal segments.

SegmentedCache has multiple internal Cache instances for increased concurrent update performance. However, it has little overheads on retrievals and updates for managing these segments.

For usage examples, see the document of the Cache.

Implementations

impl<K, V> SegmentedCache<K, V, RandomState> where
    K: Hash + Eq + Send + Sync + 'static,
    V: Clone + Send + Sync + 'static, 

pub fn new(max_capacity: u64, num_segments: usize) -> Self

Constructs a new SegmentedCache<K, V> that has multiple internal segments and will store up to the max_capacity.

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

Panics

Panics if num_segments is 0.

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

Returns a CacheBuilder, which can builds a SegmentedCache with various configuration knobs.

impl<K, V, S> SegmentedCache<K, V, S> where
    K: Hash + Eq + Send + Sync + 'static,
    V: Clone + Send + Sync + 'static,
    S: BuildHasher + Clone + Send + Sync + 'static, 

pub fn contains_key<Q>(&self, key: &Q) -> bool where
    Arc<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Returns true if the cache contains a value for the key.

Unlike the get method, this method is not considered a cache read operation, so it does not update the historic popularity estimator or reset the idle timer 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 get<Q>(&self, key: &Q) -> Option<V> where
    Arc<K>: Borrow<Q>,
    Q: Hash + Eq + ?Sized, 

Returns a clone of the value corresponding to the key.

If you want to store values that will be expensive to clone, wrap them by std::sync::Arc before storing in a cache. Arc is a thread-safe reference-counted pointer and its clone() method is cheap.

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 get_or_insert_with(&self, key: K, init: impl FnOnce() -> V) -> V

👎 Deprecated since 0.8.0:

Replaced with get_with

Deprecated, replaced with get_with

pub fn get_or_try_insert_with<F, E>(&self, key: K, init: F) -> Result<V, Arc<E>> where
    F: FnOnce() -> Result<V, E>,
    E: Send + Sync + 'static, 

👎 Deprecated since 0.8.0:

Replaced with try_get_with

Deprecated, replaced with try_get_with

pub fn get_with(&self, key: K, init: impl FnOnce() -> V) -> V

Ensures the value of the key exists by inserting the result of the init closure if not exist, and returns a clone of the value.

This method prevents to evaluate the init closure multiple times on the same key even if the method is concurrently called by many threads; only one of the calls evaluates its closure, and other calls wait for that closure to complete.

pub fn try_get_with<F, E>(&self, key: K, init: F) -> Result<V, Arc<E>> where
    F: FnOnce() -> Result<V, E>,
    E: Send + Sync + 'static, 

Try to ensure the value of the key exists by inserting an Ok result of the init closure if not exist, and returns a clone of the value or the Err returned by the closure.

This method prevents to evaluate the init closure multiple times on the same key even if the method is concurrently called by many threads; only one of the calls evaluates its closure (as long as these closures return the same error type), and other calls wait for that closure to complete.

pub fn insert(&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>(&self, key: &Q) where
    Arc<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(&self)

Discards all cached values.

This method returns immediately and a background thread will evict all the cached values inserted before the time when this method was called. It is guaranteed that the get method must not return these invalidated values even if they have not been evicted.

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<F>(
    &self,
    predicate: F
) -> Result<(), PredicateError> where
    F: Fn(&K, &V) -> bool + Send + Sync + 'static, 

Discards cached values that satisfy a predicate.

invalidate_entries_if takes a closure that returns true or false. This method returns immediately and a background thread will apply the closure to each cached value inserted before the time when invalidate_entries_if was called. If the closure returns true on a value, that value will be evicted from the cache.

Also the get method will apply the closure to a value to determine if it should have been invalidated. Therefore, it is guaranteed that the get method must not return invalidated values.

Note that you must call CacheBuilder::support_invalidation_closures at the cache creation time as the cache needs to maintain additional internal data structures to support this method. Otherwise, calling this method will fail with a PredicateError::InvalidationClosuresDisabled.

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 policy(&self) -> Policy

Returns a read-only cache policy of this cache.

At this time, cache policy cannot be modified after cache creation. A future version may support to modify it.

Trait Implementations

impl<K, V, S> Clone for SegmentedCache<K, V, S>

fn clone(&self) -> Self

Makes a clone of this shared cache.

This operation is cheap as it only creates thread-safe reference counted pointers to the shared internal data structures.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K, V, S> ConcurrentCacheExt<K, V> for SegmentedCache<K, V, S> where
    K: Hash + Eq + Send + Sync + 'static,
    V: Send + Sync + 'static,
    S: BuildHasher + Clone + Send + Sync + 'static, 

fn sync(&self)

Performs any pending maintenance operations needed by the cache.

impl<K, V, S> Send for SegmentedCache<K, V, S> where
    K: Send + Sync,
    V: Send + Sync,
    S: Send, 

impl<K, V, S> Sync for SegmentedCache<K, V, S> where
    K: Send + Sync,
    V: Send + Sync,
    S: Sync,