Struct InMemoryCache 

pub struct InMemoryCache { /* private fields */ }

Available on native and crate feature cache only.

In-memory cache backend

Implementations

impl InMemoryCache

pub fn new() -> InMemoryCache

Available on crate features cache or static-files or storage only.

Create a new in-memory cache with naive cleanup strategy

Uses traditional O(n) full scan for cleanup. Suitable for small caches or when simplicity is preferred.

Examples

use reinhardt_utils::cache::InMemoryCache;

let cache = InMemoryCache::new();
// Cache is ready to use with no default TTL

pub fn with_layered_cleanup() -> InMemoryCache

Available on crate features cache or static-files or storage only.

Create a new in-memory cache with layered cleanup strategy

Uses Redis-style layered cleanup with O(1) amortized complexity:

• Passive expiration on access
• Active random sampling (default: 20 keys, 25% threshold)
• TTL index for batch cleanup

Recommended for caches with many entries or frequent TTL usage.

Performance

For caches with 100,000+ entries, layered cleanup is 100-1000x faster than naive cleanup.

Examples

use reinhardt_utils::cache::InMemoryCache;

let cache = InMemoryCache::with_layered_cleanup();
// Use layered cleanup for better performance

pub fn with_custom_layered_cleanup( sample_size: usize, threshold: f32, ) -> InMemoryCache

Available on crate features cache or static-files or storage only.

Create a new in-memory cache with custom layered cleanup parameters

Arguments

• sample_size - Number of keys to sample per cleanup round (default: 20)
• threshold - Threshold for expired entries to trigger another round (default: 0.25)

Examples

use reinhardt_utils::cache::InMemoryCache;

// Sample 50 keys per round, trigger next round if >30% expired
let cache = InMemoryCache::with_custom_layered_cleanup(50, 0.30);

pub fn with_default_ttl(self, ttl: Duration) -> InMemoryCache

Available on crate features cache or static-files or storage only.

Set a default TTL for all cache entries

Examples

use reinhardt_utils::cache::{InMemoryCache, Cache};
use std::time::Duration;

let cache = InMemoryCache::new()
    .with_default_ttl(Duration::from_secs(1));

// Set a value without explicit TTL
cache.set("key", &"value", None).await.unwrap();

// Wait for default TTL to expire

// Value should be expired
let value: Option<String> = cache.get("key").await.unwrap();
assert_eq!(value, None);

pub async fn cleanup_expired(&self)

Available on crate features cache or static-files or storage only.

Clean up expired entries

The cleanup strategy depends on how the cache was created:

• Naive strategy: O(n) full scan (simple but slow for large caches)
• Layered strategy: O(1) amortized (Redis-style, much faster)

Examples

use reinhardt_utils::cache::{InMemoryCache, Cache};
use std::time::Duration;

// Naive cleanup
let cache = InMemoryCache::new();

// Set a value with short TTL
cache.set("key1", &"value", Some(Duration::from_millis(10))).await.unwrap();

// Wait for expiration

// Clean up expired entries (O(n) scan)
cache.cleanup_expired().await;

// Verify the key is gone
assert!(!cache.has_key("key1").await.unwrap());

// Layered cleanup (faster for large caches)
let cache = InMemoryCache::with_layered_cleanup();
cache.set("key2", &"value", Some(Duration::from_millis(10))).await.unwrap();
cache.cleanup_expired().await; // O(1) amortized

pub async fn get_statistics(&self) -> CacheStatistics

Available on crate features cache or static-files or storage only.

Get cache statistics

Examples

use reinhardt_utils::cache::{InMemoryCache, Cache};

let cache = InMemoryCache::new();

// Set and get some values
cache.set("key1", &"value1", None).await.unwrap();
cache.set("key2", &"value2", None).await.unwrap();

let _: Option<String> = cache.get("key1").await.unwrap(); // Hit
let _: Option<String> = cache.get("key2").await.unwrap(); // Hit
let _: Option<String> = cache.get("key3").await.unwrap(); // Miss

let stats = cache.get_statistics().await;
assert_eq!(stats.hits, 2);
assert_eq!(stats.misses, 1);
assert_eq!(stats.total_requests, 3);
assert_eq!(stats.entry_count, 2);
assert_eq!(stats.hit_rate(), 2.0 / 3.0);

pub async fn list_keys(&self) -> Vec<String>

Available on crate features cache or static-files or storage only.

List all keys in the cache

Returns a vector of all keys currently stored in the cache, including expired entries that haven’t been cleaned up yet.

Examples

use reinhardt_utils::cache::{InMemoryCache, Cache};

let cache = InMemoryCache::new();

cache.set("key1", &"value1", None).await.unwrap();
cache.set("key2", &"value2", None).await.unwrap();
cache.set("key3", &"value3", None).await.unwrap();

let keys = cache.list_keys().await;
assert_eq!(keys.len(), 3);
assert!(keys.contains(&"key1".to_string()));
assert!(keys.contains(&"key2".to_string()));
assert!(keys.contains(&"key3".to_string()));

pub async fn inspect_entry_with_timestamps( &self, key: &str, ) -> Result<Option<(SystemTime, Option<SystemTime>)>, Error>

Available on crate features cache or static-files or storage only.

Inspect cache entry timestamps without deserializing the value

Returns the creation and last access timestamps for a cache entry. This is useful for session metadata retrieval without deserializing the full session data.

Arguments

• key - The cache key to inspect

Returns

• Ok(Some((created_at, accessed_at))) - Entry found with timestamps
• Ok(None) - Entry not found or expired
• Err(Error) - Error occurred during inspection

Examples

use reinhardt_utils::cache::{Cache, InMemoryCache};

let cache = InMemoryCache::new();
cache.set("session_123", &"session_data", None).await?;

if let Some((created, accessed)) = cache.inspect_entry_with_timestamps("session_123").await? {
    println!("Created at: {:?}", created);
    println!("Last accessed: {:?}", accessed);
}

pub async fn inspect_entry(&self, key: &str) -> Option<CacheEntryInfo>

Available on crate features cache or static-files or storage only.

Inspect a cache entry

Returns detailed information about a specific cache entry, or None if the entry doesn’t exist.

Examples

use reinhardt_utils::cache::{InMemoryCache, Cache};
use std::time::Duration;

let cache = InMemoryCache::new();

// Set a value with TTL
cache.set("key1", &"value1", Some(Duration::from_secs(300))).await.unwrap();

// Inspect the entry
let info = cache.inspect_entry("key1").await;
assert!(info.is_some());

let info = info.unwrap();
assert_eq!(info.key, "key1");
assert!(info.has_expiry);
assert!(info.ttl_seconds.is_some());
assert!(info.ttl_seconds.unwrap() <= 300);

// Non-existent key
let info = cache.inspect_entry("nonexistent").await;
assert!(info.is_none());

pub fn start_auto_cleanup(&self, interval: Duration)

Available on crate features cache or static-files or storage only.

Start automatic cleanup of expired entries

Spawns a background task that periodically removes expired entries from the cache. The task runs at the specified interval.

Examples

use reinhardt_utils::cache::InMemoryCache;
use std::time::Duration;

let cache = InMemoryCache::new();

// Start cleanup every 60 seconds
cache.start_auto_cleanup(Duration::from_secs(60));

// Cache will now automatically clean up expired entries

pub fn stop_auto_cleanup(&self)

Available on crate features cache or static-files or storage only.

Stop the background auto-cleanup task if one is running.

After calling this method, no further automatic cleanup will occur until start_auto_cleanup is called again.

pub fn with_auto_cleanup(self, interval: Duration) -> InMemoryCache

Available on crate features cache or static-files or storage only.

Set cleanup interval and start automatic cleanup

This is a builder method that sets the cleanup interval and immediately starts the background cleanup task.

Examples

use reinhardt_utils::cache::InMemoryCache;
use std::time::Duration;

let cache = InMemoryCache::new()
    .with_auto_cleanup(Duration::from_secs(60));

// Cache will automatically clean up expired entries every 60 seconds

Trait Implementations

impl Cache for InMemoryCache

fn get<'life0, 'life1, 'async_trait, T>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<T>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: for<'de> Deserialize<'de> + Send + 'async_trait, InMemoryCache: 'async_trait,

Get a value from the cache

fn set<'life0, 'life1, 'life2, 'async_trait, T>( &'life0 self, key: &'life1 str, value: &'life2 T, ttl: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, T: Serialize + Send + Sync + 'async_trait, InMemoryCache: 'async_trait,

Set a value in the cache with optional TTL

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, InMemoryCache: 'async_trait,

Delete a value from the cache

fn has_key<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, InMemoryCache: 'async_trait,

Check if a key exists in the cache

fn clear<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, InMemoryCache: 'async_trait,

Clear all values from the cache

fn get_many<'life0, 'life1, 'life2, 'async_trait, T>( &'life0 self, keys: &'life1 [&'life2 str], ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, T>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, T: for<'de> Deserialize<'de> + Serialize + Send + Sync + 'async_trait, Self: 'async_trait,

Get multiple values at once

fn set_many<'life0, 'async_trait, T>( &'life0 self, values: HashMap<String, T>, ttl: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, T: Serialize + Send + Sync + 'async_trait, Self: 'async_trait,

Set multiple values at once

fn delete_many<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, keys: &'life1 [&'life2 str], ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Delete multiple keys at once

fn incr<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, delta: i64, ) -> Pin<Box<dyn Future<Output = Result<i64, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Increment a numeric value

fn decr<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, delta: i64, ) -> Pin<Box<dyn Future<Output = Result<i64, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Decrement a numeric value

impl Clone for InMemoryCache

fn clone(&self) -> InMemoryCache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for InMemoryCache

fn default() -> InMemoryCache

Returns the “default value” for a type.