Go scheduler simulator

Each card is a P (processor) with the goroutine it is running, its runnext slot and its local run queue. Below are the global run queue and any goroutines blocked in system calls, each holding its own thread. The timeline shows which goroutine ran on each P and when.

• Fan-out: main starts 48 goroutines on P0. Each new one goes into runnext and pushes the previous one into the local queue; the idle Ps wake up and steal half of it at a time. Switch work stealing off to see P0 do everything alone.
• Blocking syscalls: watch the thread count climb past GOMAXPROCS as sysmon hands Ps away from threads stuck in the kernel.
• Tight loop on one P: with Go 1.14+ the loop is preempted after 10 ms and the waiting goroutines run; set preemption to before 1.14 and they wait for the whole loop.
• Ping-pong: the pair hand control to each other through runnext and run back to back on one P, until they have used a 10 ms slice between them and are preempted together.

The Go scheduler is the part of the Go runtime that decides which goroutine runs on which operating-system thread. A Go program may have hundreds of thousands of goroutines, but the operating system only sees a few threads; the runtime multiplexes one onto the other in user space, which makes starting a goroutine and switching between goroutines far cheaper than doing the same with threads.

Because blocking operations such as channel receives, locks and network reads park only the goroutine, the thread underneath moves on to other work. The scheduler's job is to keep every processor busy without much locking, to treat goroutines fairly, and to cope with the cases it cannot see into, such as system calls that block in the kernel.

• G, a goroutine: a function to run, its stack (which starts small and grows as needed) and its saved registers.
• M, a machine: an OS thread. Ms are created as needed, up to a default limit of 10,000 (debug.SetMaxThreads).
• P, a processor: the right to run Go code, with a run queue and per-processor caches. There are exactly GOMAXPROCS Ps.

An M must hold a P to run a G. The P is what makes the design scale: before it was added, all threads took goroutines from one global queue under one lock. With a P per CPU, the common path, taking the next goroutine from your own queue, needs no lock at all.

A runnable goroutine sits in one of three places:

• runnext, a single slot per P. go f() puts the new goroutine there, and so does waking a goroutine blocked on a channel. Whatever was in runnext moves to the back of the local queue. Running the woken goroutine next on the same P keeps shared data in cache, and a goroutine taken from runnext inherits the current time slice, so a pair that keeps waking each other cannot starve everyone else.
• The local run queue, a ring of 256 goroutines owned by the P. When it is full, half of it and the new goroutine move to the global queue.
• The global run queue, shared and protected by a lock. Preempted goroutines go here, as do goroutines whose system call returned when no P was free.

When a P needs work it looks, in order: at the global queue first on every 61st scheduling round, so that goroutines there are not starved by two that keep respawning each other; then runnext; then its local queue; then the global queue, taking a batch of up to half a local queue (the queue's length divided by GOMAXPROCS, plus one); then the network poller; and finally other Ps, to steal.

A P with nothing to run visits the other Ps in a random order and takes half of the first non-empty local queue it finds, rounding up. It makes four passes; on the last one it may also take a victim's runnext goroutine. Stealing half moves enough work to keep the thief busy for a while without leaving the victim empty, and the random order spreads thieves across victims. The fan-out workload, 48 one-millisecond goroutines started by one goroutine:

Network I/O in Go does not block threads: sockets are non-blocking and a parked goroutine is woken by the runtime's network poller (epoll, kqueue or IOCP). File reads and other system calls do block the thread, and the runtime cannot know for how long. The goroutine keeps its thread for the duration, and the thread keeps a loose hold on its P. The sysmon thread checks regularly; if a P has been stuck in a system call for more than one of its ticks (at least 20 µs) and there is work it could do, sysmon takes the P and gives it to another thread, waking an idle one or creating a new one. When the call returns, the goroutine tries to get its old P back, then any idle P, and failing that it goes to the global queue and its thread goes to sleep.

sysmon also watches each P's scheduling counter. If the same goroutine, or the same chain of runnext goroutines, has been running for 10 ms, sysmon asks it to stop, and it goes to the back of the global queue. Until Go 1.14 the request was a flag checked in function prologues, so a loop that made no function calls could not be stopped, which could hold up the garbage collector and every goroutine waiting on that P. Go 1.14 added asynchronous preemption: the runtime sends the thread a signal (SIGURG on Unix) and stops the goroutine at almost any instruction. The tight-loop workload, a 40 ms loop without calls and three short goroutines on one P:

The model steps in 10 µs ticks and follows the rules in runtime/proc.go: runqput and its spill to the global queue, the order of checks in findRunnable including the every-61st global check and the batch size, runqsteal taking half with four passes in random order, runnext inheriting the time slice, sysmon's 10 ms preemption and its syscall retake and handoff. It leaves out garbage collection, timers and the network poller, lets every idle P look for work on every tick (the runtime limits how many threads spin), and runs sysmon every 20 µs (the real one backs off to 10 ms when the program is idle). Context switches and steals cost no time.

It is checked headless: in every workload with 1 to 8 Ps, with and without stealing and preemption, every goroutine runs to completion, the CPU time used equals the work requested, and no goroutine is ever in two places at once.

Go was released in 2009 with a scheduler that used a single global run queue protected by a lock. In 2012 Dmitry Vyukov wrote the "Scalable Go Scheduler Design Doc", which introduced the P, per-P run queues and work stealing; his "runtime: improved scheduler" change landed in March 2013 and shipped in Go 1.1. Preemption at function calls followed in Go 1.2, asynchronous preemption by signal in Go 1.14 (February 2020), and Go 1.25 (August 2025) made the default GOMAXPROCS follow a container's CPU limit on Linux.