Struct Cache 

pub struct Cache<Key, Val, We = UnitWeighter, B = DefaultHashBuilder, L = DefaultLifecycle<Key, Val>> {
    shard: CacheShard<Key, Val, We, B, L, SharedPlaceholder>,
}

A non-concurrent cache.

Fields

shard: CacheShard<Key, Val, We, B, L, SharedPlaceholder>

Implementations

impl<Key: Eq + Hash, Val> 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, We: Weighter<Key, Val>> Cache<Key, Val, We>

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

impl<Key: Eq + Hash, Val, We: Weighter<Key, Val>, B: BuildHasher, L: Lifecycle<Key, Val>> 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::{unsync::{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 reserve(&mut self, additional: usize)

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

pub fn contains_key<Q>(&self, key: &Q) -> bool

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

Check if a key exist in the cache.

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

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

Fetches an item from the cache.

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<RefMut<'_, Key, Val, We, B, L>>

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

Fetches an item from the cache.

Note: Leaking the returned RefMut might cause cache weight tracking to be inaccurate.

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

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

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

pub fn peek_mut<Q>(&mut self, key: &Q) -> Option<RefMut<'_, Key, Val, We, B, L>>

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

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

Note: Leaking the returned RefMut might cause cache weight tracking to be inaccurate.

pub fn remove<Q>(&mut 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 remove_if<Q, F>(&mut self, key: &Q, f: F) -> Option<(Key, Val)>

where Q: Hash + Equivalent<Key> + ?Sized, F: FnOnce(&Val) -> bool,

Remove an item from the cache whose key is key if f(&value) returns true for that entry. Compared to peek and remove, this method is more efficient as it requires only 1 lookup.

Returns the removed entry, if any.

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

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

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

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

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

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

pub fn retain<F>(&mut self, f: F)

where F: Fn(&Key, &Val) -> bool,

Retains only the items specified by the predicate. In other words, remove all items for which f(&key, &value) returns false. The elements are visited in arbitrary order.

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

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

Gets or inserts an item in the cache with key key. Returns a reference to the inserted value if it was admitted to the cache.

See also get_ref_or_guard.

pub fn get_mut_or_insert_with<'a, Q, E>( &'a mut self, key: &Q, with: impl FnOnce() -> Result<Val, E>, ) -> Result<Option<RefMut<'a, Key, Val, We, B, L>>, E>

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

Gets or inserts an item in the cache with key key. Returns a mutable reference to the inserted value if it was admitted to the cache.

See also get_mut_or_guard.

pub fn get_ref_or_guard<Q>( &mut self, key: &Q, ) -> Result<&Val, Guard<'_, 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.

pub fn get_mut_or_guard<'a, Q>( &'a mut self, key: &Q, ) -> Result<Option<RefMut<'a, Key, Val, We, B, L>>, Guard<'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.

Note: Leaking the returned RefMut might cause cache weight tracking to be inaccurate.

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

Inserts an item in the cache with key key.

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

Inserts an item in the cache with key key.

pub fn clear(&mut self)

Clear all items from the cache

pub fn iter(&self) -> impl Iterator<Item = (&Key, &Val)> + '_

Iterator for the items in the cache

pub fn drain(&mut self) -> impl Iterator<Item = (Key, Val)> + '_

Drain all items from the cache

The cache will be emptied even if the returned iterator isn’t fully consumed.

pub fn set_capacity(&mut self, new_weight_capacity: u64)

Sets the cache to a new weight capacity.

If the new capacity is smaller than the current weight, items will be evicted to bring the cache within the new limit.

pub fn memory_used(&self) -> MemoryUsed

Get total memory used by cache data structures

It should be noted that if cache key or value is some type like Vec<T>, the memory allocated in the heap will not be counted.

Trait Implementations

impl<Key: Clone, Val: Clone, We: Clone, B: Clone, L: Clone> Clone for Cache<Key, Val, We, B, L>

fn clone(&self) -> Cache<Key, Val, We, B, L>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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.