Struct qlrumap::LruMap

pub struct LruMap<K, V> where
    K: Eq + Hash,  { /* private fields */ }

A HashMap which maintains an internal last recently used node list.

Implementations

impl<K, V> LruMap<K, V> where
    K: Eq + Hash, 

pub fn new() -> Self

Create a new LRU HashMap, without node expiry TTL.

pub fn with_ttl(dur: Duration) -> Self

Create a new LRU HashMap, with node TTL’s.

An LruMap with a TTL can call LruMap::drain_timedout() to return an iterator that will return items that have become stale.

pub fn is_empty(&self) -> bool

Return true if the container is empty. Return false otherwise.

use qlrumap::LruMap;

let mut map = LruMap::new();
assert_eq!(map.is_empty(), true);
map.insert(1, 1);
assert_eq!(map.is_empty(), false);

pub fn len(&self) -> usize

Return the number of elements in the container.

pub fn clear(&mut self)

Remove all nodes from the LruMap.

pub fn insert(&mut self, key: K, value: V) -> Option<V>

Add a new entry to the container. New nodes will be the least recently used node.

Adding a new node:

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
assert_eq!(map.len(), 1);

Adding an already existing key will replace the value, and return the old one:

use qlrumap::LruMap;

// Create a new LruMap, and insert a test node, make sure length == 1.
let mut map = LruMap::new();
map.insert(1, 1);
assert_eq!(map.len(), 1);

// Insert another value, with the same key, make sure length is
// unchanged and make sure the returned value is the old value.
let v = map.insert(1, 2);
assert_eq!(map.len(), 1);
assert_eq!(v, Some(1));

// Make sure the stored value is the new value.
let v = map.get(&1);
assert_eq!(v, Some(&2));

pub fn get<Q: ?Sized>(&mut self, k: &Q) -> Option<&V> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Given a reference to a key return the value associated with it. The map entry will be moved to the front of the internal lru list. If the LruMap has a TTL configured, the node’s timeout will be reset.

pub fn get_mut<Q: ?Sized>(&mut self, k: &Q) -> Option<&mut V> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

pub fn remove<Q: ?Sized>(&mut self, k: &Q) -> Option<V> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Remove a node from the map based on its key. Returns the value if its key was found in the map.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
let v = map.remove(&1);
assert_eq!(v, Some(1));
assert!(map.is_empty());

pub fn touch<Q: ?Sized>(&mut self, k: &Q) -> bool where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Move a node to the front of the LRU list given a key.

Returns true if the key exists in the map. Returns false otherwise.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
map.insert(2, 2);
assert_eq!(map.oldest(), Some((&1, &1)));
map.touch(&1);
assert_eq!(map.oldest(), Some((&2, &2)));

pub fn pop(&mut self) -> Option<(K, V)>

Remove and return the oldest node.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
map.insert(2, 2);
assert_eq!(map.pop(), Some((1, 1)));
assert_eq!(map.pop(), Some((2, 2)));
assert_eq!(map.pop(), None);
assert!(map.is_empty());

pub fn youngest(&self) -> Option<(&K, &V)>

Get the least recently used (youngest) node.

Does not update the node’s timestamp.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
map.insert(2, 2);
assert_eq!(map.youngest(), Some((&2, &2)));

pub fn oldest(&self) -> Option<(&K, &V)>

Get the oldest node.

Does not update the node’s timestamp.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
map.insert(2, 2);
assert_eq!(map.oldest(), Some((&1, &1)));

pub fn drain(&mut self) -> Drain<'_, K, V>

Return an iterator that will yield all the elements of the LruMap.

pub fn drain_ordered(&mut self) -> DrainOrdered<'_, K, V>

Return an iterator that will yield all the elements of the LruMap, ordered.

The youngest node will be returned first.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, "elena");
map.insert(2, "chloe");
map.insert(3, "drake");

// make second entry the youngest
map.touch(&2);

let v: Vec<(u32, &str)> = map.drain_ordered().collect();
assert_eq!(v[0], (2, "chloe"));
assert_eq!(v[1], (3, "drake"));
assert_eq!(v[2], (1, "elena"));

assert!(map.is_empty());

pub fn drain_filter<F>(&mut self, f: F) -> DrainFilter<'_, K, V, F> where
    F: FnMut(&K, &mut V) -> bool, 

Drain nodes using a closure to validate notes to be drained.

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
map.insert(2, 2);
map.insert(3, 3);
let mut it = map.drain_filter(|k, v| {
  // drain second element
  *k == 2 && *v == 2
});

assert_eq!(it.next(), Some((2, 2)));
assert_eq!(it.next(), None);
drop(it);

assert_eq!(map.len(), 2);
assert_eq!(map.oldest(), Some((&1, &1)));
assert_eq!(map.youngest(), Some((&3, &3)));

pub fn drain_timedout(&mut self) -> DrainTimedout<'_, K, V>

Drain entries that have timed out.

To cap the number of elements in the LruMap and also remove stale elements in one call, use LruMap::drain_old().

Notes

• The timestamp used to check if nodes have expired is generated and stored in the iterator when it is created. This implies that expiration candidacy is effectively determined when drain_timeout() is called, and not when the iterator’s next() method is called.

pub fn drain_overflow(&mut self, lim: usize) -> DrainOverflow<'_, K, V>

Cap the number of entries in the map.

Creates a draining iterator which will return the oldest entries until there are lim remaining entries in the map.

To cap the number of elements in the LruMap and also remove stale elements in one call, use LruMap::drain_old().

use qlrumap::LruMap;

let mut map = LruMap::new();
map.insert(1, 1);
map.insert(2, 2);

let mut drain = map.drain_overflow(2);
assert_eq!(drain.next(), None);
drop(drain);

map.insert(3, 3);

let mut drain = map.drain_overflow(2);
assert_eq!(drain.next(), Some((1, 1)));
assert_eq!(drain.next(), None);

pub fn drain_old(&mut self, cap: Option<usize>) -> DrainOld<'_, K, V>

Remove old entries and return them in an iterator.

If the cap parameter is set then the oldest node will be removed until the number of elements is equal to or lower than this value.

use std::time::Duration;
use qlrumap::LruMap;

let mut map = LruMap::with_ttl(Duration::from_secs(10));
map.insert(1, "elena");
map.insert(2, "chloe");
map.insert(3, "drake");

map.touch(&1);
map.touch(&2);

// Limit map to 2 entries, use current time as expiry
let mut drain = map.drain_old(Some(2));

assert_eq!(drain.next(), Some((3, "drake")));
assert_eq!(drain.next(), None);

Trait Implementations

impl<K, V> Drop for LruMap<K, V> where
    K: Eq + Hash, 

fn drop(&mut self)

Executes the destructor for this type.