The scheduler, GOMAXPROCS and the runtime

A goroutine is cheap because the Go runtime schedules it, not the operating system. The runtime keeps a pool of OS threads, runs goroutines on them a few at a time, and moves work away from a thread that blocks. The previous lesson started goroutines; this one looks at what runs them.

G, M and P

The three letters are the runtime's own names. A G is a goroutine: its stack, its instruction pointer and its state. An M is a machine, an OS thread the runtime created and can block in a system call. A P is a processor, the right to run Go code, and there are GOMAXPROCS of them: a G runs on an M only while holding a P. A G that blocks in a system call gives its P back, another M picks the P up, and the program keeps running Go code while the thread waits.

package main import ( "fmt" "runtime" ) func main() { fmt.Println("NumCPU:", runtime.NumCPU()) fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0)) fmt.Println("NumGoroutine:", runtime.NumGoroutine()) fmt.Println("version:", runtime.Version()) }

go build -o app main.go && ./app

NumCPU: 4
GOMAXPROCS: 4
NumGoroutine: 1
version: go1.26.10

The container sees four CPUs, so the runtime starts four Ps, and a program at rest has one goroutine: the one running main. NumGoroutine also counts the runtime's own goroutines when they exist, which is why a busy server reports a number a few above its requests. GOMAXPROCS is a limit on parallelism, not on concurrency: a thousand goroutines can be in flight on four Ps.

A hundred thousand goroutines

A goroutine starts with a small stack and grows it by copying, so the cost of starting one is closer to a function call than to a thread. The program below starts a hundred thousand of them, each adding one to an atomic counter, and prints the count and the time. The counter is sync/atomic because a plain int would race; the next lessons take the two apart.

package main import ( "fmt" "sync" "sync/atomic" "time" ) func main() { var counter atomic.Int64 var wg sync.WaitGroup start := time.Now() for i := 0; i < 100_000; i++ { wg.Add(1) go func() { defer wg.Done() counter.Add(1) }() } wg.Wait() fmt.Println("goroutines:", counter.Load()) fmt.Println("elapsed:", time.Since(start).Round(time.Millisecond)) }

go build -o app main.go && ./app

goroutines: 100000
elapsed: 51ms

Fifty-one milliseconds is this machine and this run; a slower box reports more, and a second run reports a different number. The count is the part that matters: every goroutine ran and the atomic counter lost no update. A hundred thousand threads would have exhausted the memory of the container long before the first wave finished.

A blocked goroutine blocks only itself

The fast goroutine below prints before the slow one even wakes up, although both were started in the same instant and the slow one sleeps for twenty milliseconds. The runtime does not run the sleep on a thread: it parks the goroutine and uses the P for other work, which is why a sleeping goroutine costs nothing while it sleeps.

package main import ( "fmt" "sync" "time" ) func main() { var wg sync.WaitGroup wg.Add(2) go func() { defer wg.Done() time.Sleep(20 * time.Millisecond) fmt.Println("slow goroutine done") }() go func() { defer wg.Done() fmt.Println("fast goroutine done") }() wg.Wait() fmt.Println("both done") }

go build -o app main.go && ./app

fast goroutine done
slow goroutine done
both done

Wait is what turns "should be done by now" into "is done": the last line can only come from the goroutine that owns the counter. The sleep itself is a duration, not a signal, which is why the earlier lesson called it a guess; here it is only a way to keep one worker busy.

GOMAXPROCS

GOMAXPROCS can be read with an argument of zero and changed at run time. Setting it to one is the standard way to check that a program does not depend on real parallelism: the goroutines still interleave at the points where they block or yield, but two pieces of Go code never run at the same instant. The environment variable of the same name sets the initial value.

package main import ( "fmt" "runtime" ) func main() { before := runtime.GOMAXPROCS(0) runtime.GOMAXPROCS(1) fmt.Println("before:", before) fmt.Println("now:", runtime.GOMAXPROCS(0)) runtime.GOMAXPROCS(before) fmt.Println("restored:", runtime.GOMAXPROCS(0)) }

go build -o app main.go && ./app

before: 4
now: 1
restored: 4

In a container the runtime reads the CPU limit it is given, so the four here are four CPUs of this machine rather than of the host. A program that wants a goroutine per request does not change GOMAXPROCS; a program that pins itself to a few cores, or a benchmark that compares one core with many, does.

Exercises

  1. Run the hundred-thousand-goroutine program with GOMAXPROCS=1 and again with GOMAXPROCS=4. Which number changed, and by how much?
  2. Add a time.Sleep of a millisecond inside the counter goroutine and run the program again. What happens to the elapsed time, and why?
  3. Print runtime.NumGoroutine() before and after a thousand goroutines finish. What does the difference tell you about the runtime's own goroutines?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is a G in the Go runtime?

    Answer

    A goroutine

    G is the goroutine, with its stack and its state.

  2. What is an M?

    Answer

    An OS thread that runs Go code

    The runtime creates threads and blocks them in system calls.

  3. What is a P?

    Answer

    The right to run Go code, one per GOMAXPROCS

    A goroutine runs on a thread only while holding a P.

  4. What does runtime.NumCPU report in this container?

    Answer

    4

    The runtime sees the CPUs the container is given.

  5. How does a sleeping goroutine affect its P?

    Answer

    It gives the P up and the runtime runs other work

    That is why a sleeping goroutine is nearly free.

  6. How many goroutines does a program at rest report?

    Answer

    One, the one running main

    The runtime goroutines appear only when they exist.

  7. What does runtime.GOMAXPROCS(0) do?

    Answer

    Returns the current value without changing it

    Zero is the "read only" argument.

  8. What does GOMAXPROCS limit?

    Answer

    The Go code that runs at the same instant

    It caps parallelism, not concurrency.

  9. Why is a hundred thousand goroutines cheaper than a hundred thousand threads?

    Answer

    The runtime multiplexes them onto a few threads

    A small growing stack and a user-space scheduler are the reason.

  10. Which environment variable sets the initial GOMAXPROCS?

    Answer

    GOMAXPROCS

    The variable and the function share the name.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev