# cachekit
[](https://github.com/OxidizeLabs/cachekit/actions/workflows/ci.yml)
[](https://crates.io/crates/cachekit)
[](https://docs.rs/cachekit)
[](https://github.com/OxidizeLabs/cachekit/blob/main/Cargo.toml)
[](LICENSE-MIT)
[](LICENSE-APACHE)
**High-performance cache policies and tiered caching primitives for Rust systems with optional metrics and benchmarks.**
## Overview
CacheKit is a Rust library that provides:
- High-performance cache replacement policies (e.g., **FIFO**, **LRU**, **LRU-K**).
- Tiered caching primitives to build layered caching strategies.
- Optional metrics and benchmark harnesses.
- A modular API suitable for embedding in systems where control over caching behavior is critical.
This crate is designed for systems programming, microservices, and performance-critical applications.
## Features
- Policy implementations optimized for performance and predictability.
- Backends that support both in-memory and composite cache strategies.
- Optional integration with metrics collectors (e.g., Prometheus/metrics crates).
- Benchmarks to compare policy performance under real-world workloads.
- Idiomatic Rust API with `no_std` compatibility where appropriate.
## Installation
Add `cachekit` as a dependency in your `Cargo.toml`:
```toml
[dependencies]
cachekit = { git = "https://github.com/OxidizeLabs/cachekit" }
```
## Quick Start
### Using the Builder (Recommended)
The `CacheBuilder` provides a unified API for creating caches with any eviction policy:
```rust
use cachekit::builder::{CacheBuilder, CachePolicy};
fn main() {
// Create an LRU cache with a capacity of 100 entries
let mut cache = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Lru);
// Insert items
cache.insert(1, "value1".to_string());
cache.insert(2, "value2".to_string());
// Retrieve an item
if let Some(value) = cache.get(&1) {
println!("Got from cache: {}", value);
}
// Check existence and size
assert!(cache.contains(&1));
assert_eq!(cache.len(), 2);
}
```
### Available Policies
```rust
use cachekit::builder::{CacheBuilder, CachePolicy};
// FIFO - First In, First Out
let fifo = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Fifo);
// LRU - Least Recently Used
let lru = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Lru);
// LRU-K - Scan-resistant LRU (K=2 is common)
let lru_k = CacheBuilder::new(100).build::<u64, String>(CachePolicy::LruK { k: 2 });
// LFU - Least Frequently Used (bucket-based, O(1))
let lfu = CacheBuilder::new(100).build::<u64, String>(CachePolicy::Lfu);
// HeapLFU - Least Frequently Used (heap-based, O(log n))
let heap_lfu = CacheBuilder::new(100).build::<u64, String>(CachePolicy::HeapLfu);
// 2Q - Two-Queue with configurable probation fraction
let two_q = CacheBuilder::new(100).build::<u64, String>(
CachePolicy::TwoQ { probation_frac: 0.25 }
);
```
### Policy Selection Guide
| FIFO | Simple, predictable workloads | Insertion order |
| LRU | Temporal locality | Recency |
| LRU-K | Scan-resistant workloads | K-th access time |
| LFU | Stable access patterns | Frequency (O(1)) |
| HeapLFU | Large caches, frequent evictions | Frequency (O(log n)) |
| 2Q | Mixed workloads | Two-queue promotion |
### Direct Policy Access
For advanced use cases requiring policy-specific operations, use the underlying implementations directly:
```rust
use std::sync::Arc;
use cachekit::policy::lru::LruCore;
use cachekit::traits::{CoreCache, LruCacheTrait};
fn main() {
let mut cache: LruCore<u64, &str> = LruCore::new(100);
cache.insert(1, Arc::new("value"));
// Policy-specific operations
if let Some((key, _)) = cache.peek_lru() {
println!("LRU key: {}", key);
}
}
```