pub struct Cache<K, V> { /* private fields */ }
Expand description
Basic caching structure with asynchronous locking support.
This structure provides asynchronous access wrapped around a standard
BTreeMap
to avoid blocking event loops when a writer cannot gain a
handle - which is what would happen with standard locking implementations.
Implementations
sourceimpl<K, V> Cache<K, V> where
K: Ord + Clone,
impl<K, V> Cache<K, V> where
K: Ord + Clone,
sourcepub fn with_label(self, s: &str) -> Self
pub fn with_label(self, s: &str) -> Self
Sets the label inside this cache for logging purposes.
sourcepub async fn expired(&self) -> usize
pub async fn expired(&self) -> usize
Retrieve the number of expired entries inside the cache.
Note that this is calculated by walking the set of entries and should therefore not be used in performance sensitive situations.
sourcepub async fn get(&self, k: &K) -> Option<CacheReadGuard<'_, V>>
pub async fn get(&self, k: &K) -> Option<CacheReadGuard<'_, V>>
Retrieve a reference to a value inside the cache.
The returned reference is bound inside a RwLockReadGuard
.
sourcepub async fn len(&self) -> usize
pub async fn len(&self) -> usize
Retrieve the number of entries inside the cache.
This does include entries which may be expired but are not yet evicted. In future there may be an API addition to find the unexpired count, but as it’s relatively expensive it has been omitted for the time being.
sourcepub async fn insert<E>(&self, k: K, v: V, e: E) -> Option<V> where
E: Into<CacheExpiration>,
pub async fn insert<E>(&self, k: K, v: V, e: E) -> Option<V> where
E: Into<CacheExpiration>,
Insert a key/value pair into the cache with an associated expiration.
The third argument controls expiration, which can be provided using any type which
implements Into<CacheExpiration>
. This allows for various different syntax based
on your use case. If you do not want expiration, use CacheExpiration::none()
.
sourcepub async fn monitor(&self, sample: usize, threshold: f64, frequency: Duration)
pub async fn monitor(&self, sample: usize, threshold: f64, frequency: Duration)
Retrieve a Future
used to monitor expired keys.
This future must be spawned on whatever runtime you are using inside your application; not doing this will result in keys never being expired.
For expiration logic, please see Cache::purge
, as this is used under the hood.
sourcepub async fn purge(&self, sample: usize, threshold: f64)
pub async fn purge(&self, sample: usize, threshold: f64)
Cleanses the cache of expired entries.
Keys are expired using the same logic as the popular caching system Redis:
- Wait until the next tick of
frequency
. - Take a sample of
sample
keys from the cache. - Remove any expired keys from the sample.
- Based on
threshold
percentage: 4a. If more thanthreshold
were expired, goto #2. 4b. If less thanthreshold
were expired, goto #1.
This means that at any point you may have up to threshold
percent of your
cache storing expired entries (assuming the monitor just ran), so make sure
to tune your frequency, sample size, and threshold accordingly.
sourcepub async fn remove(&self, k: &K) -> Option<V>
pub async fn remove(&self, k: &K) -> Option<V>
Remove an entry from the cache and return any stored value.
Trait Implementations
Auto Trait Implementations
impl<K, V> !RefUnwindSafe for Cache<K, V>
impl<K, V> Send for Cache<K, V> where
K: Send,
V: Send,
impl<K, V> Sync for Cache<K, V> where
K: Send + Sync,
V: Send + Sync,
impl<K, V> Unpin for Cache<K, V>
impl<K, V> UnwindSafe for Cache<K, V> where
K: RefUnwindSafe,
V: RefUnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more