Struct Cached

pub struct Cached<T, E> { /* private fields */ }

The main struct implementing the async computation coalescing.

T is the value type and E is the error type of the computation.

A Cached computation is in one of three states:

• There is no cached value and no inflight computation is happening
• There is a cached value and no inflight computation is happening
• There is no cached value, but an inflight computation is currently computing one

The Cached instance can be shared via cloning as it uses an Arc internally.

Cached::get_or_compute will

• Start a new inflight computation if there is no cached value and no inflight computation is happening
• Return the cached value immediately if there is a cached value available
• Subscribe to an inflight computation if there is one happening and return the result of that when it concludes

The cache can be invalidated using Cached::invalidate

The instances of T and E are cloned for every time a user requests a value or gets handed an error E. Thus, consider using an Arc for expensive to clone variants of T and E.

The cached value is stored on the stack, so you may want to consider using a Box for large T.

Implementations

impl<T, E> Cached<T, E>

pub fn new() -> Self

Creates a new instance with no cached value present.

pub fn new_with_value(value: T) -> Self

Creates a new instance with the given value in the cache.

pub fn invalidate(&self) -> Option<T>

Invalidates the cache immediately, returning its value without cloning if present.

pub fn is_inflight(&self) -> bool

Returns true iff there is an inflight computation happening.

pub fn inflight_waiting_count(&self) -> usize

Returns the amount of instances waiting on an inflight computation, including the instance that started the computation.

pub fn abort(&self) -> bool

Aborts the current inflight computation. Returns true iff there was an inflight computation to abort.

After this function returns, the instance will immediately act like there is no inflight computation happening. However, it might still take some time until the actual inflight computation finishes aborting.

pub fn is_value_cached(&self) -> bool

Returns true iff a value is currently cached.

impl<T: Clone, E> Cached<T, E>

pub fn get(&self) -> Option<T>

Returns the value of the cache immediately if present, cloning the value.

impl<T, E> Cached<T, E>

where T: Clone, E: Clone,

pub async fn get_or_compute<Fut>( &self, computation: impl FnOnce() -> Fut, ) -> Result<T, Error<E>>

where Fut: Future<Output = Result<T, E>>,

This function will

• Execute computation and the Future it returns if there is no cached value and no inflight computation is happening, starting a new inflight computation and returning the result of that
• Not do anything with computation and return the cached value immediately if there is a cached value available
• Not do anything with computation and subscribe to an inflight computation if there is one happening and return the result of that when it concludes

Note that the Future computation returns will not be executed via [tokio::spawn] or similar, but rather will become part of the Future this function returns. This means it does not need to be Send.

Errors

If the inflight computation this function subscribed to or started returns an error, that error is cloned and returned by this function in an Error::Computation.

If this function does not start a computation, but subscribes to a computation which panics or gets dropped/cancelled, it will return an Error::Broadcast.

If this function starts a computation or subscribes to a computation that gets aborted with Cached::abort, it will return an Error::Aborted.

Panics

This function panics if computation gets executed and panics, or if the Future returned by computation panics.

pub async fn get_or_subscribe(&self) -> Option<Result<T, Error<E>>>

This function will

• Return immediately with the cached value if a cached value is present
• Return None immediately if no cached value is present and no inflight computation is happening
• Subscribe to an inflight computation if there is one happening and return the result of that when it concludes

Errors

If the inflight computation this function subscribed to returns an error, that error is cloned and returned by this function in an Error::Computation.

If this function subscribes to a computation which panics or gets dropped/cancelled, it will return an Error::Broadcast.

If this function subscribes to a computation that gets aborted with Cached::abort, it will return an Error::Aborted.

pub async fn subscribe_or_recompute<Fut>( &self, computation: impl FnOnce() -> Fut, ) -> (Option<T>, Result<T, Error<E>>)

where Fut: Future<Output = Result<T, E>>,

This function will

• Invalidate the cache and execute computation and the Future it returns if no inflight computation is happening, starting a new inflight computation and returning the result of that
• Subscribe to an inflight computation if there is one happening and return the result of that when it concludes

Note that after calling this function, the cache will always be empty, even if the computation results in an error.

This function will return the previously cached value as well as the result of the computation it starts or subscribes to.

Errors

If the inflight computation this function starts or subscribes to returns an error, that error is cloned and returned by this function in an Error::Computation.

If this function subscribes to a computation which panics or gets dropped/cancelled, it will return an Error::Broadcast.

If this function subscribes to or starts a computation that gets aborted with Cached::abort, it will return an Error::Aborted.

Panics

This function panics if computation gets executed and panics, or if the Future returned by computation panics.

pub async fn force_recompute<Fut>( &self, computation: Fut, ) -> (CachedState<T>, Result<T, Error<E>>)

where Fut: Future<Output = Result<T, E>>,

This function will invalidate the cache, potentially abort the inflight request if one is happening, and start a new inflight computation, returning the result of that.

It will return the previous CachedState as well as the result of the computation it starts.

Errors

If the inflight computation this function starts returns an error, that error is cloned and returned by this function in an Error::Computation.

If this function starts a computation which panics or gets dropped/cancelled, it will return an Error::Broadcast.

If this function starts a computation that gets aborted with Cached::abort, it will return an Error::Aborted.

Panics

This function panics if computation or the Future returned by computation panics.

Trait Implementations

impl<T, E> Clone for Cached<T, E>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug, E: Debug> Debug for Cached<T, E>

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

Formats the value using the given formatter.

impl<T: Default, E: Default> Default for Cached<T, E>

fn default() -> Cached<T, E>

Returns the “default value” for a type.