Struct Query 

pub struct Query<'a, T, E = Infallible> { /* private fields */ }

Query the cache for data.

A query must be constructed, using the builder pattern and then passed to Cache::query to retrieve the data.

The following fields are required when constructing a query:

• key: passed to Query::new, this is a unique identifier for the data in the cache, and is used to determine the name of the cache file.

• type T: the type of the data stored in the cache, it must implement serde::Serialize and serde::Deserialize.

The following fields are optional:

• update_fn: used to update the cache, see Query::update_fn.
• checksum: used to determine staleness of the cache, see Query::checksum.
• policy: used to determine when to update the cache and when to return stale data, see Query::policy.
• ttl: the Time To Live (TTL) for the data in the cache, see Query::ttl.
• initial_poll: the duration to wait for the cache to be populated on the first call, see Query::initial_poll.

Implementations

impl<'a> Query<'a, (), Infallible>

pub fn new(key: &'a str) -> Self

Returns a new cache query.

The key is used to determine the name of the cache file.

pub fn update_fn<F, T, E>(self, update_fn: F) -> Query<'a, T, E>

where F: FnOnce() -> Result<T, E> + 'a,

Set the function to update the cache.

This function is called if the cache needs to be updated.

💡 Note

The cache is updated in a separate process to avoid blocking the main thread, this means that any errors from the update function will not be propagated. Stale data will be returned in the meantime.

impl<T, E> Query<'_, T, E>

pub fn checksum<C>(self, checksum: C) -> Self

where C: AsRef<[u8]>,

Set the checksum for the cache.

This is used to determine staleness and is used in two places:

• Whether to the cache needs to be updated (in addition to the TTL). If the checksum is different to the one stored in the cache then the cache might be updated, depending on the QueryPolicy.

• Whether to return stale data. If the checksum is different to the one stored in the cache then depending on the QueryPolicy stale data may be returned.

pub fn policy(self, policy: impl Into<FlagSet<QueryPolicy>>) -> Self

Set the policy for the cache query.

This is used to determine when updates should occur and stale data is allowed to be returned.

Defaults to the cache’s policy.

pub fn ttl(self, ttl: Duration) -> Self

Set the Time To Live (TTL) for the data in the cache.

If the data in the cache is older than this then the cache will be automatically refreshed. Stale data will be returned in the meantime.

Defaults to the cache’s TTL.

pub fn initial_poll(self, initial_poll: Duration) -> Self

Set the initial poll duration.

This is the duration to wait for the cache to be populated on the first call. If the cache is not populated within this duration, a miss error will be raised.

Defaults to the cache’s initial poll duration.