What do b.ResetTimer and b.StopTimer/b.StartTimer control in a Go benchmark?

## The timed region When the testing package runs a benchmark, it starts a clock and an allocation counter, calls your function, stops both, and divides by `b.N`. Everything the function does between those two points is charged to the operation — including a fixture you built at the top of the function. That is the whole problem these three methods exist to solve. ## b.ResetTimer `b.ResetTimer()` zeroes the elapsed benchmark time and the memory-allocation counters accumulated so far, and discards any custom metrics reported up to that point. It does not start or stop anything — if the clock was running it keeps running, it simply forgets what came before. The idiomatic placement is one line above the loop: ```go func BenchmarkEncodeChunk(b *testing.B) { src := bytes.NewReader(corpus) // 8 MiB of pipeline records chunk := readChunk(src) // fixture: must not be measured b.ResetTimer() for i := 0; i < b.N; i++ { encodeChunk(chunk) } } ``` Without that line, `ns/op` is `(decode the 8 MiB fixture + b.N encodes) / b.N`. For a small `b.N` the fixture dominates completely; as the harness raises `b.N` the fixture's share shrinks, which is why the reported figure moves around when you change the benchmark duration. A second reason the placement matters: the harness calls your **entire function** again for each attempt at a larger `b.N`, so expensive setup above the loop is paid on every attempt. Resetting the timer does not make that setup free in wall-clock terms — the benchmark still takes longer to run — it only keeps it out of the reported per-operation cost. ## b.StopTimer and b.StartTimer Some setup genuinely cannot be hoisted out of the loop: the operation consumes or mutates its input, so each iteration needs a fresh one. ```go func BenchmarkEncodeFresh(b *testing.B) { for i := 0; i < b.N; i++ { b.StopTimer() chunk := readChunk(bytes.NewReader(corpus)) b.StartTimer() encodeChunk(chunk) } } ``` `b.StopTimer()` pauses the clock and the allocation accounting; `b.StartTimer()` resumes both. Anything between them is excluded from `ns/op`, `B/op` and `allocs/op`. The same pair is used at the end of a benchmark for teardown you do not want measured — closing files, flushing a writer — by calling `b.StopTimer()` after the loop. ## The cost of pausing Stopping and starting is not free. Each call reads the clock and the runtime's allocation statistics, which takes on the order of hundreds of nanoseconds. If the operation under test costs 40 ns and you wrap every iteration in a stop/start pair, the measurement overhead is larger than the thing being measured, and the pause itself perturbs the CPU caches your operation was about to use. So the preference order is: 1. Hoist the fixture above the loop and call `b.ResetTimer()` once. 2. If the operation mutates its input, prepare a **slice of fixtures** before the loop and index it with `i % len(fixtures)`, or reset the input cheaply inside the timed region and accept the small constant. 3. Only reach for `b.StopTimer`/`b.StartTimer` when the per-iteration setup is genuinely expensive relative to the operation — expensive enough that leaving it in would swamp the result *and* excluding it costs proportionally little. ## Common mistakes * **Calling `b.ResetTimer()` inside the loop.** Every iteration then throws away the accumulated measurement, and only the last iteration's cost survives into `ns/op` — a wildly optimistic and unstable number. * **Forgetting `b.StartTimer()`** on some branch of the loop body, so most iterations are not timed at all. * **Assuming the timer methods change what code runs.** They change only the accounting. The setup still executes, still allocates, still takes wall-clock time; it is merely not charged to the operation. * **Believing setup above the loop is excluded automatically.** It is not. Nothing is excluded unless you exclude it. ## How the mistake shows up The honest way to catch mis-attributed setup is a benchmark that does not respond the way physics says it should: double the size of the record you encode and `ns/op` barely moves, or the figure changes noticeably between two different benchmark durations. Both are the signature of a fixed cost sitting inside the timed region and being divided by whatever `b.N` the harness happened to pick.