fncache 0.1.2

A zero-boilerplate Rust library for function-level caching with pluggable backends
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# fncache

[![Crates.io](https://img.shields.io/crates/v/fncache.svg)](https://crates.io/crates/fncache)
[![Documentation](https://docs.rs/fncache/badge.svg)](https://docs.rs/fncache)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

```toml
[dependencies]
fncache = { version = "0.1.1", features = ["memory"] }
tokio = { version = "1", features = ["full"] }
futures = "0.3"
```

### Basic Usage

```rust
use fncache::{
    backends::memory::MemoryBackend,
    init_global_cache,
    fncache,
    Result,
};
use std::time::Instant;

#[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 t1 = Instant::now();
    let result1 = expensive_operation(5);
    let d1 = t1.elapsed();
    println!("Result 1: {} (took {:?})", result1, d1); // ~1s
    
    // Second call returns cached result
    let t2 = Instant::now();
    let result2 = expensive_operation(5);
    let d2 = t2.elapsed();
    println!("Result 2: {} (took {:?})", result2, d2); // microseconds
    
    Ok(())
}
```

Note: The first call performs the real work (~1s here). Subsequent calls with the same arguments return the cached result in microseconds.

### Async Function Example

```rust
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

- **Memory backend**: see `examples/backend_memory.rs`
  - Run: `cargo run --example backend_memory`

- **File backend**: see `examples/backend_file.rs`
  - Run: `cargo run --example backend_file --features file-backend`

- **Redis backend**: see `examples/backend_redis.rs`
  - Requires a running Redis server at `redis://127.0.0.1:6379`
  - Run: `cargo run --example backend_redis --features redis-backend`

## Available Features

| Feature | Description | Default |
|---------|-------------|----------|
| `memory` | In-memory cache backend | ✅ |
| `redis-backend` | Redis backend support | ❌ |
| `file-backend` | File-based persistent cache | ❌ |
| `rocksdb-backend` | RocksDB high-performance backend | ❌ |
| `metrics` | Performance metrics collection | ✅ |
| `invalidation` | Tag-based cache invalidation | ✅ |

## Requirements

- **Rust**: 1.70+
- **Runtime**: `tokio` only if you use async cached functions or run async examples
- **Features/Backends**: enable via Cargo features (see table above)

## 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](ARCHITECTURE.md) - Internal design and architecture

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

## License

MIT License - see [LICENSE](LICENSE) for details.