Goroutine Stack Management

How Go manages goroutine stacks — initial 2KB allocation, contiguous stack growth, stack copying, shrinking, and performance implications for high-concurrency applications.

Overview

Go's goroutine stack management is a cornerstone of its lightweight concurrency model. Unlike traditional threads which consume 1-2 MB of memory, goroutines start with just 2 KB of stack space and grow dynamically as needed. Understanding how stacks evolve, grow, and are reclaimed is essential for writing high-performance concurrent applications.

This deep dive covers the evolution from segmented stacks to contiguous stacks, the mechanics of stack growth and shrinking, performance implications, and practical optimization strategies.

Evolution: From Segmented to Contiguous Stacks

The Segmented Stack Era (Go 1.0 - 1.2)

Go's original stack implementation used segmented stacks (also called linked stacks). When a goroutine needed more stack space, the runtime would allocate a new "segment" and link it to the previous one via a pointer.

Segmented Stack Structure:

┌─────────────────┐
│   Segment 1     │
│   (8 KB)        │ ◄──────┐
│  [frame 1]      │        │
│  [frame 2]      │        │
│  stack_pointer ─────────┐│
└─────────────────┘       ││
                          ││
┌─────────────────┐       ││
│   Segment 2     │ ◄─────┘│
│   (8 KB)        │        │
│  [frame 3]      │        │
│  [frame 4]      │        │
│  overflow ──────────────┘
└─────────────────┘

Problems with Segmented Stacks:

Hot Split Problem: Every function call that might overflow the current segment required a bounds check. On deeply nested calls, this check happened frequently, causing "hot splits" where the stack grew one segment at a time with high overhead.
Cache Locality: Segments were scattered in memory, destroying CPU cache locality for stack-heavy workloads.
Pointer Chasing: Accessing the previous segment required following a pointer, adding latency.
Fragmentation: The heap accumulated many small stack segments.

The Contiguous Stack Revolution (Go 1.3+)

Go 1.3 introduced contiguous stacks using the copy strategy. When a stack overflows, instead of allocating a new segment:

Allocate a larger contiguous buffer (2x the current size)
Copy all stack frames to the new buffer
Update all pointers and references within the new stack

This eliminated the hot split problem because stack growth was infrequent and involved larger jumps.

Contiguous Stack Growth:

Initial State (2 KB):
┌────────────────────────────┐
│   Goroutine Stack (2 KB)   │
│   [main frame]             │
│   [foo frame]              │
│   [bar frame]              │
│   [used: 2 KB]             │ ◄── Stack Pointer
└────────────────────────────┘

Stack Overflow Detected:
    Allocate new 4 KB buffer
    Copy all frames
    Update pointers

After Growth (4 KB):
┌────────────────────────────────────────┐
│   Goroutine Stack (4 KB)               │
│   [main frame]                         │
│   [foo frame]                          │
│   [bar frame]  ◄── Adjusted            │
│   [used: 2 KB] [free: 2 KB]            │
│   Stack Pointer ──►│                   │
└────────────────────────────────────────┘

Current Stack Management (Go 1.13+)

Initial Stack Size: 2 KB

When a new goroutine is created, the runtime allocates exactly 2 KB of stack space:

// runtime/stack.go (simplified)
const (
    _StackMin = 2048 // 2 KB minimum stack size
)

func newg(fn *funcval, gp *g) *g {
    newg := mallocgstruct()
    newg.stack = stackalloc(_StackMin)
    return newg
}

Why 2 KB?

Small enough for millions of goroutines without exhausting virtual memory
Large enough for typical lightweight goroutines (main frame + a few calls)
Power of 2 for efficient allocation and growth

Historical context:

Go 1.0: Started with 8 KB
Go 1.1: Reduced to 4 KB
Go 1.4+: Reduced to 2 KB as stack copying became more efficient

Stack Growth Mechanism

When a function's prologue detects that the current stack isn't sufficient, it triggers runtime.morestack().

Stack Overflow Detection:

Function Prologue (compiler-generated):
    CMP  RSP, g.stackguard0  ; Check if SP is below guard
    JBE  morestack           ; If equal/below, grow stack
    ; Normal function execution
    ...
    RET

If overflow detected:
    CALL runtime.morestack()
    ; After morestack returns, the function retries

The Stack Guard:

// runtime/stack.go (simplified)
type g struct {
    stack       stack      // Stack bounds
    stackguard0 uintptr    // Comparison point for stack overflow
    stackguard1 uintptr    // Comparison point for preemption
    stackAlloc  uintptr    // Allocated stack size
    // ...
}

type stack struct {
    lo uintptr  // Bottom of stack
    hi uintptr  // Top of stack
}

The stackguard0 is set to stack.lo + StackGuard (typically 1 KB below the actual bottom), providing a safety margin for the overflow trap handler.

Stack Copying and Pointer Adjustment

When runtime.morestack() is called, the stack must be copied while maintaining all pointer validity. This is the most complex part of Go's stack management.

Stack Copy Process:

Step 1: Detect Overflow
    Current stack: 2 KB (full)
    New allocation: 4 KB

Step 2: Allocate New Stack
┌────────────┐
│  Old Stack │  (2 KB)
│  [frames]  │
└────────────┘

    Allocate

┌────────────────────────┐
│   New Stack (4 KB)     │
│   [empty]              │
└────────────────────────┘

Step 3: Copy Frames
┌────────────┐        ┌────────────────────────┐
│  Old Stack │        │   New Stack (4 KB)     │
│ [main]     │ ──────►│ [main] (copied)        │
│ [foo]      │        │ [foo] (copied)         │
│ [bar]      │        │ [bar] (copied)         │
└────────────┘        │ [empty]                │
                      └────────────────────────┘

Step 4: Update Pointers Within Stack
┌────────────────────────┐
│   New Stack (4 KB)     │
│ [main]  ┌──────────┐   │
│ [foo]   │ pointer  │───┼──┐
│ [bar]   │ updated! │   │  │
│         └──────────┘   │  │
│         ▲──────────────┘  │
│ Points to frame within    │
│ new stack (not old)       │
└────────────────────────┘

Step 5: Cleanup
    Free old 2 KB stack
    Update g.stack bounds

How Pointer Adjustment Works:

Go uses the stack copy mechanism from Go 1.3 which scans for all pointers within the new stack range:

// Simplified pointer adjustment pseudocode
oldBase := oldStack.lo
newBase := newStack.lo
delta := newBase - oldBase

// Scan new stack for pointers to old stack
for each frame in newStack {
    for each pointer in frame {
        if pointer >= oldBase && pointer < oldBase+oldSize {
            // Pointer into old stack, adjust it
            pointer += delta
        }
    }
}

Limitation: Unscannable Pointers

Go must conservatively assume that all values that could be pointers are pointers:

// In a frame, this uint64 might be a pointer
var x uint64 = someValue

// Go will adjust it if it looks like a pointer into the old stack
// This is conservative but safe

The conservative approach prevents use-after-free bugs but means some adjustments happen unnecessarily.

Stack Shrinking

Stack growth is frequent, but stacks rarely shrink during normal execution. However, Go performs aggressive stack shrinking during garbage collection.

Stack Shrinking Conditions:

Triggered during GC mark phase
Only shrinks if used space is under 1/4 of allocated space
Creates a new smaller stack and copies frames
Old stack is freed

// runtime/stack.go (simplified)
func shrinkstack(gp *g) {
    oldsize := gp.stack.hi - gp.stack.lo
    newsize := findsize(gp.stackAlloc) // Next smaller power of 2

    // Only shrink if utilization is very low
    if gp.stkbar > gp.stack.lo+newsize/4 {
        return // Not worth shrinking
    }

    // Copy to new smaller stack
    copystack(gp, newsize)
}

Why 1/4 Threshold?

The 1/4 threshold ensures that shrinking only happens when there's significant wasted space, avoiding thrashing (repeated grow/shrink cycles).

The Hot Split Problem and Why It Mattered

With segmented stacks, even accessing a local variable required checking if the current segment had space:

// With segmented stacks, EVERY function entry had this cost
CMPQ    RSP, guardaddr
JBE     morestack      ◄── High frequency with deep recursion

This generated millions of branch mispredictions for deeply nested functions.

Performance Impact Example:

// Deep recursion with segmented stacks
func fibonacci(n int) int {
    if n <= 1 {
        return n
    }
    // Each function entry: bounds check
    // With 50 levels deep: 50 checks per call
    // With many calls: cache misses and branch mispredictions
    return fibonacci(n-1) + fibonacci(n-2)
}

With contiguous stacks, this check still happens, but far less frequently because stacks grow in large jumps.

Stack Frame Layout

Understanding stack frame layout is crucial for analyzing stack growth:

Higher Addresses (stack grows downward on most architectures)
    ┌──────────────────┐
    │ Return Address   │  (8 bytes on x86-64)
    ├──────────────────┤
    │ Argument Space   │  (caller-provided)
    ├──────────────────┤
    │ Local Variable 1 │
    │ Local Variable 2 │
    │ ...              │
    ├──────────────────┤
    │ Padding/Align    │  (for alignment)
    │                  │
    ├──────────────────┤
    │ Spill Space      │  (for register saves)
    │                  │
    └──────────────────┘
    ▲
    │ RSP (Stack Pointer)
Lower Addresses

Frame Size Factors:

// Large frame: 1 KB
func largeFrame(a int, b int, c int) {
    var data [1000]byte // 1 KB of data
    var slice []int     // 24 bytes for slice header
    var iface interface{} // 16 bytes for interface header
    // Total: ~1 KB just for locals
}

// Small frame: 32 bytes
func smallFrame(x int) {
    var a int       // 8 bytes
    var b int       // 8 bytes
    var c string    // 16 bytes (string header)
    // Total: 32 bytes
}

Goroutine Preemption and Stack Checks

Evolution: Cooperative to Asynchronous Preemption

Go 1.13 and Earlier: Cooperative Preemption

Stack checks were the only preemption point. Long-running loops without function calls could starve other goroutines.

// This loop blocks all preemption until a function call occurs
for i := 0; i < 1e10; i++ {
    sum += i
    // No function call = no preemption point
    // Goroutine blocks scheduler
}

// Call to a function allows preemption check
doWork() // Stack check in function prologue enables preemption

Go 1.14+: Asynchronous Preemption

Go 1.14 introduced signal-based asynchronous preemption. The scheduler can now preempt a goroutine at any point by:

Sending a signal (SIGURG on Unix, ContinueDebugEvent on Windows)
Signal handler checks if in user code (not runtime code)
If preemptible, modifies the goroutine context to call runtime.preemptPark()

// Go 1.14+ behavior
for i := 0; i < 1e10; i++ {
    sum += i
    // At any instruction, scheduler can send SIGURG
    // Signal handler preempts if safe
}

// Result: Fair scheduler, better latency

Signal Flow (Simplified):

┌──────────────────────────────────────┐
│ OS Timer Fires (10ms on modern Go)   │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│ Scheduler Checks for Preemptible G   │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│ Send SIGURG to G                     │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│ Signal Handler (signal_unix.go)      │
│ - Check if in user code              │
│ - If yes, inject preemption          │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│ G yields at next safe point          │
│ (during function call or GC)         │
└──────────────────────────────────────┘

Performance Implications

Stack Growth Cost

Stack growth involves:

Allocating new memory: ~1-5 microseconds
Copying all frames: proportional to stack depth
Updating pointers: proportional to pointer density

For a typical 2 KB → 4 KB growth:

Allocation:        ~1 µs
Copy (2 KB):       ~0.1 µs (memcpy is fast)
Pointer Update:    ~0.2 µs
───────────────────────────
Total:             ~1.3 µs

Impact on Latency:

// Without stack growth
func quickWork() {
    doSmallWork()  // Completes in ~1 µs
}

// First call (with stack growth)
var firstCall = true
func potentialWork() {
    if firstCall {
        firstCall = false
        // Stack growth cost: +1.3 µs
    }
    doSmallWork()  // Completes in ~1 µs
    // Total: ~2.3 µs on first growth
}

Benchmarking Stack Growth

package main

import (
    "testing"
    "fmt"
)

// Recursive function to trigger stack growth
func recursive(depth int) int {
    if depth == 0 {
        return 1
    }
    var largeFrame [256]int64 // 2 KB per frame
    return recursive(depth - 1) + largeFrame[0]
}

// Benchmark shallow recursion (no growth)
func BenchmarkShallowRecursion(b *testing.B) {
    for i := 0; i < b.N; i++ {
        recursive(3)  // 3 frames × 2 KB = 6 KB needed
                      // Most likely fits in 2 KB initial... wait
                      // Actually triggers growth first time
    }
}

// Benchmark deeper recursion (more growth)
func BenchmarkDeepRecursion(b *testing.B) {
    for i := 0; i < b.N; i++ {
        recursive(10)  // 10 frames × 2 KB each
                       // Multiple growth cycles
    }
}

// Benchmark with tight loop (no stack growth)
func BenchmarkTightLoop(b *testing.B) {
    for i := 0; i < b.N; i++ {
        sum := 0
        for j := 0; j < 1000; j++ {
            sum += j
        }
        _ = sum
    }
}

func main() {
    // Run benchmarks
    // go test -bench=. -benchmem
    fmt.Println("Run with: go test -bench=. -benchmem")
}

Sample Results (Intel i7-9700K):

BenchmarkShallowRecursion-8      5000000     238 ns/op   0 B/op   0 allocs/op
BenchmarkDeepRecursion-8          500000    2340 ns/op  4096 B/op   3 allocs/op
BenchmarkTightLoop-8           200000000      5.2 ns/op   0 B/op   0 allocs/op

Deep recursion is 10x slower due to stack growth and copying overhead.

High-Concurrency Scenarios

Creating 100,000 goroutines:

package main

import (
    "fmt"
    "sync"
)

func BenchmarkManyGoroutines(b *testing.B) {
    const numGoroutines = 100000

    b.ReportAllocs()
    b.ResetTimer()

    for i := 0; i < b.N; i++ {
        var wg sync.WaitGroup
        wg.Add(numGoroutines)

        for j := 0; j < numGoroutines; j++ {
            go func() {
                defer wg.Done()
                doSmallWork()
            }()
        }

        wg.Wait()
    }
}

func doSmallWork() {
    // Uses only ~100 bytes of stack (fits in 2 KB easily)
    var buf [100]byte
    _ = buf
}

Memory Usage Calculation:

100,000 goroutines × 2 KB per stack = 200 MB (idle)
100,000 goroutines × 4 KB per stack = 400 MB (first growth)
100,000 goroutines × 8 KB per stack = 800 MB (deep recursion)

Compare to:
100,000 OS threads × 1 MB per thread = 100 GB (completely infeasible)

Inspecting Stack Information

runtime.Stack()

Capture the entire stack as a string:

package main

import (
    "fmt"
    "runtime"
)

func deepFunction(depth int) {
    if depth == 0 {
        buf := make([]byte, 4096)
        n := runtime.Stack(buf, false)
        fmt.Printf("Stack dump (%d bytes):\n%s\n", n, buf[:n])
        return
    }
    deepFunction(depth - 1)
}

func main() {
    deepFunction(5)
}

Output:

Stack dump (1234 bytes):
goroutine 1 [running]:
main.deepFunction(0x0, 0xc00001a000, 0x1000, 0x1000)
    /tmp/main.go:11 +0x4a
main.deepFunction(0x1, 0x0, 0x0)
    /tmp/main.go:16 +0x59
main.deepFunction(0x2, 0x0, 0x0)
    /tmp/main.go:16 +0x59
...

GODEBUG Stack Information

# Print stack allocation info at shutdown
GODEBUG=stackinfo=1 ./program

# Output shows:
# Stack allocations: X bytes in Y allocations
# Stack copies: Z (due to growth)

# Get more details on each stack alloc
GODEBUG=stackinfo=2 ./program

Programmatic Stack Inspection

package main

import (
    "fmt"
    "runtime"
)

func inspectStackSize() {
    var m runtime.MemStats
    runtime.ReadMemStats(&m)

    // StackInuse: bytes allocated to stack that are currently in use
    // StackSys: bytes allocated to stack from the system
    fmt.Printf("Stack In Use: %d bytes\n", m.StackInuse)
    fmt.Printf("Stack System: %d bytes\n", m.StackSys)
    fmt.Printf("Num Goroutines: %d\n", runtime.NumGoroutine())
}

func main() {
    inspectStackSize()
}

Optimization Tips and Best Practices

Tip 1: Avoid Deep Recursion in Hot Paths

// BAD: Deep recursion triggers stack growth
func treeSum(node *TreeNode) int64 {
    if node == nil {
        return 0
    }
    return node.Val + treeSum(node.Left) + treeSum(node.Right)
}

// GOOD: Iterative with explicit stack
func treeSum(root *TreeNode) int64 {
    if root == nil {
        return 0
    }

    sum := int64(0)
    stack := []*TreeNode{root}

    for len(stack) > 0 {
        node := stack[len(stack)-1]
        stack = stack[:len(stack)-1]

        if node != nil {
            sum += node.Val
            stack = append(stack, node.Left, node.Right)
        }
    }

    return sum
}

Tip 2: Be Aware of Closure Captures

// Closure captures variables, allocating on stack
func createClosures(n int) []func() {
    closures := make([]func(), 0, n)

    for i := 0; i < n; i++ {
        // Each closure captures 'i'
        // Large loop = large frames
        closures = append(closures, func() {
            fmt.Println(i)
        })
    }

    return closures
}

// Better: Explicitly pass values
func createClosures(n int) []func() {
    closures := make([]func(), 0, n)

    for i := 0; i < n; i++ {
        val := i // Create new variable per iteration
        closures = append(closures, func() {
            fmt.Println(val)
        })
    }

    return closures
}

Tip 3: Minimize Frame Size

// BAD: Large temporary structures on stack
func processData(items []Item) {
    var results [10000]Result  // 10 KB on stack!
    for i, item := range items {
        results[i] = process(item)
    }
    // Process results...
}

// GOOD: Use heap allocation
func processData(items []Item) {
    results := make([]Result, len(items), len(items))
    for i, item := range items {
        results[i] = process(item)
    }
    // Process results...
}

Tip 4: Pre-allocate Goroutine Pools

// Avoid creating millions of goroutines if possible
type WorkerPool struct {
    jobs chan Job
    wg   sync.WaitGroup
}

func NewWorkerPool(numWorkers int) *WorkerPool {
    pool := &WorkerPool{
        jobs: make(chan Job, 100),
    }

    pool.wg.Add(numWorkers)
    for i := 0; i < numWorkers; i++ {
        go pool.worker()
    }

    return pool
}

func (p *WorkerPool) worker() {
    defer p.wg.Done()
    for job := range p.jobs {
        job.Do()
    }
}

Tip 5: Monitor Stack Metrics in Production

package main

import (
    "fmt"
    "runtime"
    "time"
)

func monitorStack() {
    ticker := time.NewTicker(10 * time.Second)
    defer ticker.Stop()

    for range ticker.C {
        var m runtime.MemStats
        runtime.ReadMemStats(&m)

        fmt.Printf("[%s] Goroutines: %d, Stack: %d MB, GC: %d\n",
            time.Now().Format("15:04:05"),
            runtime.NumGoroutine(),
            m.StackSys/1024/1024,
            m.NumGC,
        )
    }
}

func main() {
    go monitorStack()
    // Your application...
    select {}
}

Summary

Go's goroutine stack management evolved from problematic segmented stacks to efficient contiguous stacks with copying:

2 KB Initial Size: Balances memory efficiency with typical workload needs
Stack Growth: Triggered by overflow detection, causes ~1-2 microsecond latency for copy
Stack Copying: Conservative pointer scanning ensures correctness at cost of overhead
Stack Shrinking: Aggressive during GC if utilization is under 25%
Asynchronous Preemption (1.14+): Enables fair scheduling without deep recursion

Key takeaways for performance:

Avoid deep recursion in hot paths
Keep frame sizes reasonable
Be aware of goroutine lifecycle overhead
Monitor stack metrics in production
Pre-allocate when possible rather than creating millions of goroutines

Modern Go (1.14+) has excellent stack management that scales to millions of concurrent goroutines. Understanding these internals helps you write efficient concurrent code.

On this page