Struct waitcache::WaitCache

pub struct WaitCache<K, V, S = RandomState> { /* fields omitted */ }

A concurrent, ever-growing hash map with key-level lock granularity.

This map is suitable for use in situations where the resolution of values can take an extraordinarily long time, such as caching the result of disk access, network requests, or extensive computations. Concurrent resolutions block access to only the resolving values, and not to hash-adjacent values.

Unlike some other cache implemetations, the function used to resolve a given key is never executed multiple times. This is important for avoiding duplication of expensive work.

Implementations

impl<K: Eq + Hash, V> WaitCache<K, V, RandomState>

#[must_use]pub fn new() -> Self

Constructs a new WaitCache with the default hashing algorithm and an initial capacity of 0.

#[must_use]pub fn with_capacity(capacity: usize) -> Self

Constructs a new WaitCache with the default hashing algorithm and the specified initial capacity.

impl<K: Eq + Hash, V, S: BuildHasher + Clone> WaitCache<K, V, S>

#[must_use]pub fn with_hasher(hasher: S) -> Self

Constructs a new WaitCache with the specified hasher and an initial capacity of 0.

#[must_use]pub fn with_capacity_and_hasher(capacity: usize, hasher: S) -> Self

Constructs a new WaitCache with the specified hasher and initial capacity.

#[must_use]pub fn is_empty(&self) -> bool

Returns true if the cache currently contains no items and false otherwise.

#[must_use]pub fn len(&self) -> usize

Returns the number of items currently in the cache.

#[must_use]pub fn capacity(&self) -> usize

Returns the currently provisioned capacity of the cache.

pub fn shrink_to_fit(&self)

Shrinks the provisioned capacity to match the current number of items in the cache.

#[must_use]pub fn hasher(&self) -> &S

Returns the hasher used to construct this cache.

pub fn clear(&mut self)

Empties the cache of all items.

#[must_use]pub fn get<'a, 'b, Q: Eq + Hash + ?Sized>(&'a self, key: &'b Q) -> Option<&'a V> where
    K: Borrow<Q>, 

Looks up a value in the cache given a compatible key.

If the key is present but the value is not fully resolved, the current thread will block until resolution completes.

Returns

• Some(value) - The fully-resolved value corresponding to the specified key.
• None - The specified key was not present.

pub fn resolve<F: FnOnce() -> V>(&self, key: K, init: F) -> &V

Retrieves the value with the specified key, or initializes it if it is not present.

If the key is present but the value is not fully resolved, the current thread will block until resolution completes. If the key is not present, init is executed to produce a value. In either case, an immutable reference to the value is returned.

Notes

The resolution closure, init, does not provide access to the key being resolved. You may need to provide a copy of this value to the closure. This is done to allow for maximum concurrency, as it permits the key to be accessed by other threads during the resolution process.

#[must_use]pub fn iter(&self) -> Iter<'_, K, V, S>

Produces an iterator of immutable references to the entries contained in the cache.

The values are exposed as immutable references to a WaitCell containing the value. The value may still be resolving.

Concurrency

This iterator may prevent concurrent updates to certain portions of the cache.

#[must_use]pub fn keys(&self) -> Keys<'_, K, V, S>

Produces an iterator of immutable references to the keyes contained in the cache.

Concurrency

This iterator may prevent concurrent updates to certain portions of the cache.

#[must_use]pub fn values(&self) -> Values<'_, K, V, S>

Produces an iterator of immutable references to the values contained in the cache.

The values are exposed as immutable references to a WaitCell containing the value. The value may still be resolving.

#[must_use]pub fn from_raw_iter_with_hasher<T: IntoIterator<Item = (K, Box<WaitCell<V>>)>>(
    iter: T,
    hasher: S
) -> Self

Constructs a WaitCache from the specified boxed cell iterator and hasher.

Notes

This method is provided for completeness. Prefer using from_iter_with_hasher instead.

#[must_use]pub fn from_iter_with_hasher<T: IntoIterator<Item = (K, V)>>(
    iter: T,
    hasher: S
) -> Self

Constructs a WaitCache from the specified iterator and hasher.

Trait Implementations

impl<K: Debug + Eq + Hash, V: Debug, S: BuildHasher + Clone> Debug for WaitCache<K, V, S>

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

Formats the value using the given formatter.

impl<K: Eq + Hash, V, S: BuildHasher + Clone + Default> Default for WaitCache<K, V, S>

pub fn default() -> Self

Returns the "default value" for a type.

impl<K: Eq + Hash, V> FromIterator<(K, V)> for WaitCache<K, V, RandomState>

pub fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<K: Eq + Hash, V, S: BuildHasher + Clone> IntoIterator for WaitCache<K, V, S>

type IntoIter = Owned<K, V, S>

Which kind of iterator are we turning this into?

type Item = (K, Option<V>)

The type of the elements being iterated over.

pub fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.