Struct LruCache

Source

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

Implementations§

Source §

impl<K, V> LruCache<K, V>
where K: Clone + Eq + Hash,

Source

pub fn new(shards_count: usize, cap_per_shard: usize) -> LruCache<K, V>

Creates a new instance of LruCache.

The cache is divided into multiple shards to improve concurrency by distributing the entries across different locks.

§Arguments

shards_count - The number of shards in the cache. Each shard acts as an independent LRU with its own capacity and order list.
cap_per_shard - The capacity for each shard, representing the maximum number of items it can hold before evicting the least recently used item(s).

§Returns

A new instance of LruCache.

§Examples

use threadsafe_lru::LruCache;

let cache: LruCache<i32, i32> = LruCache::new(4, 2); // Creates a cache with 4 shards and capacity of 2 entries per shard.

Source

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

Inserts a new key-value pair into the cache.

If the key already exists in the cache, its value is updated and it is promoted to the most recently used position. If inserting the new item causes the cache to exceed its capacity, the least recently used item will be evicted from its shard.

§Arguments

k - The key to insert or update.
v - The value associated with the key.

§Returns

If the key already existed in the cache and was updated, the previous value is returned. Otherwise, None is returned.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

let five = 5;
let six = 6;

assert_eq!(cache.insert(five, 10), None); // Inserts a new key-value pair
assert_eq!(cache.insert(six, 20), None); // Inserts another new key-value pair
assert_eq!(cache.insert(five, 30), Some(10)); // Updates an existing key with a new value and returns the old value

Source

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

Retrieves a value from the cache by key.

When a key is accessed using this method, it is promoted to the most recently used position in its shard. If the key does not exist in the cache, None is returned.

§Arguments

k - The key of the item to retrieve.

§Returns

The value associated with the key if it exists; otherwise, None.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

let five = 5;
let six = 6;

assert_eq!(cache.insert(five, 10), None);
assert_eq!(cache.get(&five), Some(10));

This method ensures that frequently accessed items remain more accessible while older or less frequently accessed items are evicted when necessary.

Source

pub fn get_mut<Q, F>(&self, k: &Q, func: F)
where K: Borrow<Q>, Q: Hash + Eq + ?Sized + ToOwned<Owned = K>, F: FnMut(Option<&mut V>),

Retrieves and mutates a value from the cache by key.

When a key is accessed using this method, it is promoted to the most recently used position in its shard. If the key does not exist in the cache, None is returned.

This function provides mutable access to the value associated with a given key, allowing you to modify its contents directly without needing to retrieve and re-insert it into the cache.

§Arguments

k - The key of the item to retrieve and mutate.
func - A closure that takes a mutable reference to the value (if present) and allows for in-place modifications.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

let five = 5;
let six = 6;

assert_eq!(cache.insert(five, 10), None);
cache.get_mut(&five, |v| {
  if let Some(v) = v {
     *v += 1
   }
});

This method ensures that frequently accessed items remain more accessible while older or less frequently accessed items are evicted when necessary.

Source

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

Removes a key-value pair from the cache by key.

When an item is removed from the cache using this method, its corresponding entry is deleted along with any references to it in the order list. If the key does not exist in the cache, None is returned.

This operation ensures that the cache maintains its integrity and correctly tracks the number of items stored.

§Arguments

k - The key of the item to remove.

§Returns

The value associated with the key if it existed; otherwise, None.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

let five = 5;
let six = 6;

assert_eq!(cache.insert(five, 10), None); // Inserts a new key-value pair
assert_eq!(cache.insert(six, 20), None); // Inserts another new key-value pair

assert_eq!(cache.remove(&five), Some(10)); // Removes the item with key five and returns its value
assert_eq!(cache.get(&five), None); // Key five no longer exists in the cache

Source

pub fn promote<Q>(&self, k: &Q)
where K: Borrow<Q>, Q: Hash + Eq + ?Sized + ToOwned<Owned = K>,

Promotes a key-value pair in the cache to the most recently used position.

When an item is accessed using this method, it is promoted to the most recently used position in its shard. If the key does not exist in the cache, no action is taken.

§Arguments

k - The key of the item to promote.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

let five = 5;
let six = 6;
let seven = 7;

assert_eq!(cache.insert(five, 10), None); // Inserts a new key-value pair
assert_eq!(cache.insert(six, 20), None); // Inserts another new key-value pair

cache.promote(&five);

assert_eq!(cache.insert(seven, 30), None); // Inserts another new key-value pair
assert_eq!(cache.get(&five), Some(10)); // Retrieving the promoted item

Source

pub fn len(&self) -> usize

Returns the total number of key-value pairs currently stored in the cache.

This method provides a quick way to check how many items are present in the cache without iterating over its contents.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

let five = 5;
let six = 6;

assert_eq!(cache.insert(five, 10), None); // Inserts a new key-value pair
assert_eq!(cache.len(), 1); // Cache now has one item

cache.insert(six, 20);
assert_eq!(cache.len(), 2); // Cache now has two items

cache.remove(&five);
assert_eq!(cache.len(), 1); // Cache now has only one item

let new_cache: LruCache<i32, i32> = LruCache::new(4, 2);
assert_eq!(new_cache.len(), 0); // New cache is empty

Source

pub fn is_empty(&self) -> bool

Checks if the cache is empty.

This method provides a quick way to determine whether the cache contains any key-value pairs without iterating over its contents.

§Examples

use threadsafe_lru::LruCache;

let cache = LruCache::new(4, 2);

assert!(cache.is_empty()); // Cache is empty upon creation

let five = 5;
let six = 6;

cache.insert(five, 10); // Inserting a key-value pair
assert!(!cache.is_empty()); // Cache is no longer empty

cache.remove(&five); // Removing the key-value pair
assert!(cache.is_empty()); // Cache is empty again after removal