tiered-cache 0.1.5

A high-performance multi-tiered cache with automatic sizing
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

# tiered-cache

[![Crates.io](https://img.shields.io/crates/v/tiered-cache.svg)](https://crates.io/crates/tiered-cache)
[![Documentation](https://docs.rs/tiered-cache/badge.svg)](https://docs.rs/tiered-cache)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)

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

```toml
[dependencies]
tiered-cache = "0.1.5"
```

## Quick Start

```rust
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](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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contributing

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