fncache

A zero-boilerplate Rust library for function-level caching with pluggable backends, inspired by functools.lru_cache and request-cache.

Features

• 🚀 Zero Boilerplate: Simple #[fncache] attribute for instant caching
• 🔌 Pluggable Backends: Memory, File, Redis, RocksDB support
• ⚡ Async/Sync: Seamless support for both synchronous and asynchronous functions
• 🛡️ Type Safety: Strong typing throughout the caching layer with compile-time guarantees
• 📊 Advanced Metrics: Built-in instrumentation with latency, hit rates, and size tracking
• 🏷️ Cache Invalidation: Tag-based and prefix-based cache invalidation
• 🔥 Background Warming: Proactive cache population for improved performance

Quick Start

Add fncache to your Cargo.toml with the desired features:

[dependencies]
fncache = { version = "0.1", features = ["memory"] }

Basic Usage

use fncache::{
    backends::memory::MemoryBackend,
    init_global_cache,
    fncache,
    Result,
};

#[fncache(ttl = 60)]
fn expensive_operation(x: u64) -> u64 {
    println!("Performing expensive operation for {}", x);
    std::thread::sleep(std::time::Duration::from_secs(1));
    x * x
}

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize with memory backend
    init_global_cache(MemoryBackend::new())?;
    
    // First call executes the function
    let result1 = expensive_operation(5);
    println!("Result 1: {}", result1); // Takes ~1 second
    
    // Second call returns cached result
    let result2 = expensive_operation(5);
    println!("Result 2: {}", result2); // Returns immediately
    
    Ok(())
}

Async Function Example

use std::time::Duration;
use tokio::time::sleep;

#[fncache(ttl = 300)]
async fn fetch_data(id: &str) -> String {
    println!("Fetching data for {}", id);
    sleep(Duration::from_secs(1)).await;
    format!("Data for {}", id)
}

Backend Examples

Redis Backend

use fncache::backends::redis::RedisBackend;

#[tokio::main]
async fn main() -> Result<()> {
    let backend = RedisBackend::new("redis://localhost:6379")?;
    init_global_cache(backend)?;
    
    // Your cached functions work the same way
    Ok(())
}

File Backend

use fncache::backends::file::FileBackend;

fn main() -> Result<()> {
    let backend = FileBackend::new("/tmp/cache")?;
    init_global_cache(backend)?;
    Ok(())
}

Available Features

Requirements

• Rust: 1.70 or later
• Runtime: tokio for async support
• Dependencies: Automatically managed via features

Performance

• Memory Backend: ~1-2μs set latency, ~850-970μs get hit latency
• Redis Backend: ~1ms cache hit latency (network dependent)
• File Backend: ~100μs cache hit latency
• Throughput: Thousands of operations/second (memory backend)

See benches/ for detailed benchmarks.

Documentation

• Architecture - Internal design and architecture

Changelog

See CHANGELOG.md for version history and breaking changes.

License

MIT License - see LICENSE for details.