[floatdrop]

What

A new package, stats. stats.Wrap puts a counter in front of any evict.Cache and is one itself:

cache := stats.Wrap(tinylfu.New[string, int](10_000))
s := cache.Stats() // Hits, Misses, Evictions, Len, Cap
s.HitRatio()
cache.Stats().Sub(s) // the counts of an interval

• Get counts a hit or a miss.
• Set counts an eviction when the entry it reports is not the one the key had, or when a cache without capacity hands the new entry back. A replacement is not an eviction.
• Peek, Delete, Clear and All count nothing; Clear does not reset the counts.

The README's "no statistics" is gone, and it has a short Statistics section.

Why a wrapper

Counting inside each policy would be cheaper: the caches already write to a line in the right place (the reader slots, the shard under its lock). A wrapper touches none of the policy code and is easy to drop if it turns out not to be worth it.

Cost (Apple M3 Max)

tinylfu Get, all hits	1 CPU	8 CPUs
direct	15.7 ns	2.17 ns/op
through evict.Cache	16.0 ns	2.22 ns/op
through stats.Wrap	17.4 ns	2.37 ns/op

• 10–14% over a few runs (medians of 7 above).
• Goroutines count in stripes of 128 bytes, 16 per CPU, picked by stack address like the reader slots of cslab. That is 2–4 KiB per CPU for every wrapped cache, whatever its capacity.
• A key converted from a []byte on the spot allocates through the wrapper (1 alloc against 0), because the compiler cannot see through the interface.
• Stats() reads every stripe and calls Len: 0.17 µs on 8 CPUs for an idle tinylfu.

Checked

• The conformance suite and NoAllocs from internal/cachetest, on wrapped lru and s3fifo.
• Exact counts under 16 goroutines: hits + misses = requests, and evictions = entries added − entries left.
• Evictions on all five policies, including -0 replacing +0, NaN keys and zero capacity.
• A test that goroutines running at the same time count in different stripes. It fails if every goroutine counts in one stripe; that change alone made Get 20 times slower on 8 CPUs, and every other test still passed.
• internal/inlinecheck has three new probes: direct use, and use through a generic type of another package that instantiates nothing. Get and Set make no call other than the one through the interface. The probes fail if the counters are switched to atomic.Uint64.
• An independent review agent checked the counting against a model on all five policies (capacities 0 to 600, more shards than entries, any keys mixing 0, -0.0, "0" and nil) and found nothing wrong.
• golangci-lint clean; go test -race ./... passes; GOOS=linux GOARCH=386 go vet ./... clean (32-bit not run, only vetted).

Note

perf-review also changes internal/inlinecheck/inline_test.go; whichever lands second resolves a small conflict in its patterns.

🤖 Generated with Claude Code