Struct OnceMap 

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

Run tasks only once and store the results in a parallel hash map.

We often have jobs Fn(K) -> V that we only want to run once and memoize, e.g. network requests for metadata. When multiple tasks start the same query in parallel, e.g. through source dist builds, we want to wait until the other task is done and get a reference to the same result.

Note that this always clones the value out of the underlying map. Because of this, it’s common to wrap the V in an Arc<V> to make cloning cheap.

Implementations

impl<K: Eq + Hash + Clone, V: Clone, H: BuildHasher + Clone> OnceMap<K, V, H>

pub fn register(&self, key: K) -> bool

Register that you want to start a job.

If this method returns true, you need to start a job and call OnceMap::done eventually or other tasks will hang. If it returns false, this job is already in progress and you can OnceMap::wait for the result.

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

Register that you want to start a job, unless it was already started, then wait for its result.

Use this method for once-only operations.

Returns None if the job needs to be started, otherwise returns the result of the job.

Example

if let Some(response) = cache.register_or_wait(&id).await {
    response
} else {
    let response = fetch(&id).await;
    cache.done(id, response.clone());
    response
}

pub fn done(&self, key: K, value: V)

Submit the result of a job you registered.

pub async fn wait(&self, key: &K) -> Result<V, UnregisteredTask<K>>

Wait for the result of a job that is running.

Will hang if OnceMap::done isn’t called for this key, or if UnregisteredTask is a non-fatal error and OnceMap::done isn’t called for this key.

pub fn wait_blocking(&self, key: &K) -> Result<V, UnregisteredTask<K>>

Wait for the result of a job that is running, in a blocking context.

Will hang if OnceMap::done isn’t called for this key, or if UnregisteredTask is a non-fatal error and OnceMap::done isn’t called for this key.

pub fn get<Q: ?Sized + Hash + Eq>(&self, key: &Q) -> Option<V>

where K: Borrow<Q>,

Return the result of a previous job, if any.

pub fn remove<Q: ?Sized + Hash + Eq>(&self, key: &Q) -> Option<V>

where K: Borrow<Q>,

Remove the result of a previous job, if any.

Trait Implementations

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

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

Formats the value using the given formatter.

impl<K: Eq + Hash + Clone, V, H: Default + BuildHasher + Clone> Default for OnceMap<K, V, H>

fn default() -> Self

Returns the “default value” for a type.

impl<K, V, H> FromIterator<(K, V)> for OnceMap<K, V, H>

where K: Eq + Hash, H: Default + Clone + BuildHasher,

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

Creates a value from an iterator.