Struct RTCache

pub struct RTCache<K, T, CB, S>
where
    K: Hash + Send,
    T: Clone + Send,
{ /* private fields */ }

A read-through in-memory cache on top of MemoryCache

Instead of providing a put function, RTCache requires a type which implements Lookup to be automatically called during cache miss to populate the cache. This is useful when trying to cache queries to external system such as DNS or databases.

Lookup coalescing is provided so that multiple concurrent lookups for the same key results only in one lookup callback.

Implementations

impl<K, T, CB, S> RTCache<K, T, CB, S>

where K: Hash + Send, T: Clone + Send + Sync + 'static,

pub fn new( size: usize, lock_age: Option<Duration>, lock_timeout: Option<Duration>, ) -> Self

Create a new RTCache of given size. lock_age defines how long a lock is valid for. lock_timeout is used to stop a lookup from holding on to the key for too long.

impl<K, T, CB, S> RTCache<K, T, CB, S>

where K: Hash + Send, T: Clone + Send + Sync + 'static, CB: Lookup<K, T, S>,

pub async fn get( &self, key: &K, ttl: Option<Duration>, extra: Option<&S>, ) -> (Result<T, Box<Error>>, CacheStatus)

Query the cache for a given value. If it exists and no TTL is configured initially, it will use the ttl value given.

pub async fn get_stale( &self, key: &K, ttl: Option<Duration>, extra: Option<&S>, stale_ttl: Duration, ) -> (Result<T, Box<Error>>, CacheStatus)

Similar to Self::get, query the cache for a given value, but also returns the value even if the value is expired up to stale_ttl. If it is a cache miss or the value is stale more than the stale_ttl, a lookup will be performed to populate the cache.

impl<K, T, CB, S> RTCache<K, T, CB, S>

where K: Hash + Clone + Send + Sync, T: Clone + Send + Sync + 'static, S: Clone + Send + Sync, CB: Lookup<K, T, S> + Sync + Send,

pub async fn get_stale_while_update( &'static self, key: &K, ttl: Option<Duration>, extra: Option<&S>, stale_ttl: Duration, ) -> (Result<T, Box<Error>>, CacheStatus)

Similar to Self::get_stale, but when it returns the stale value, it also initiates a lookup in the background in order to refresh the value.

Note that this function requires the RTCache to be static, which can be done by wrapping it with something like once_cell::sync::Lazy.

impl<K, T, CB, S> RTCache<K, T, CB, S>

where K: Hash + Send, T: Clone + Send + Sync + 'static, CB: MultiLookup<K, T, S>,

pub async fn multi_get<'a, I>( &self, keys: I, ttl: Option<Duration>, extra: Option<&S>, ) -> Result<Vec<(T, CacheStatus)>, Box<Error>>

where I: Iterator<Item = &'a K>, K: 'a,

Same behavior as RTCache::get but for an arbitrary amount of keys.

If there are keys that are missing from the cache, multi_lookup is invoked to populate the cache before returning the final results. This is useful if your type supports batch queries.

To avoid dead lock for the same key across concurrent multi_get calls, this function does not provide lookup coalescing.