How does a goroutine's stack grow when its initial ~2 KB is not enough?

## The problem growable stacks solve Every function call needs space for its local variables, its spilled arguments and its return address. That space lives on the stack of whatever is executing the call. A native OS thread solves this by reserving a large fixed range up front — often 1 MB or 8 MB of virtual address space — and simply never letting the program exceed it. That is fine when you have dozens of threads, and hopeless when you want hundreds of thousands of concurrent tasks: you would either reserve far more address space than you can afford, or pick a small fixed size and crash on any moderately deep call chain. Go takes the other route. A goroutine starts with a **tiny stack — about 2 KB** — and the runtime **grows it on demand**, so the depth a goroutine can reach is not a decision anybody makes at creation time. ## The check in every function prologue The Go compiler emits a preamble at the top of nearly every function it compiles. Conceptually it is: *is the stack pointer, minus the number of bytes this frame needs, still above the goroutine's stack guard?* The guard is a field on the goroutine's runtime descriptor (`stackguard0`) that sits a small distance above the bottom of the currently allocated stack. If the frame fits, execution falls straight through into the function body and the cost is a compare and a not-taken branch. If it does not fit, the prologue jumps to `runtime.morestack`. A few functions opt out of the check with the `//go:nosplit` directive — mostly deep runtime internals that cannot themselves trigger a stack growth. Those functions must fit inside a small reserved margin below the guard, and the linker reports an error if the chain of nosplit calls would overflow it. ## What growth actually does `runtime.morestack` calls `runtime.newstack`, which: 1. Allocates a **new stack of double the current size** (2 KB becomes 4 KB, then 8 KB, and so on). 2. Calls `runtime.copystack`, which copies the entire used portion of the old stack into the new one — byte for byte, at a different address. 3. **Adjusts every pointer** that referred to the old stack. The compiler records, for each frame, exactly which words are pointers, so the runtime can walk the frames and add the address delta to each such word, including pointers held in deferred-call records. 4. Frees the old stack back to the runtime's stack allocator. 5. Returns to the prologue, which re-runs the check — this time it passes — and the function proceeds. From your code's point of view nothing happened except that the call took longer. Nothing is copied that the program can observe, because the runtime has fixed up all the internal references. ## Why one contiguous stack instead of segments An earlier design chained a fresh segment onto the old one when space ran out, which avoided copying. It had a famous pathology usually called the **hot split**: if the boundary between two segments fell inside a hot loop, every iteration would allocate a segment on the way in and free it on the way out, turning a cheap call into an allocation. Copying to a single larger contiguous stack removes that cliff. Because each growth **doubles** the size, a goroutine that ends up N bytes deep pays O(N) total copying across its life — amortised constant per call — and never oscillates at a boundary. ## What forces growth Deep call chains are the obvious cause, and recursion is the classic one. Large frames matter just as much: a function that declares a `[64 * 1024]byte` local needs 64 KB of stack all at once, so calling it from a fresh goroutine forces several doublings immediately. This is one reason big buffers are usually heap-allocated or pooled rather than declared as huge local arrays. ## The ceiling Growth is not unlimited. The default maximum size for a single goroutine's stack is **1 GB on 64-bit platforms** (250 MB on 32-bit), adjustable with `runtime/debug.SetMaxStack`. Exceeding it is not a recoverable panic: the runtime prints `runtime: goroutine stack exceeds 1000000000-byte limit`, then `fatal error: stack overflow`, and the whole process dies. In practice, code that reaches the limit is code with unbounded recursion, and the fix belongs in the code, not in the limit.