Struct quick_cache::sync::Cache

pub struct Cache<Key, Val, We = UnitWeighter, B = DefaultHashBuilder, L = DefaultLifecycle<Key, Val>> { /* private fields */ }

A concurrent cache.

Value

Cache values are cloned when fetched. Users should wrap their values with Arc<_> if necessary to avoid expensive clone operations. If interior mutability is required Arc<Mutex<_>> or Arc<RwLock<_>> can also be used.

Thread Safety and Concurrency

The cache instance can wrapped with an Arc (or equivalent) and shared between threads. All methods are accessible via non-mut references so no further synchronization (e.g. Mutex) is needed.

Implementations

impl<Key: Eq + Hash, Val: Clone> Cache<Key, Val>

pub fn new(items_capacity: usize) -> Self

Creates a new cache with holds up to items_capacity items (approximately).

impl<Key: Eq + Hash, Val: Clone, We: Weighter<Key, Val> + Clone> Cache<Key, Val, We>

pub fn with_weighter( estimated_items_capacity: usize, weight_capacity: u64, weighter: We, ) -> Self

impl<Key: Eq + Hash, Val: Clone, We: Weighter<Key, Val> + Clone, B: BuildHasher + Clone, L: Lifecycle<Key, Val> + Clone> Cache<Key, Val, We, B, L>

pub fn with( estimated_items_capacity: usize, weight_capacity: u64, weighter: We, hash_builder: B, lifecycle: L, ) -> Self

Creates a new cache that can hold up to weight_capacity in weight. estimated_items_capacity is the estimated number of items the cache is expected to hold, roughly equivalent to weight_capacity / average item weight.

pub fn with_options( options: Options, weighter: We, hash_builder: B, lifecycle: L, ) -> Self

Constructs a cache based on OptionsBuilder.

Example

use quick_cache::{sync::{Cache, DefaultLifecycle}, OptionsBuilder, UnitWeighter, DefaultHashBuilder};

Cache::<(String, u64), String>::with_options(
  OptionsBuilder::new()
    .estimated_items_capacity(10000)
    .weight_capacity(10000)
    .build()
    .unwrap(),
    UnitWeighter,
    DefaultHashBuilder::default(),
    DefaultLifecycle::default(),
);

pub fn is_empty(&self) -> bool

Returns whether the cache is empty

pub fn len(&self) -> usize

Returns the number of cached items

pub fn weight(&self) -> u64

Returns the total weight of cached items

pub fn capacity(&self) -> u64

Returns the maximum weight of cached items

pub fn misses(&self) -> u64

Available on crate feature stats only.

Returns the number of misses

pub fn hits(&self) -> u64

Available on crate feature stats only.

Returns the number of hits

pub fn reserve(&self, additional: usize)

Reserver additional space for additional entries. Note that this is counted in entries, and is not weighted.

pub fn get<Q>(&self, key: &Q) -> Option<Val>

where Q: Hash + Equivalent<Key> + ?Sized,

Fetches an item from the cache whose key is key.

pub fn peek<Q>(&self, key: &Q) -> Option<Val>

where Q: Hash + Equivalent<Key> + ?Sized,

Peeks an item from the cache whose key is key. Contrary to gets, peeks don’t alter the key “hotness”.

pub fn remove<Q>(&self, key: &Q) -> Option<(Key, Val)>

where Q: Hash + Equivalent<Key> + ?Sized,

Remove an item from the cache whose key is key. Returns the removed entry, if any.

pub fn replace( &self, key: Key, value: Val, soft: bool, ) -> Result<(), (Key, Val)>

Inserts an item in the cache, but only if an entry with key key already exists. If soft is set, the replace operation won’t affect the “hotness” of the entry, even if the value is replaced.

Returns Ok if the entry was admitted and Err(_) if it wasn’t.

pub fn replace_with_lifecycle( &self, key: Key, value: Val, soft: bool, ) -> Result<L::RequestState, (Key, Val)>

Inserts an item in the cache, but only if an entry with key key already exists. If soft is set, the replace operation won’t affect the “hotness” of the entry, even if the value is replaced.

Returns Ok if the entry was admitted and Err(_) if it wasn’t.

pub fn insert(&self, key: Key, value: Val)

Inserts an item in the cache with key key.

pub fn insert_with_lifecycle(&self, key: Key, value: Val) -> L::RequestState

Inserts an item in the cache with key key.

pub fn clear(&self)

Clear all items from the cache

pub fn get_value_or_guard<'a, Q>( &'a self, key: &Q, timeout: Option<Duration>, ) -> GuardResult<'a, Key, Val, We, B, L>

where Q: Hash + Equivalent<Key> + ToOwned<Owned = Key> + ?Sized,

Gets an item from the cache with key key .

If the corresponding value isn’t present in the cache, this functions returns a guard that can be used to insert the value once it’s computed. While the returned guard is alive, other calls with the same key using the get_value_guard or get_or_insert family of functions will wait until the guard is dropped or the value is inserted.

A None timeout means waiting forever.

pub fn get_or_insert_with<Q, E>( &self, key: &Q, with: impl FnOnce() -> Result<Val, E>, ) -> Result<Val, E>

where Q: Hash + Equivalent<Key> + ToOwned<Owned = Key> + ?Sized,

Gets or inserts an item in the cache with key key.

See also get_value_or_guard and get_value_or_guard_async.

pub async fn get_value_or_guard_async<'a, Q>( &'a self, key: &Q, ) -> Result<Val, PlaceholderGuard<'a, Key, Val, We, B, L>>

where Q: Hash + Equivalent<Key> + ToOwned<Owned = Key> + ?Sized,

Gets an item from the cache with key key.

If the corresponding value isn’t present in the cache, this functions returns a guard that can be used to insert the value once it’s computed. While the returned guard is alive, other calls with the same key using the get_value_guard or get_or_insert family of functions will wait until the guard is dropped or the value is inserted.

pub async fn get_or_insert_async<'a, Q, E>( &self, key: &Q, with: impl Future<Output = Result<Val, E>>, ) -> Result<Val, E>

where Q: Hash + Equivalent<Key> + ToOwned<Owned = Key> + ?Sized,

Gets or inserts an item in the cache with key key.

Trait Implementations

impl<Key, Val, We, B, L> Debug for Cache<Key, Val, We, B, L>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.