Mini Moka

Because mini_moka::sync::Cache::get returns a clone of the value (Option<V>) rather than a reference (Option<&V>), retrieving large or expensive-to-clone values can impact performance.

To mitigate this, wrap your values in std::sync::Arc. Cloning an Arc is a cheap operation that only increments a reference count, rather than copying the underlying data.

use std::sync::Arc;
use mini_moka::sync::Cache;

let cache: Cache<usize, Arc<Vec<u8>>> = Cache::new(100);
let large_value = vec![0u8; 2 * 1024 * 1024]; // 2 MiB

// Wrap in Arc before inserting
cache.insert(1, Arc::new(large_value));

// get() will call Arc::clone(), which is very fast
let retrieved = cache.get(&1);

To use Mini Moka in your Rust project, add it to your Cargo.toml dependencies:

[dependencies]
mini_moka = "0.10"

Mini Moka provides two primary cache implementations depending on your concurrency requirements:

1. Thread-safe, highly concurrent cache: Use the sync::Cache module when you need to share the cache across multiple threads. This requires the sync feature to be enabled.
2. Non-thread-safe, single-threaded cache: Use the unsync::Cache module for applications running in a single thread where thread-safety is not required.

Both implementations support bounding (by entry count or weighted size), expiration policies (TTL/TTI), and eviction algorithms inspired by Caffeine (LFU admission and LRU eviction).

// Example of selecting the appropriate module:
// For multi-threaded use (requires 'sync' feature):
// use mini_moka::sync::Cache;

// For single-threaded use:
use mini_moka::unsync::Cache;

Mini Moka uses the Policy abstraction to manage how entries are admitted, evicted, and expired.

Key capabilities include:

• Bounding: Limit the cache by the maximum number of entries or by the total weighted size of entries (Size-aware eviction).
• Expiration:
  • Time to Live (TTL): Evict entries after a certain duration since creation.
  • Time to Idle (TTI): Evict entries after a certain duration since their last access.
• Eviction Algorithms: Uses a combination of Least Frequently Used (LFU) for admission control and Least Recently Used (LRU) for eviction.

Mini Moka supports two types of expiration policies via the CacheBuilder:

1. Time to Live (TTL): An entry expires after a fixed duration has passed since it was inserted.
2. Time to Idle (TTI): An entry expires after a fixed duration has passed since it was last accessed (via get) or inserted.

Note: The builder will panic if you attempt to set a duration longer than 1000 years to prevent overflow errors during expiration calculations.

use mini_moka::sync::Cache;
use std::time::Duration;

let cache = Cache::builder()
    // TTL: Expires 30 minutes after insertion
    .time_to_live(Duration::from_secs(30 * 60))
    // TTI: Expires 5 minutes after last access/insertion
    .time_to_idle(Duration::from_secs(5 * 60))
    .build();

cache.insert(0, "zero");
// This get() extends the entry's life for another 5 minutes (TTI)
cache.get(&0);

By default, caches are bounded by the maximum number of entries. If your entries have varying memory footprints, you can use a weigher to bound the cache by total weighted size instead.

Use Cache::builder() to configure a weigher closure. The closure receives the key and value and must return a u32 representing the relative size. The cache will then evict entries when the sum of these weights exceeds max_capacity.

use mini_moka::sync::Cache;

let cache = Cache::builder()
    // The weigher returns the byte length of the String as the weight
    .weigher(|_key, value: &String| -> u32 {
        value.len().try_into().unwrap_or(u32::MAX)
    })
    // The cache will hold up to 32MiB of total weight
    .max_capacity(32 * 1024 * 1024)
    .build();

cache.insert(0, "zero".to_string());

The ConcurrentCacheExt trait provides a sync() method for concurrent cache implementations. This method performs any pending maintenance operations (such as eviction or expiration) that the cache might have deferred. It is primarily intended for use in testing environments to ensure the cache state is up-to-date before assertions.

use mini_moka::ConcurrentCacheExt;

// Assuming `cache` is an instance of a concurrent cache
cache.sync();

If you need to use a specific hashing algorithm (instead of the default RandomState), use the build_with_hasher method on the CacheBuilder.

// Assuming S implements BuildHasher + Clone + Send + Sync + 'static
let cache = Cache::builder()
    .max_capacity(100)
    .build_with_hasher(my_custom_hasher);

The unsync module provides a non-thread-safe, single-threaded cache implementation built upon std::collections::HashMap. This is suitable for scenarios where you do not need to share the cache across multiple threads and want to avoid the overhead of synchronization primitives like Mutex or RwLock.

use mini_moka::unsync::{Cache, CacheBuilder};

// Example of building and using an unsync cache
let cache = CacheBuilder::new()
    .build();

cache.insert("key", "value");
let val = cache.get("key");