Add test coverage, update README

Author: Thomas Stromberg

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+
+      - name: Run tests
+        run: make test
+
+      - name: Generate coverage
+        run: make coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.out
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+
+      - name: Run lint
+        run: make lint
+
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+
+      - name: Run competitive benchmark
+        run: make competitive-benchmark

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test lint bench benchmark competitive-benchmark clean tag release update
+.PHONY: test lint bench benchmark competitive-benchmark coverage clean tag release update
 
 # Tag all modules in the repository with a version
 # Usage: make tag VERSION=v1.2.3
@@ -71,6 +71,9 @@ benchmark:
 competitive-benchmark:
 	go run ./benchmarks/runner.go -competitive
 
+coverage:
+	go test -coverprofile=coverage.out -covermode=atomic ./...
+
 clean:
 	go clean -testcache
 

README.md

@@ -1,8 +1,19 @@
+<p align="center">
+  <img src="media/logo-small.png" alt="multicache logo" width="200">
+</p>
+
 # multicache
 
-multicache is an absurdly fast multi-threaded multi-tiered in-memory cache library for Go -- it offers higher performance than any other option ever created for the language.
+[![CI](https://github.com/codeGROOVE-dev/multicache/actions/workflows/ci.yml/badge.svg)](https://github.com/codeGROOVE-dev/multicache/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/codeGROOVE-dev/multicache)](https://goreportcard.com/report/github.com/codeGROOVE-dev/multicache)
+[![Go Reference](https://pkg.go.dev/badge/github.com/codeGROOVE-dev/multicache.svg)](https://pkg.go.dev/github.com/codeGROOVE-dev/multicache)
+[![codecov](https://codecov.io/gh/codeGROOVE-dev/multicache/graph/badge.svg)](https://codecov.io/gh/codeGROOVE-dev/multicache)
+[![Release](https://img.shields.io/github/v/release/codeGROOVE-dev/multicache)](https://github.com/codeGROOVE-dev/multicache/releases)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+multicache is the most well-rounded cache implementation for Go today.
 
-It offers optional persistence with compression, and has been specifically optimized for Cloud Compute environments where the process is periodically restarted, such as Kubernetes or Google Cloud Run. 
+Designed for real-world applications in unstable environments, it has a higher average hit rate, higher throughput, and lower latency for production workloads than any other cache. To deal with process eviction in environments like Kubernetes, Cloud Run, or Borg, it also offers an optional persistence tier.
 
 ## Install
 
@@ -24,8 +35,8 @@ With persistence:
 store, _ := localfs.New[string, User]("myapp", "")
 cache, _ := multicache.NewTiered(store)
 
-cache.Set(ctx, "user:123", user)           // sync write
-cache.SetAsync(ctx, "user:456", user)      // async write
+_ = cache.Set(ctx, "user:123", user)       // sync write
+_ = cache.SetAsync(ctx, "user:456", user)  // async write
 ```
 
 GetSet deduplicates concurrent loads to prevent thundering herd situations:
@@ -62,14 +73,14 @@ multicache has been exhaustively tested for performance using [gocachemark](http
 
 Where multicache wins:
 
-- **Throughput**: 954M int gets/sec at 16 threads (2.2X faster than otter). 140M string sets/sec (9X faster than otter).
-- **Hit rate**: Wins 7 of 9 workloads. Highest average across all datasets (+2.9% vs otter, +0.9% vs sieve).
-- **Latency**: 8ns int gets, 10ns string gets, zero allocations (4X lower latency than otter)
+- **Throughput**: 551M int gets/sec avg (2.4X faster than otter). 89M string sets/sec avg (27X faster than otter).
+- **Hit rate**: Wins 6 of 9 workloads. Highest average across all datasets (+2.7% vs otter, +0.9% vs sieve).
+- **Latency**: 8ns int gets, 10ns string gets, zero allocations (3.5X lower latency than otter)
 
 Where others win:
 
-- **Memory**: freelru and otter use less memory per entry (73 bytes/item overhead vs 15 for otter)
-- **Specific workloads**: clock +0.07% on ibm-docker, theine +0.34% on zipf
+- **Memory**: freelru and otter use less memory per entry (73 bytes/item overhead vs 14 for otter)
+- **Specific workloads**: sieve +0.5% on thesios-block, clock +0.1% on ibm-docker, theine +0.6% on zipf
 
 Much of the credit for high throughput goes to [puzpuzpuz/xsync](https://github.com/puzpuzpuz/xsync) and its lock-free data structures.
 
@@ -81,11 +92,11 @@ multicache uses [S3-FIFO](https://s3fifo.com/), which features three queues: sma
 
 multicache has been hyper-tuned for high performance, and deviates from the original paper in a handful of ways:
 
-- **Tuned small queue** - 90% vs paper's 10%, tuned via binary search to maximize average hit rate across 9 production traces
+- **Tuned small queue** - 13.7% vs paper's 10%, tuned via binary search to maximize average hit rate across 9 production traces
 - **Full ghost frequency restoration** - returning keys restore 100% of their previous access count
-- **Reduced frequency cap** - max freq=2 vs paper's 3, tuned via binary search for best average hit rate
-- **Hot item demotion** - items accessed at least once (peakFreq≥1) get demoted to small queue instead of evicted
-- **Extended ghost capacity** - 8x cache size for ghost tracking, tuned via binary search
+- **Increased frequency cap** - max freq=5 vs paper's 3, tuned via binary search for best average hit rate
+- **Death row** - hot items (high peakFreq) get a second chance before eviction
+- **Extended ghost capacity** - 1.22x cache size for ghost tracking, tuned via binary search
 - **Ghost frequency ring buffer** - fixed-size 256-entry ring replaces map allocations
 
 ## License