caffeine

# Caffeine

High-performance, near-optimal caching library for Java 11+.

## Build & Test

```bash
./gradlew :caffeine:build                                    # Full build
./gradlew :caffeine:test --tests 'ClassName'                 # Single test class
./gradlew :caffeine:test --tests 'ClassName.methodName'      # Single method
./gradlew :caffeine:compileTestJava                          # Compile tests only
```

A single test method is fine to run even when it sweeps the full `@CacheSpec` matrix; it's whole
classes and the full suite to avoid locally, or to narrow with the `-P` flags below. CI runs the
full matrix sharded across 40 workers. See `.claude/rules/testing.md`.

### Test Filtering

```bash
./gradlew :caffeine:test -Pimplementation=caffeine  # Cache type (caffeine/guava)
./gradlew :caffeine:test -Pkeys=strong              # Key reference (strong/weak)
./gradlew :caffeine:test -Pvalues=strong            # Value reference (strong/weak/soft)
./gradlew :caffeine:test -Pcompute=sync             # Compute mode (sync/async)
./gradlew :caffeine:test -Pstats=enabled            # Stats recording (enabled/disabled)
```

### Specialized Test Suites

```bash
./gradlew :caffeine:frayTest         # Fray concurrency interleaving
./gradlew :caffeine:lincheckTest     # LinCheck linearizability
./gradlew :caffeine:fuzzTest         # Fuzzing (Jazzer)
./gradlew :caffeine:jcstress         # JCStress concurrency stress tests
./gradlew :caffeine:googleTest       # Guava collections tests
./gradlew :caffeine:apacheTest       # Apache Commons collections tests
./gradlew :caffeine:eclipseTest      # Eclipse Collections' collections tests
./gradlew :caffeine:jctoolsTest      # JCTools collections tests
./gradlew :caffeine:jsr166Test       # JSR-166 collections tests
./gradlew :caffeine:openjdkTest      # OpenJDK collections tests
./gradlew :caffeine:moduleTest       # Java module system tests
./gradlew :caffeine:osgiTest         # OSGi bundle tests
```

Tests cannot be `@Disabled` or skipped: a test that JUnit reports as skipped fails the build, though a task that Gradle skips with `onlyIf` runs no tests and does not.

### Static Analysis

```bash
./gradlew :caffeine:build -Pspotbugs  # SpotBugs
./gradlew :caffeine:build -Ppmd       # PMD
.github/scripts/analyze.sh            # all
```

ErrorProne + NullAway run on every build. Prefer fixing warnings over suppressing them; see
`.claude/rules/errorprone.md` for the few sanctioned suppressions and how to write them.

### Benchmarks & Analysis

```bash
./gradlew jmh -PincludePattern=GetPutBenchmark               # JMH microbenchmarks
./gradlew :caffeine:memoryOverhead                           # JOL object layout analysis
./gradlew :caffeine:stress --workload read --duration PT30S  # Stress testing (read, write, refresh)
```

Use [/optimize-cache](skills/optimize-cache/SKILL.md) for bounded cache performance experiments
with paired stress measurements, correctness review, and a reviewable patch as the output.

## Style

Google Java Style. Contributors must sign a CLA.

## Guidelines

- Before suggesting dependency versions, Semgrep rulesets, or tool integrations, verify they exist (check Maven Central, registries, JDK release notes). Never recommend unverified tools. Use latest versions.
- Stay focused on the specific task requested. Don't produce unsolicited broad recommendation plans or premature "ready for engineer follow-up" conclusions.
- Lossy/best-effort semantics (read buffer drops, approximate frequency counts, eventual consistency) are intentional design trade-offs in the cache — not defects. Read `.claude/docs/design-decisions.md` before flagging these.
- Update `.claude/` when a change alters a durable rule, boundary, or rationale. Revise existing
  sections; follow `.claude/rules/code-comments.md`.
- Work that will span sessions gets a `LEDGER.md` work queue (itemized rows, status updated in place) alongside its scripts and data under `.local/experiments/<topic>/`. Being gitignored, that workspace survives the branch resets and rebases that remove checked-in artifacts — a narrative report on its own is not a handoff. It is ephemeral and machine-local, though: a checked-in file must not depend on `.local/` **contents** — never cite a specific workspace as where the evidence lives, or a `LEDGER.md` as the record, because the tree may be purged and other clones don't have it. Declaring a **destination** is fine and expected (`.local/audits/<model>/<skill>.md` is the audit convention). Distill durable conclusions into `.claude/` docs; workspace pointers belong in other `.local` files or in memory.
- When parallel workstreams report conflicting values for the same measurement, re-measure it directly rather than averaging them or trusting the more confident one. The conflict is usually an instrumentation artifact in one of them, and it otherwise ships as a finding.
- Don't blindly suggest committing after writing code. Actually run the tests and verify the output before proposing to commit.

## Architecture

Core: `caffeine/src/main/java/com/github/benmanes/caffeine/cache/`

| File | Purpose |
|------|---------|
| `BoundedLocalCache.java` | Main cache logic: eviction, expiration, compute |
| `FrequencySketch.java` | TinyLFU admission frequency counters |
| `WindowClimber.java` | Adaptive hill climber sizing the admission window |
| `BoundedBuffer.java` | Striped ring buffer for read recording |
| `MpscGrowableArrayQueue.java` | Write buffer (multi-producer single-consumer) |
| `TimerWheel.java` | Hierarchical timer wheel for variable expiration |
| `Node.java` | Node interface (implementations are code-generated) |

Tests: `caffeine/src/test/java/com/github/benmanes/caffeine/cache/`

## Code Generation

Node classes (PS, PW, PSAWMW, etc.) are **generated by javaPoet**. Never edit files
in `caffeine/build/generated/`. Edit the generators in `caffeine/src/javaPoet/java/` instead.

```bash
./gradlew :caffeine:generateNodes :caffeine:generateLocalCaches
```

Node naming: P=strong key, F=weak key, S=strong value, W=weak value, D=soft value.
Suffixes: A=access-time, W=write-time, R=refresh, MS=unweighted eviction, MW=weighted eviction.

## Project Structure

```
caffeine/    — Core cache library
guava/       — Guava compatibility adapter
jcache/      — JSR-107 JCache adapter
simulator/   — Cache policy simulator
```

## Reference Docs

For deep dives, read these on demand (not auto-loaded to save context):

- `.claude/docs/design-decisions.md` — why non-obvious choices are intentional, not bugs
- `.claude/docs/ruled-out.md` — adjudicated-and-rejected patterns, by module, with the reason each was rejected. It is not the only place rulings live; the module rule files carry adjudications it does not repeat
- `.claude/docs/synchronization.md` — lock hierarchy, access modes, callback invocation points
- `.claude/docs/testing.md` — CacheSpec parameterization, Truth subjects, test utilities
- `.claude/docs/research-foundations.md` — papers mapped to implementation (TinyLFU, BP-Wrapper, etc.)
- `.claude/docs/hill-climber.md` — the adaptive window climber: goal, adversarial cases, the probe machine, and the graveyard of alternatives
- `wiki/adaptive-window.html` — the climber's human-facing design document. **Don't read it**: it is a 470 KB rendered deliverable whose content is `hill-climber.md` §1-6 in prose. Edit it when the design changes; read `hill-climber.md` instead.
- `.claude/docs/finding-taxonomy.md` — standard severity/category schema for audit and review findings
- `.claude/docs/jsr107-conformance.md` — JSR-107 (JCache) conformance

When to read which doc:
- Concurrency or thread-safety work → `synchronization.md`
- Reviewing code → `design-decisions.md` first (prevents false positives); an audit reads it at the auditor's Phase 1.5, after recording its own findings
- Adjudicating an audit row, or arguing one past a standing ruling → `ruled-out.md` **and the rule file for the row's module**. Checking only `ruled-out.md` misses rulings that live solely in the rule files
- Writing or modifying tests → `testing.md`
- Understanding algorithm choices → `research-foundations.md`
- Touching the window climber / `determineAdjustment` → `hill-climber.md` (§1-4 first if new to the area)
- Investigating audit or retention costs → `hill-climber.md` §5–6 and `/audit-regret`'s
  targeted retention controls; reuse workload specs, not archived experiment runners
- Interpreting or writing audit findings → `finding-taxonomy.md`
- Consolidating audit reports → `audit-rounds.md` and `audit-output.md` §Consolidated queue
- Auditing JSR-107 conformance of the jcache adapter → `jsr107-conformance.md`

## Claude Code Extensions

- **Rules** (`.claude/rules/`): project conventions, loaded automatically when relevant. The module files also carry standing adjudications, so read the one for a module before raising a finding against it
- **Skills** (`/review-change`): multi-layer parallel code review with blind + design-aware + regression pattern matching
- **Skills** (`/audit-*`): snapshot-style deep analysis skills for concurrency, correctness, and performance, enumerated in the Audit Selection Guide below. Scope is repository-wide — the auditor agent's module map covers core, guava, jcache, simulator, and examples (`ruled-out.md` narrows the simulator's and the examples' scope); pass a module or path argument to focus a run
- **Skills** (`/audit-adversarial`): hostile full-codebase review with NO design context — finds bugs domain familiarity masks
- **Skills** (`/audit-temporal-walk`): heavyweight history-mining audit. Walks every commit oldest-first, forward-tracking issues across the project's full history. Catches bugs snapshot-style audits cannot — half-fixes invisible from current state, latent+trigger pairs across multi-commit interactions. Manually-invoked CLI tool (`walker.py` + `verify.py`), hours-long, rare-run (every several months or before a major release). Ships focused variants over the same engine — diff-shape lenses (deletion/sibling/intent), a fix-commit walk, a test-coverage-regression walk, and a forward-tracked invariant ledger — orchestrated as a battery by `run.py`; invoking the skill presents the variant menu so they aren't forgotten
- **Skills** (`/audit-jcache-conformance`): JSR-107 1.1.1 spec-conformance verification for the jcache adapter.
- **Skills** (`/audit-third-party-contracts`): external-library and JDK contract misuse across adapters, simulator, and examples — verifies call-site assumptions (error paths, duplicate/empty inputs, disposal) against upstream docs
- **Skills** (`/sim-*`): simulator workflow automation — `/sim-compare` for policy comparison charts, `/sim-analyze` for trace characterization
- **Eviction quality** (`/climber-gate`, `/audit-regret`, `/climber-minimize`, `/audit-adaptivity`): a
  workflow, not audits — see the section below
- **Auditor agent** (`.claude/agents/`): multi-pass — analysis → reflection → evaluator challenge → targeted re-audit

### Audit Selection Guide

| If concerned about... | Run |
|---|---|
| Thread-safety of a specific change | `/audit-jmm` |
| API contract ordering under concurrency | `/audit-linearizability` |
| Feature interactions (eviction+expiry+refresh) | `/audit-feature-interaction` |
| Exception paths leaving inconsistent state | `/audit-exception-safety` |
| Memory leaks after removal/eviction | `/audit-memory-retention` |
| Arithmetic edge cases (overflow, off-by-one) | `/audit-arithmetic` |
| Shutdown/close/GC races | `/audit-lifecycle` |
| Fresh-eyes adversarial sweep (no domain context) | `/audit-adversarial` |
| Full correctness proof of public methods | `/audit-correctness-proof` |
| Map/ConcurrentMap contract compliance | `/audit-map-contract` |
| Re-entrancy from user callbacks | `/audit-reentrancy` |
| Concurrent iteration and view consistency | `/audit-iteration` |
| Performance inefficiencies on hot paths | `/audit-performance` |
| Provably redundant work or state, including clarity-only cleanups | `/audit-redundancy` |
| Serialization proxy completeness and safety | `/audit-serialization` |
| Behavior under extreme/adversarial API inputs | `/audit-adversarial-input` |
| Progress and termination guarantees | `/audit-liveness` |
| Test coverage gaps and missing edge cases | `/audit-coverage-gaps` |
| Per-subsystem concurrency correctness | `/audit-subsystem-safety` |
| Build/CI configuration correctness | `/audit-build-ci` |
| Documented behavior vs. implementation drift | `/audit-contract-drift` |
| Divergences between sibling implementations | `/audit-sibling-divergence` |
| Drain-status / node-lifecycle / async-value state machines | `/audit-state-machine` |
| JSR-107 (JCache) spec conformance of the adapter | `/audit-jcache-conformance` |
| Third-party/JDK API contract misuse (adapters, simulator, examples) | `/audit-third-party-contracts` |

**Running a batch round** (order, quota, model coverage, and consolidation):
`.claude/docs/audit-rounds.md`. Read it when starting or triaging a round.

**Audit output**: reports go to `.local/audits/<model>/<skill-name>.md` — one directory per
producing model (`opus-5`, `gpt-5.6-sol`, …) plus `shared` for cross-model working documents like
the consolidated backlog. Gitignored but kept long-term; see `.claude/docs/audit-output.md`.

### Eviction Quality (a workflow, not audits)

These four are about how well correct code performs, not whether it is correct, so they are not
in the table above: their findings are failure classes and prices, not defects. Only
`/audit-adaptivity` reports bugs, and it is here because it shares the subsystem. The names are
historical — `/audit-regret` is not a correctness audit, and it is not climber-scoped either,
since its `structural` class routes to admission, the sketch, or the SLRU split.

| The question | Run | When |
|---|---|---|
| Did a change break a trap the machine already handles? | `/climber-gate` | after **any** `WindowClimber` or window-resize change |
| Is there a workload where correct code still loses hit rate? | `/audit-regret` | a round at a time, when looking for new families |
| Does each algorithmic step still earn its complexity? | `/climber-minimize` | before a release, or after several repairs land |
| Is there an implementation defect in the climber itself? | `/audit-adaptivity` | on a correctness doubt in the subsystem |

They compose: `/audit-regret` finds a family and promotes it to a `/climber-gate` row, the gate
holds it against every later change, and `/climber-minimize` asks periodically whether the rule
added to fix it is still paying for itself. Read `hill-climber.md` §3 and §5 before starting any of them.

**Review vs Audit**: `/review-change` is for pre-commit code review — reads design docs and filters known-intentional patterns. `/audit-*` skills independently search a specific lens; `/audit-redundancy` proves safe simplifications without requiring a defect or measured speedup. Use review for routine changes, audit when you need fresh-eyes analysis. `/audit-temporal-walk` is a third category (heavyweight, rare-run history-mining) — see its `SKILL.md` for invocation.

More agent context in ben-manes/caffeine

36 other files this repository gives its agents.