pub struct TimedLfuCache<Key: Hash + Eq, Value> { /* private fields */ }Expand description
A LFU cache with additional eviction conditions based on the time an entry has been in cache.
Note that the performance of this cache for all operations that evict expired entries is O(log n).
Implementations§
Source§impl<Key: Hash + Eq, Value> TimedLfuCache<Key, Value>
impl<Key: Hash + Eq, Value> TimedLfuCache<Key, Value>
Sourcepub fn with_expiration(expiration: Duration) -> Self
pub fn with_expiration(expiration: Duration) -> Self
Constructs an unbounded LFU cache with an time-to-live for its elements. Cache elements that have been in the cache longer than the provided duration are automatically evicted.
Sourcepub fn with_capacity_and_expiration(
capacity: usize,
expiration: Duration,
) -> Self
pub fn with_capacity_and_expiration( capacity: usize, expiration: Duration, ) -> Self
Constructs a bounded LFU cache with an time-to-live for its elements. Cache elements that have been in the cache longer than the provided duration are automatically evicted.
Sourcepub fn set_capacity(&mut self, new_capacity: usize)
pub fn set_capacity(&mut self, new_capacity: usize)
Sets the new capacity. If the provided capacity is zero, then this will turn the cache into an unbounded cache. If the new capacity is less than the current capacity, the least frequently used items are evicted until the number of items is equal to the capacity.
Calling this method will automatically evict expired entries before inserting the value.
If the cache becomes unbounded, then users must manually call
Self::pop_lfu to remove the least frequently used item.
Sourcepub fn insert(&mut self, key: Key, value: Value) -> Option<Value>
pub fn insert(&mut self, key: Key, value: Value) -> Option<Value>
Inserts a value into the cache using the provided key. If the value already exists, then the value is replaced with the provided value and the frequency is reset.
Calling this method will automatically evict expired entries before inserting the value.
The returned Option will return an evicted value, if a value needed to be evicted. This includes the old value, if the previously existing value was present under the same key.
Sourcepub fn get(&mut self, key: &Key) -> Option<&Value>
pub fn get(&mut self, key: &Key) -> Option<&Value>
Gets a value and incrementing the internal frequency counter of that value, if it exists.
Calling this method will automatically evict expired entries before looking up the value.
Sourcepub fn get_mut(&mut self, key: &Key) -> Option<&mut Value>
pub fn get_mut(&mut self, key: &Key) -> Option<&mut Value>
Gets a mutable value and incrementing the internal frequency counter of that value, if it exists.
Calling this method will automatically evict expired entries before looking up the value.
Sourcepub fn remove(&mut self, key: &Key) -> Option<Value>
pub fn remove(&mut self, key: &Key) -> Option<Value>
Removes a value from the cache by key, if it exists.
Calling this method will automatically evict expired entries before removing the value.
Sourcepub fn entry(&mut self, key: Key) -> Entry<'_, Key, Value>
pub fn entry(&mut self, key: Key) -> Entry<'_, Key, Value>
Gets the given key’s corresponding entry in the LFU cache for in-place manipulation. If the key refers to an occupied entry, that entry then is immediately considered accessed, even if no reading or writing is performed. This behavior is a limitation of the Entry API.
Calling this method method will automatically evict expired entries before returning the entry struct.
Sourcepub fn pop_lfu(&mut self) -> Option<Value>
pub fn pop_lfu(&mut self) -> Option<Value>
Evicts the least frequently used value and returns it. If the cache is empty, then this returns None. If there are multiple items that have an equal access count, then the most recently added value is evicted.
Calling this method will automatically evict expired entries before returning the LFU item.
Sourcepub fn pop_lfu_key_value(&mut self) -> Option<(Key, Value)>
pub fn pop_lfu_key_value(&mut self) -> Option<(Key, Value)>
Evicts the least frequently used key-value pair and returns it. If the cache is empty, then this returns None. If there are multiple items that have an equal access count, then the most recently added key-value pair is evicted.
Calling this method will automatically evict expired entries before returning the LFU item.
Sourcepub fn pop_lfu_key_value_frequency(&mut self) -> Option<(Key, Value, usize)>
pub fn pop_lfu_key_value_frequency(&mut self) -> Option<(Key, Value, usize)>
Evicts the least frequently used value and returns it, the key it was inserted under, and the frequency it had. If the cache is empty, then this returns None. If there are multiple items that have an equal access count, then the most recently added key-value pair is evicted.
Calling this method will automatically evict expired entries before returning the LFU item.
Sourcepub fn clear(&mut self) -> LfuCacheIter<Key, Value> ⓘ
pub fn clear(&mut self) -> LfuCacheIter<Key, Value> ⓘ
Clears the cache, returning the iterator of the previous cached values.
Sourcepub fn peek_lfu(&self) -> Option<&Value>
pub fn peek_lfu(&self) -> Option<&Value>
Peeks at the next value to be evicted, if there is one. This will not increment the access counter for that value, or evict expired entries.
Sourcepub fn peek_lfu_key(&self) -> Option<&Key>
pub fn peek_lfu_key(&self) -> Option<&Key>
Peeks at the key for the next value to be evicted, if there is one. This will not increment the access counter for that value.
Sourcepub const fn capacity(&self) -> Option<NonZeroUsize>
pub const fn capacity(&self) -> Option<NonZeroUsize>
Returns the current capacity of the cache.
Sourcepub const fn len(&self) -> usize
pub const fn len(&self) -> usize
Returns the current number of items in the cache. This is a constant
time operation. Calling this method does not evict expired items, so it
is possible that this will include stale items. Consider calling
Self::evict_expired if this is a concern.
Sourcepub const fn is_empty(&self) -> bool
pub const fn is_empty(&self) -> bool
Returns if the cache contains no elements. Calling this method does not
evict expired items, so it is possible that this will include stale
items. Consider calling Self::evict_expired if this is a concern.
Sourcepub const fn is_unbounded(&self) -> bool
pub const fn is_unbounded(&self) -> bool
Returns if the cache is unbounded.
Sourcepub fn frequencies(&self) -> Vec<usize>
pub fn frequencies(&self) -> Vec<usize>
Returns the frequencies that this cache has. This is a linear time
operation. Calling this method does not evict expired items, so it is
possible that this will include stale items. Consider calling
Self::evict_expired if this is a concern.
Sourcepub fn shrink_to_fit(&mut self)
pub fn shrink_to_fit(&mut self)
Sets the capacity to the amount of objects currently in the cache. If
no items were in the cache, the cache becomes unbounded. Note that this
will evict expired items before shrinking, so it is recommended to
directly call Self::set_capacity for a more consistent size.
Sourcepub fn keys(&self) -> impl Iterator<Item = &Key> + FusedIterator + '_
pub fn keys(&self) -> impl Iterator<Item = &Key> + FusedIterator + '_
Returns an iterator over the keys of the LFU cache in any order. Note
that this will not automatically evict expired items, so stale items
may appear in the iterator. Consider calling Self::evict_expired if
this is a concern.
Sourcepub fn peek_values(&self) -> impl Iterator<Item = &Value> + FusedIterator + '_
pub fn peek_values(&self) -> impl Iterator<Item = &Value> + FusedIterator + '_
Returns an iterator over the values of the LFU cache in any order. Note
that this does not increment the count for any of the values and
will not automatically evict expired items, so stale items may appear
in the iterator. Consider calling Self::evict_expired if this is a
concern.
Sourcepub fn peek_iter(
&self,
) -> impl Iterator<Item = (&Key, &Value)> + FusedIterator + '_
pub fn peek_iter( &self, ) -> impl Iterator<Item = (&Key, &Value)> + FusedIterator + '_
Returns an iterator over the keys and values of the LFU cache in any
order. Note that this does not increment the count for any of the
values and will not automatically evict expired items, so stale items
may appear in the iterator. Consider calling Self::evict_expired
if this is a concern.
Sourcepub fn evict_expired(&mut self)
pub fn evict_expired(&mut self)
Manually evict expired entires. Note that it is possible to have stale entries after this method was called as it is possible for entries to have expired right after calling this function.
Trait Implementations§
Source§impl<Key: Hash + Eq, Value> Extend<(Key, Value)> for TimedLfuCache<Key, Value>
impl<Key: Hash + Eq, Value> Extend<(Key, Value)> for TimedLfuCache<Key, Value>
Source§fn extend<T: IntoIterator<Item = (Key, Value)>>(&mut self, iter: T)
fn extend<T: IntoIterator<Item = (Key, Value)>>(&mut self, iter: T)
Inserts the items from the iterator into the cache. Note that this may evict items if the number of elements in the iterator plus the number of current items in the cache exceeds the capacity of the cache.
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one)