The b.N Loop

## The shape A Go benchmark lives in a `_test.go` file next to the code and looks like this: ```go func BenchmarkEncodeRecord(b *testing.B) { rec := Record{ID: 42, Body: []byte("payload")} for i := 0; i < b.N; i++ { encodeRecord(rec) } } ``` The rules are mechanical: the name must start with `Benchmark`, the single parameter is `*testing.B`, and the operation you want to measure must run exactly `b.N` times. ## What b.N is `b.N` is a plain `int` field on `testing.B` that the harness fills in before it calls your function. It is the number of repetitions of the operation for this measurement attempt. It is **not** a size, **not** a concurrency level, and **not** something you assign. ## How the harness picks it The testing package cannot know in advance whether one iteration of your code takes 3 nanoseconds or 3 milliseconds, so it discovers that by running the benchmark: 1. It calls the function with `b.N = 1` and times it. 2. If the run was shorter than the benchmark duration (`-benchtime`, default `1s`), it estimates how many iterations would fill that duration, grows `b.N` towards that estimate (rounded up to a readable number, and never by more than a large fixed factor in one step), and calls the function **again from the top**. 3. It repeats until a run lasts at least `-benchtime`. Only the final run produces the reported numbers. Everything from earlier attempts is discarded. The key thing juniors miss is step 2's phrase *from the top*: the harness re-invokes the **entire function**, not just the loop. Any setup you wrote above the loop runs once per attempt, and — crucially — it runs inside the timed region of the final, reported attempt unless you tell the harness otherwise. ## Reading the output ```text $ go test -bench=EncodeRecord goos: linux goarch: amd64 BenchmarkEncodeRecord-8 2874316 412.6 ns/op PASS ``` * `-8` is the value of `GOMAXPROCS` the benchmark ran with, not a CPU id. * `2874316` is the final `b.N`. * `412.6 ns/op` is the elapsed time of that final run divided by `b.N`. Because `ns/op` is always *elapsed divided by b.N*, the number is only meaningful if the loop really performed `b.N` units of the same work. A body that ignores `b.N` and does a fixed amount of work reports a figure that shrinks as the harness raises `b.N` — pure nonsense. ## Benchmarks do not run by default `go test` runs `Test` functions and skips benchmarks. They execute only when the `-bench` flag's regexp matches: ```text go test -bench=. # all benchmarks in the package (tests run too) go test -bench=Encode -run=^$ # only matching benchmarks, no tests ``` `-run=^$` is the idiomatic way to say "no test name matches", which keeps the test suite from adding noise and time to a benchmarking run. ## The classic misuse of b.N ```go data := make([]byte, b.N) // wrong: input size must not depend on b.N ``` Sizing the input by `b.N` means each iteration does more work as the harness increases `b.N`, so the harness's estimate never converges on a stable per-operation cost and `ns/op` describes nothing. Input size is a constant of the benchmark (or a dimension you vary with sub-benchmarks); `b.N` is only the repetition count. Similarly, do not try to "help" by assigning `b.N` yourself or by breaking out of the loop early: the reported figure divides by the `b.N` the harness chose, so a loop that runs fewer iterations reports an artificially cheap operation. ## Failing inside a benchmark `testing.B` embeds the same failure API as `testing.T`: `b.Fatal`, `b.Fatalf`, `b.Error`, `b.Skip`, plus `b.Helper` and `b.Cleanup`. Use them for setup that can fail; a benchmark that panics or fails is reported as a failure rather than producing a number. ## Determinism when you need it If you want a fixed iteration count rather than a fixed duration — for debugging the benchmark itself, or when a single operation is very slow — pass an `x`-suffixed benchmark duration: `go test -bench=Encode -benchtime=100x` sets `b.N` to exactly 100.