cache-mod 1.0.0

High-performance in-process caching with multiple eviction policies (LRU, LFU, TinyLFU, TTL, size-bounded). Async-safe, lock-minimized internals. Typed key-value API. No dependency on any external store.
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

# cache-mod v1.0.0 — Stable API

**The API freeze.** Every public symbol that landed across 0.2.0 – 0.9.0 is now committed under SemVer-strict guarantees. No new features in this release — the 1.0.0 milestone is the *stability commitment*. Consumers can pin `cache-mod = "1"` and expect minor / patch updates within the 1.x line to remain backwards-compatible per the SemVer contract.

## What is cache-mod?

High-performance in-process caching for Rust with five eviction policies all behind one trait — LRU, LFU, TTL, TinyLFU, and SizedCache. Async-safe (`&self` everywhere, `Send + Sync` cache instances), lock-minimized internals (sharded for entry-bounded caches, single-`Mutex` for `SizedCache`), typed key-value API. No dependency on any external store.

## What's in 1.0

The 0.2.0 – 0.9.0 cycle delivered the substance; this release is the stability lock. Eight milestones crossed the line during the pre-1.0 cycle and are all frozen at 1.0:

- **0.2.0 — Foundation.** The `Cache<K, V>` trait, `CacheError`, and `LruCache` reference implementation. Public surface shape established.
- **0.3.0 — LFU.** `LfuCache` lands. Counter-based eviction with LRU tie-break.
- **0.4.0 — TTL.** `TtlCache` lands. Per-entry deadlines, lazy expiry, soonest-expiry-first eviction, per-call TTL override via `insert_with_ttl`.
- **0.5.0 — TinyLFU + SizedCache.** `TinyLfuCache` (Count-Min Sketch admission filter) and `SizedCache` (byte-bound capacity) land. `proptest` harness and Criterion benchmark suite introduced. Public-surface roster is feature-complete from this point on.
- **0.6.0 — Arena-backed internals.** Algorithm-quality pass. LRU/TinyLFU/Sized switch to arena-backed doubly-linked lists with O(1) promote and O(1) eviction. LFU switches to a `BTreeMap<(count, age), K>` priority index for O(log n) eviction. Public surface unchanged.
- **0.7.0 — Sharded concurrency.** Internal `Mutex<Inner>` replaced by up to 16 independent shards (per-shard hash routing) for entry-bounded caches. Per-cache rationale: per-shard arena (LRU / TinyLFU), per-shard BTreeMap (LFU), per-shard HashMap (TTL), per-shard Count-Min Sketch (TinyLFU). `SizedCache` stays unsharded — splitting a weight budget across shards rejects values that should fit. Public surface unchanged.
- **0.9.0 — Hardening + audit.** `#[must_use]` on every value-returning trait method. Crate-level "Guarantees" section (no `unsafe`, no `panic!`, no background threads, no required runtime, `Send + Sync` everywhere). 9 new unit tests for sharding helpers. 8 new property tests (4 concurrent-safety + 4 cross-cache symmetry). `deny.toml` locks in license allow-list and advisory gate. 91 tests total.
- **1.0.0 — API freeze.** `docs/STABILITY.md` enumerates the frozen surface and the explicit SemVer commitments. CHANGELOG, README, API.md, and per-type rustdoc all updated to drop pre-1.0 language and stale forward-looking references. No code changes — library code is byte-identical to 0.9.0.

Skipped versions: **0.8.0** intentionally (the `SizedCache` sharding redesign hasn't surfaced as a real-world bottleneck; forcing it through would have been busywork during the audit window).

## The stability promise

[`docs/STABILITY.md`](https://github.com/jamesgober/cache-mod/blob/main/docs/STABILITY.md) lists every committed item. Highlights:

- **Strict SemVer.** Removing, renaming, or changing the signature of anything listed in the frozen surface requires a `2.0` release. Additive changes (new variants, methods, types, modules, feature flags, trait methods with default implementations) are minor.
- **MSRV is Rust 1.75**, frozen at 1.0.0. MSRV bumps within the 1.x line are advertised in the CHANGELOG but not treated as breaking.
- **Feature flags frozen.** `default = ["std"]` and the `std` feature are part of the public surface. New feature flags can be added in minor releases; existing ones cannot be renamed or removed without a major bump.
- **Behavioural contracts** documented at the trait / type level: `Cache::get` is an access, `contains_key` is a query (with the TTL lazy-expiry nuance), `Cache::insert` returns the previously-stored value except on `TinyLfuCache` where admission may reject, `Cache::clear` resets auxiliary state, the capacity invariant holds after every operation, eviction rules for each policy, `Send + Sync` predicates, and the no-`unsafe` / no-`panic` guarantee.
- **Explicitly NOT promised:** exact eviction order beyond what the contracts commit to, internal data-structure choices (arena layouts, BTreeMap, Count-Min Sketch parameters), shard count and the sharding heuristic, performance characteristics, error message text, hash function used for shard routing, anything `pub(crate)` or `#[doc(hidden)]`, the exact dev-dependency list, the `Cargo.lock` contents.

## Breaking changes

**None.** Every existing 0.9.0 call-site compiles and behaves identically against 1.0.0. The `#[must_use]` warnings introduced in 0.9.0 remain warnings, not errors.

## Verification

Local run on Windows x86_64, Rust stable; identical commands pass on Linux and via the configured CI matrix (Linux / macOS / Windows on stable + MSRV 1.75):

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --all-targets --no-default-features -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features                # RUSTDOCFLAGS="-D warnings"
cargo deny check all                              # optional, license + advisory gate
cargo build --benches --release                   # criterion suite compiles
```

All green. Same test totals as 0.9.0 (zero new test code in 1.0.0):

- Unit tests: **9 passed** (sharding helpers).
- Integration tests: **47 passed**.
- Property tests (proptest): **17 passed** (5 capacity invariants × 5 cache types + 4 concurrent-safety + 4 cross-cache symmetry + 4 round-trip).
- Doctests: **18 passed**.
- **91 tests total.**

REPS lint surface declared in `src/lib.rs` honored: every `deny(...)` clippy / rustc lint still applies. No `unsafe` is used anywhere in the crate. The single `#[allow(clippy::ptr_arg)]` in `tests/smoke.rs` is justified inline (function-pointer signature must match `V`).

## What's next after 1.0

The 1.x roadmap is intentionally undocumented at the SemVer level — additive changes happen as a normal part of minor / patch development. Known-future-work items that could justify a 2.0:

- A `Borrow<Q>`-generic lookup API on `Cache::get` / `contains_key` / `remove` if the additive form turns out to be insufficient.
- Replacing `fn(&V) -> usize` weighers on `SizedCache` with a generic `Weigh<V>` trait, if there is sufficient demand for state-carrying weighers.
- A meaningfully-incompatible eviction policy change (e.g. switching `TinyLfuCache` to full W-TinyLFU with SLRU+doorkeeper if the surface had to change to expose the new structure).
- An MSRV jump large enough to force a deliberate decision (currently no such jump is on the roadmap; 1.75 supports every pattern the crate uses).

Any of these would land on `main` behind a `2.0-pre` cycle first.

## Installation

```toml
[dependencies]
cache-mod = "1"

# Useful when you want to opt out of the std-dependent cache types:
cache-mod = { version = "1", default-features = false }
```

MSRV: Rust 1.75. Edition 2021. `default-features = ["std"]`.

## Quick start

```rust
use cache_mod::{Cache, LruCache};

let cache: LruCache<&'static str, u32> = LruCache::new(1024).expect("capacity > 0");

cache.insert("requests", 1);
cache.insert("errors", 0);

assert_eq!(cache.get(&"requests"), Some(1));
assert_eq!(cache.len(), 2);
```

Every cache type implements the same `Cache<K, V>` trait — swap `LruCache` for `LfuCache`, `TtlCache`, `TinyLfuCache`, or `SizedCache` to change the eviction policy without changing the call sites.

## Documentation

- [README](https://github.com/jamesgober/cache-mod/blob/main/README.md)
- [API reference (full)](https://github.com/jamesgober/cache-mod/blob/main/docs/API.md)
- [**Stability promise**](https://github.com/jamesgober/cache-mod/blob/main/docs/STABILITY.md)
- [CHANGELOG](https://github.com/jamesgober/cache-mod/blob/main/CHANGELOG.md)
- [REPS standards](https://github.com/jamesgober/cache-mod/blob/main/REPS.md)
- [docs.rs/cache-mod/1.0.0](https://docs.rs/cache-mod/1.0.0)

---

**Full diff:** [`v0.9.0...v1.0.0`](https://github.com/jamesgober/cache-mod/compare/v0.9.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/cache-mod/blob/main/CHANGELOG.md#100---2026-05-21).