ben-manes/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
```

Run individual tests, not the full suite — it's slow and sharded across 40 CI workers.

### 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 — the build fails on any skipped test.

### Static Analysis

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

ErrorProne + NullAway run on every build. Fix warnings, don't suppress 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)
```

## 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.
- When fixing a bug or making a design change, update or create `.claude/` files (docs, rules, skills, agents) to keep them in sync with the change.
- 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 |
| `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 `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/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/finding-taxonomy.md` — standard severity/category schema for audit and review findings

When to read which doc:
- Concurrency or thread-safety work → `synchronization.md`
- Auditing or reviewing code → `design-decisions.md` first (prevents false positives)
- Writing or modifying tests → `testing.md`
- Understanding algorithm choices → `research-foundations.md`
- Interpreting or writing audit findings → `finding-taxonomy.md`

## Claude Code Extensions

- **Rules** (`.claude/rules/`): project conventions, loaded automatically when relevant
- **Skills** (`/review-change`): multi-layer parallel code review with blind + design-aware + regression pattern matching
- **Skills** (`/audit-*`): 20 snapshot-style deep analysis skills for concurrency, correctness, and performance
- **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)
- **Skills** (`/sim-*`): simulator workflow automation — `/sim-compare` for policy comparison charts, `/sim-analyze` for trace characterization
- **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` |
| 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` |

**Review vs Audit**: `/review-change` is for pre-commit code review — reads design docs and filters known-intentional patterns. `/audit-*` skills are for correctness doubts — independent, no design context filtering. 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.