bhandaar (भंडार)
On-disk LRU/TTL file cache for Rust with cross-process concurrency via flock(2).
bhandaar (भंडार) — Hindi for "storehouse, repository"
Features
- LRU eviction — least recently used entries are evicted first
- TTL support — per-entry time-to-live with lazy expiration
- Cross-process safe — uses
filockforflock(2)locking - Sharded design — user-defined shard count for concurrent access
- Greedy storage — fills up to max size, evicts only when needed
- Streaming API — handle large files without loading into memory
- Two-level hashing — SHA-256-based directory nesting, supports millions of entries
Quick Start
use ;
use Duration;
API
In-Memory API (for small data)
// Put
cache.put?;
cache.put_with_ttl?;
// Get (loads entire file into memory)
let data = cache.get?;
// Check existence
let exists = cache.contains?;
// Remove
let removed = cache.remove?;
// Get all keys
let keys = cache.keys?;
// Clear all entries
cache.clear?;
// Get current size
let size = cache.size;
Streaming API (for large files)
// Get a file handle — nothing loaded into memory
if let Some = cache.get_file?
// Stream data into a writer
use Write;
let mut writer = new;
cache.get_file?
.map;
// Put from a reader (streaming write)
let reader = new;
cache.put_reader?; // size must be known
// Put from a reader (auto-detect size)
let reader = new;
let actual_size = cache.put_reader_auto_size?;
Error Handling
use BhandaarError;
match cache.put
S3 Cache Example
Use bhandaar as a local disk cache for S3 objects:
// See examples/s3_cache.rs for full implementation
Architecture
Directory Structure
Files are stored using two-level SHA-256 hashing:
cache_root/
├── a1/
│ ├── b2/
│ │ ├── c3d4e5f6g7h8.dat # Cached file
│ │ ├── c3d4e5f6g7h8.dat.meta # Sidecar metadata (bincode)
│ │ └── ...
│ └── ...
└── ...
- Max ~65K directories at each level
- <10K files per leaf directory
- Supports millions of entries
Concurrency Model
- Per-shard locking — each shard has its own Mutex for in-process coordination
- filock integration — per-file
flock(2)for cross-process safety - Atomic size tracking — lock-free total size counter
Eviction Strategy
- LRU — least recently used entries evicted first
- TTL — expired entries lazily deleted on access
- Greedy — fills up to max size, evicts only when needed
Streaming Design
get_file()— returnsstd::fs::Filehandle for streaming readsput_reader()— streams data fromReadtrait to diskput_reader_auto_size()— streams without knowing size upfront- Zero memory overhead — large files never loaded entirely into RAM
License
MIT — see LICENSE for details.