The Anatomy of a Goroutine

You have written go f() a thousand times. This course is about what happens next — and the best way to understand it is to build the machinery yourself, in ordinary Go, one piece at a time.

Start with the object itself. A goroutine is not a thread. It is a small heap structure the runtime calls a g, defined in runtime/runtime2.go:

// Heavily abridged from runtime/runtime2.go.
type g struct {
	stack       stack   // [stack.lo, stack.hi) — the goroutine's stack bounds
	stackguard0 uintptr // stack-growth (and preemption!) check value
	sched       gobuf   // saved SP, PC, etc. — the "context" in context switch
	atomicstatus atomic.Uint32 // _Grunnable, _Grunning, _Gwaiting, ...
	goid        uint64
	waitreason  waitReason // why it's parked ("chan receive", "sleep", ...)
}

Three things make a g cheap where an OS thread is expensive:

• Tiny, growable stacks. A goroutine starts with a ~2 KB stack (since Go 1.19 the runtime may pick a larger start size based on the historical average). Every function prologue compares the stack pointer against stackguard0; on overflow, morestack allocates a bigger stack and copies the old one over — contiguous stacks. An OS thread reserves megabytes of virtual address space up front and can never shrink it.
• Userspace context switches. Switching goroutines means saving a handful of registers into g.sched (a gobuf: SP, PC, and a pointer to the g) and loading another goroutine's. No syscall, no kernel scheduler, roughly the cost of a function call. The assembly routines are gogo and mcall.
• M:N scheduling. Millions of Gs are multiplexed onto a few OS threads.

The runtime's scheduler is described by three letters you'll see constantly in runtime/proc.go:

• G — a goroutine: stack + saved registers + status.
• M — a machine: an actual OS thread that executes Gs.
• P — a processor: a scheduling context holding a local run queue of runnable Gs (plus allocation caches). There are exactly GOMAXPROCS Ps. An M must hold a P to run Go code; an M without a P is parked or sitting in a syscall.

go f() compiles to a call to runtime.newproc, which allocates (or recycles) a g, seeds its gobuf so it will "return into" f, marks it _Grunnable, and drops it on the current P's run queue. That's all — the statement returns immediately, and f runs whenever a P picks it up. This is also why main returning kills the program without waiting for anyone: nothing counts outstanding goroutines. The runtime deliberately has no "join"; if you want one, you build it from synchronization primitives — which is exactly your first challenge.

func Spawn(f func())  // start f concurrently; return immediately
func WaitAll()        // block until every spawned function has returned