tiered-cache-0.1.5 has been yanked.

tiered-cache

A high-performance multi-tiered cache implementation in Rust with automatic sizing and async support.

Features

🚀 Multiple cache tiers with automatic item placement based on size
⚡ Async support with Tokio
🔄 LRU eviction policy
📊 Detailed statistics for monitoring
🔍 Efficient lookup with DashMap
🛡️ Thread-safe design
📦 Zero unsafe code

Installation

Add this to your Cargo.toml:

[dependencies]
tiered-cache = "0.1.5"

Quick Start

use tiered_cache::{AutoCache, CacheConfig, TierConfig};
use std::time::Duration;

const MB: usize = 1024 * 1024;

// Configure a cache with two tiers
let config = CacheConfig {
    tiers: vec![
        TierConfig {
            total_capacity: 100 * MB,    // 100MB
            size_range: (0, 64 * 1024),  // 0-64KB
        },
        TierConfig {
            total_capacity: 900 * MB,    // 900MB
            size_range: (64 * 1024, MB), // 64KB-1MB
        },
    ],
    update_channel_size: 1024,
};

// Create the cache
let cache = AutoCache::<Vec<u8>, Vec<u8>>::new(config);

// Basic operations
cache.put(b"key1".to_vec(), vec![0; 1024]);
if let Some(value) = cache.get(&b"key1".to_vec()) {
    println!("Retrieved value of size: {}", value.len());
}

// Async get_or_update
let value = cache.get_or_update(b"key2".to_vec(), async {
    None // Returns None instead of Some(vec![0; 2048])
}).await;

Cache Configuration

The cache is configured using tiers, where each tier has:

A total capacity in bytes
A size range for entries (min_size, max_size)

Items are automatically placed in the appropriate tier based on their size. The cache uses the HeapSize trait to accurately measure memory usage.

Performance

The implementation uses:

DashMap for concurrent key-to-tier mapping
parking_lot locks for low contention
SmallVec for efficient tier storage
Cache-padded structures to prevent false sharing

Examples

See the examples directory for more usage examples, including:

Setting up a 1GB cache with multiple tiers
Handling different value sizes
Monitoring cache statistics

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

tiered-cache 0.1.5