Why can GOMAXPROCS differ between your laptop and a CI container, and how do you test both?

## What GOMAXPROCS actually bounds The Go runtime multiplexes goroutines onto OS threads through a fixed number of logical processors, conventionally called Ps. **GOMAXPROCS is the number of Ps**, and therefore the maximum number of goroutines executing Go code at the same instant. It is not a cap on how many goroutines you may create, nor on how many OS threads the process may have — a goroutine that blocks in a syscall hands its P to another thread, so the thread count can comfortably exceed GOMAXPROCS. You read and set it at run time with `runtime.GOMAXPROCS`, or from the environment with the `GOMAXPROCS` variable. The default is derived from the CPUs the process may use. ## Why CI's value differs from yours A developer machine reports its physical core count and nothing constrains the process, so GOMAXPROCS is typically 8, 10 or 16. A CI job usually runs inside a container with a CPU bandwidth limit — often one or two CPUs' worth on a much larger host. Historically the Go runtime looked only at the number of logical CPUs the OS reported, so a container limited to one CPU on a 64-core machine still started with GOMAXPROCS 64: the runtime believed it had massive parallelism while the kernel throttled it, producing long scheduling delays and erratic latency. Since Go 1.25 the default on Linux also honours the cgroup CPU bandwidth limit, and the runtime re-reads that limit periodically so a changed quota is picked up. The behaviour can be turned off with `GODEBUG=containermaxprocs=0` (and the periodic update with `GODEBUG=updatemaxprocs=0`), and `runtime.SetDefaultGOMAXPROCS` recomputes the default on demand. Either way, the conclusion for a test suite is the same: **the parallelism your tests run at is a property of the machine, not of your code**, and it is different in CI. ## Why that turns into a flaky test Interleaving changes at both ends of the range. - **At GOMAXPROCS=1** only one goroutine runs Go code at a time. Goroutines still interleave — at channel operations, mutex contention, allocation, function calls and syscalls — but a goroutine that busy-waits on a variable without ever reaching a scheduling point can hold the only processor for a long time. Tests that assumed "the worker has surely started by now" fail here more often, because the main test goroutine may run straight through to its assertion before the workers get a turn. - **At GOMAXPROCS=8** there is real simultaneity, so two goroutines genuinely touch the same memory at the same moment. Races that are theoretically present but never observed at one processor start being observed, and orderings that never occurred in a serialised run become common. So the same test can be red only in CI (low parallelism, loaded box) or red only locally (high parallelism), and neither result generalises. ## Exercising both from one command `go test` has a flag for exactly this: `-cpu` takes a comma-separated list and runs **each test once per value**, setting GOMAXPROCS to that value for the run. ``` go test -cpu=1,2,8 -count=20 -run TestWorkerPoolResults ./internal/scheduler ``` That is twenty runs at each of three parallelism levels. Alternatively, pin the value from the environment when you want a long repetition loop at one setting: `GOMAXPROCS=1 go test -count=200 -run TestWorkerPoolResults ./internal/scheduler`. Two neighbouring knobs are easy to confuse with this one: - `-parallel` controls how many tests marked parallel run concurrently; it defaults to the GOMAXPROCS value but is a different thing — a test-harness concurrency limit, not a runtime one. - `-cpu` does not pin the process to particular cores; it sets a runtime parameter, and the OS still schedules the threads wherever it likes. ## The judgment part Matching CI's GOMAXPROCS locally is the cheapest way to close the "works on my machine" gap on a concurrency test, and it costs nothing to add `-cpu=1,4` to the flaky test's reproduction command. It is not a fix, though: a test whose result depends on how many processors are available is asserting something the language never promised. The value of running at several parallelism levels is diagnostic — it tells you that the test, not the machine, is making an assumption — and the repair is to synchronise explicitly so the answer is the same at one processor and at sixteen.