Struct light_cache::cache::LightCache

source ·

pub struct LightCache<K, V, S = DefaultHashBuilder, P = NoopPolicy> { /* private fields */ }

Expand description

A concurrent hashmap that allows for efficient async insertion of values

§LightCache offers two modes for async insertion:

§Cooperative:

Self::get_or_insert and Self::get_or_try_insert only allow one worker task at a time to poll thier futures and will wake up the other tasks when the value is inserted

§Race:

Self::get_or_insert_race and Self::get_or_try_insert_race allow all worker tasks to poll thier futures at the same time

Implementations§

source §

impl<K, V, S, P> LightCache<K, V, S, P>
where K: Eq + Hash + Copy, V: Clone + Sync, S: BuildHasher, P: Policy<K, V>,

source

pub async fn get_or_insert<F, Fut>(&self, key: K, init: F) -> V
where F: FnOnce() -> Fut, Fut: Future<Output = V>,

Get or insert the value for the given key

In the case that a key is being inserted by another thread using this method or Self::get_or_try_insert tasks will cooperativley compute the value and notify the other task when the value is inserted. If a task fails to insert the value, (via panic or error) another task will take over until theyve all tried.

§Note

If a call to remove is issued between the time of inserting, and waking up tasks, the other tasks will simply see the empty slot and try again

source

pub async fn get_or_try_insert<F, Fut, Err>( &self, key: K, init: F, ) -> Result<V, Err>
where F: FnOnce() -> Fut, Fut: Future<Output = Result<V, Err>>,

Get or insert the value for the given key, returning an error if the value could not be inserted

See Self::get_or_insert for more information

source

pub async fn get_or_insert_race<F, Fut>(&self, key: K, init: F) -> V
where F: FnOnce() -> Fut, Fut: Future<Output = V>,

Get or insert a value into the cache, but instead of waiting for a single caller to finish the insertion (coopertively), any callers of this method will always attempt to poll thier own future

This is safe to use with any other get_or_* method

source

pub async fn get_or_try_insert_race<F, Fut, E>( &self, key: K, init: F, ) -> Result<V, E>
where F: FnOnce() -> Fut, Fut: Future<Output = Result<V, E>>,

See Self::get_or_insert_race for more information

source

pub fn insert(&self, key: K, value: V) -> Option<V>

Insert a value directly into the cache

§Warning:

Doing a Self::insert while another task is doing any type of async write (Self::get_or_insert, Self::get_or_try_insert, etc) will “leak” a wakers entry, which will never be removed unless another get_or_* method is fully completed without being interrupted by a call to this method.

This is mostly not a big deal as Wakers is small, and this pattern really should be avoided in practice.

source

pub fn get(&self, key: &K) -> Option<V>

Try to get a value from the cache

source

pub fn remove(&self, key: &K) -> Option<V>

Remove a value from the cache, returning the value if it was present

§Note:

If this is called while another task is trying to Self::get_or_insert or Self::get_or_try_insert, it will force them to recompute the value and insert it again.

source