Struct TimedMap

pub struct TimedMap<C, K, V> { /* private fields */ }

Associates keys of type K with values of type V. Each entry may optionally expire after a specified duration.

Mutable functions automatically clears expired entries when called.

If no expiration is set, the entry remains constant.

Implementations

impl<C, K, V> TimedMap<C, K, V>

where C: Clock, K: GenericKey,

pub fn new() -> Self

Creates an empty map.

pub fn new_with_map_kind(map_kind: MapKind) -> Self

Creates an empty map based on the chosen map implementation specified by MapKind.

pub fn expiration_tick_cap(self, expiration_tick_cap: u16) -> Self

Configures expiration_tick_cap, which sets how often TimedMap::drop_expired_entries is automatically called. The default value is 1.

On each insert (excluding unchecked ones), an internal counter expiration_tick is incremented. When expiration_tick meets or exceeds expiration_tick_cap, TimedMap::drop_expired_entries is triggered to remove expired entries.

Use this to control cleanup frequency and optimize performance. For example, if your workload involves about 100 inserts within couple seconds, setting expiration_tick_cap to 100 can improve the performance significantly.

pub fn get(&self, k: &K) -> Option<&V>

Returns the associated value if present and not expired.

To retrieve the value without checking expiration, use TimedMap::get_unchecked.

pub fn get_mut(&mut self, k: &K) -> Option<&mut V>

Returns a mutable reference to the value corresponding to the key.

To retrieve the value without checking expiration, use TimedMap::get_unchecked.

pub fn get_unchecked(&self, k: &K) -> Option<&V>

Returns the associated value if present, regardless of whether it is expired.

If you only want non-expired entries, use TimedMap::get instead.

pub fn get_unchecked_mut(&mut self, k: &K) -> Option<&mut V>

Returns a mutable reference to the associated value if present, regardless of whether it is expired.

If you only want non-expired entries, use TimedMap::get instead.

pub fn get_remaining_duration(&self, k: &K) -> Option<Duration>

Returns the associated value’s Duration if present and not expired.

Returns None if the entry does not exist or is constant.

pub fn insert_expirable(&mut self, k: K, v: V, duration: Duration) -> Option<V>

Inserts a key-value pair with an expiration duration, and then drops the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you don’t want to the check expired entries, consider using TimedMap::insert_expirable_unchecked instead.

pub fn insert_expirable_unchecked( &mut self, k: K, v: V, duration: Duration, ) -> Option<V>

Inserts a key-value pair with an expiration duration, without checking the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you want to check the expired entries, consider using TimedMap::insert_expirable instead.

pub fn insert_constant(&mut self, k: K, v: V) -> Option<V>

Inserts a key-value pair with that doesn’t expire, and then drops the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you don’t want to check the expired entries, consider using TimedMap::insert_constant_unchecked instead.

pub fn insert_constant_unchecked(&mut self, k: K, v: V) -> Option<V>

Inserts a key-value pair with that doesn’t expire without checking the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you want to check the expired entries, consider using TimedMap::insert_constant instead.

pub fn remove(&mut self, k: &K) -> Option<V>

Removes a key-value pair from the map and returns the associated value if present and not expired.

If you want to retrieve the entry after removal even if it is expired, consider using TimedMap::remove_unchecked.

pub fn remove_unchecked(&mut self, k: &K) -> Option<V>

Removes a key-value pair from the map and returns the associated value if present, regardless of expiration status.

If you only want the entry when it is not expired, consider using TimedMap::remove.

pub fn clear(&mut self)

Clears the map, removing all elements.

pub fn drop_expired_entries(&mut self)

Clears expired entries from the map.

Call this function when using *_unchecked inserts, as these do not automatically clear expired entries.

Trait Implementations

impl<C: Debug, K: Debug, V: Debug> Debug for TimedMap<C, K, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C, K, V> Default for TimedMap<C, K, V>

fn default() -> Self

Returns the “default value” for a type.