Why does `go test -race` switch coverage counters to -covermode=atomic?

## The three coverage modes `go test -covermode` takes one of three values, and it decides what the inserted counter does: - **`set`** (the default) — the counter is a boolean: did this block ever run? Cheapest, and enough for a percentage or a red/green HTML report. - **`count`** — the counter is an integer incremented on every execution. You get execution frequency, which `go tool cover -html` renders as shades of green: hotter blocks are darker. Useful for spotting a block that runs once versus a million times. - **`atomic`** — the same integer counter as `count`, but incremented with an atomic add rather than a plain `x++`. The reported percentage is identical in all three modes; only the counter's fidelity and cost differ. The mode is recorded in the first line of the profile (`mode: set`, `mode: count`, `mode: atomic`), which is how `go tool cover` knows how to interpret the last field on every block line. ## Why concurrency breaks the first two modes The instrumentation is source rewriting. A block that looked like ```go if err != nil { return err } ``` becomes, conceptually, a counter update followed by the original statements — and that counter is a package-scoped array element shared by the whole process. Nothing in Go makes a plain assignment or increment safe across goroutines. With `count`, two goroutines executing the same block concurrently perform read-modify-write on the same word. Increments are lost; the recorded frequency is wrong. That alone rarely matters, because you usually only care whether the block ran at all. The consequence that actually bites is the race detector. `-race` instruments memory accesses and reports any pair of conflicting unsynchronised accesses to the same address where at least one is a write. Coverage counters are exactly that: written from every goroutine, with no lock and no atomic. So combining `-race` with `set` or `count` would produce race reports pointing at counter variables in generated coverage code — noise that has nothing to do with the program you are testing, and, because a detected race makes `go test` exit non-zero, a red build. ## What atomic mode changes `atomic` mode replaces the increment with an atomic add on the counter. The race detector understands atomic operations as synchronising accesses, so no report is produced, and no increments are lost, so counts from concurrent tests are exact. The cost is real but small: an atomic add is more expensive than a plain increment, and it is executed at the top of every basic block, so hot loops in an instrumented, race-enabled binary get measurably slower. That is the reason `atomic` is not simply the default everywhere — for the common single-goroutine unit test, `set` is cheaper and answers the same question. ## The rule the toolchain applies `go test` chooses the mode for you: `set` by default, and `atomic` when `-race` is enabled. You can pass `-covermode` explicitly, and the useful case is asking for `count` (or `atomic`) on a run that has no `-race`, when you want frequency data. What you should not do is force `count` on a `-race` run to save a little time: you are re-introducing the unsynchronised counter the default was protecting you from. ## How this shows up in practice A CI job that runs `go test -race -coverprofile=cover.out ./...` will produce a profile whose header reads `mode: atomic` without anyone asking for it. Someone later writes a script that merges or post-processes profiles and assumes `mode: set`; the counters are now frequencies, not booleans, and a naive parser that treats the last field as a boolean still works (non-zero means covered) while a script that sums them gets something quite different. Reading the mode line rather than assuming it is the durable fix. The other practical note: because the mode is per-profile, you cannot meaningfully combine a `set` profile and a `count` profile. Pick one mode for the whole pipeline — in practice, whatever `-race` forces, because most CI suites run with the race detector on.