pub struct ExpiringSizedCache<K, V> {
pub ttl_millis: u64,
pub size_limit: Option<usize>,
/* private fields */
}
Expand description
A cache enforcing time expiration and an optional maximum size. When a maximum size is specified, the values are dropped in the order of expiration date, e.g. the next value to expire is dropped. This cache is intended for high read scenarios to allow for concurrent reads while still enforcing expiration and an optional maximum cache size.
To accomplish this, there are a few trade-offs:
- Maximum cache size logic cannot support “LRU”, instead dropping the next value to expire
- Cache keys must implement
Ord
- The cache’s size, reported by
.len
is only guaranteed to be accurate immediately after a call to either.evict
or.retain_latest
- Eviction must be explicitly requested, either on its own or while inserting
Fields§
§ttl_millis: u64
§size_limit: Option<usize>
Implementations§
source§impl<K: Hash + Eq + Ord, V> ExpiringSizedCache<K, V>
impl<K: Hash + Eq + Ord, V> ExpiringSizedCache<K, V>
pub fn new(ttl_millis: u64) -> Self
pub fn with_capacity(ttl_millis: u64, size: usize) -> Self
sourcepub fn size_limit(&mut self, size: usize) -> Option<usize>
pub fn size_limit(&mut self, size: usize) -> Option<usize>
Set a size limit. When reached, the next entries to expire are evicted. Returns the previous value if one was set.
sourcepub fn reserve(&mut self, more: usize)
pub fn reserve(&mut self, more: usize)
Increase backing stores with enough capacity to store more
sourcepub fn ttl_millis(&mut self, ttl_millis: u64) -> u64
pub fn ttl_millis(&mut self, ttl_millis: u64) -> u64
Set ttl millis, return previous value
sourcepub fn evict(&mut self) -> usize
pub fn evict(&mut self) -> usize
Evict values that have expired. Returns number of dropped items.
sourcepub fn retain_latest(&mut self, count: usize, evict: bool) -> usize
pub fn retain_latest(&mut self, count: usize, evict: bool) -> usize
Retain only the latest count
values, dropping the next values to expire.
If evict
, then also evict values that have expired.
Returns number of dropped items.
sourcepub fn remove(&mut self, key: &K) -> Option<V>
pub fn remove(&mut self, key: &K) -> Option<V>
Remove an entry, returning an unexpired value if it was present.
sourcepub fn insert(&mut self, key: K, value: V) -> Result<Option<V>, Error>
pub fn insert(&mut self, key: K, value: V) -> Result<Option<V>, Error>
Insert k/v pair without running eviction logic. See .insert_ttl_evict
sourcepub fn insert_ttl(
&mut self,
key: K,
value: V,
ttl_millis: u64,
) -> Result<Option<V>, Error>
pub fn insert_ttl( &mut self, key: K, value: V, ttl_millis: u64, ) -> Result<Option<V>, Error>
Insert k/v pair with explicit ttl. See .insert_ttl_evict
sourcepub fn insert_evict(
&mut self,
key: K,
value: V,
evict: bool,
) -> Result<Option<V>, Error>
pub fn insert_evict( &mut self, key: K, value: V, evict: bool, ) -> Result<Option<V>, Error>
Insert k/v pair and run eviction logic. See .insert_ttl_evict
sourcepub fn insert_ttl_evict(
&mut self,
key: K,
value: V,
ttl_millis: Option<u64>,
evict: bool,
) -> Result<Option<V>, Error>
pub fn insert_ttl_evict( &mut self, key: K, value: V, ttl_millis: Option<u64>, evict: bool, ) -> Result<Option<V>, Error>
Optionally run eviction logic before inserting a k/v pair with an optional explicit TTL.
If a size_limit
was specified, the next entry to expire will be evicted to make space.
Returns any existing unexpired value.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Return cache size. Note, this does not evict so may return
a size that includes expired entries. Run evict
or retain_latest
first to ensure an accurate length.
pub fn is_empty(&self) -> bool
source§impl<V> ExpiringSizedCache<String, V>
impl<V> ExpiringSizedCache<String, V>
sourcepub fn get_borrowed(&self, key: &str) -> Option<&V>
pub fn get_borrowed(&self, key: &str) -> Option<&V>
Retrieve unexpired entry, accepting &str
to check against String
keys
let mut cache = ExpiringSizedCache::<String, &str>::new(2_000);
cache.insert(String::from("a"), "a").unwrap();
assert_eq!(cache.get_borrowed("a").unwrap(), &"a");
source§impl<T: Hash + Eq + PartialEq, V> ExpiringSizedCache<Vec<T>, V>
impl<T: Hash + Eq + PartialEq, V> ExpiringSizedCache<Vec<T>, V>
sourcepub fn get_borrowed(&self, key: &[T]) -> Option<&V>
pub fn get_borrowed(&self, key: &[T]) -> Option<&V>
Retrieve unexpired entry, accepting &[T]
to check against Vec<T>
keys
let mut cache = ExpiringSizedCache::<Vec<usize>, &str>::new(2_000);
cache.insert(vec![0], "a").unwrap();
assert_eq!(cache.get_borrowed(&[0]).unwrap(), &"a");