Stack Management

Relevant source files

• src/cmd/go/testdata/script/test_cleanup_failnow.txt
• src/internal/race/norace.go
• src/internal/race/race.go
• src/runtime/arena.go
• src/runtime/asm.s
• src/runtime/cgocall.go
• src/runtime/cgocheck.go
• src/runtime/crash_test.go
• src/runtime/export_test.go
• src/runtime/heapdump.go
• src/runtime/malloc.go
• src/runtime/mbitmap.go
• src/runtime/mcache.go
• src/runtime/mcentral.go
• src/runtime/mgc.go
• src/runtime/mgcmark.go
• src/runtime/mgcmark_greenteagc.go
• src/runtime/mgcmark_nogreenteagc.go
• src/runtime/mgcpacer.go
• src/runtime/mgcstack.go
• src/runtime/mgcsweep.go
• src/runtime/mheap.go
• src/runtime/panic.go
• src/runtime/preempt.go
• src/runtime/proc.go
• src/runtime/race.go
• src/runtime/runtime2.go
• src/runtime/sizeof_test.go
• src/runtime/stack.go
• src/runtime/stkframe.go
• src/runtime/symtabinl.go
• src/runtime/symtabinl_test.go
• src/runtime/testdata/testprog/crash.go
• src/runtime/traceback.go

Purpose and Scope

This document describes the Go runtime's stack management system, which handles allocation, growth, shrinking, and deallocation of goroutine stacks. Each goroutine (represented by a g structure) has its own stack that grows and shrinks dynamically as needed.

For information about goroutine scheduling, see Goroutine Scheduler. For memory allocation that occurs on the heap, see Memory Management. For garbage collection interactions with stacks, see Garbage Collection.

Stack Structure and Representation

Stack Bounds

Each goroutine's stack is represented by a stack structure that defines the memory bounds:

The actual stack memory occupies the range <FileRef file-url="https://github.com/golang/go/blob/0bf3f64c/stack.lo, stack.hi). Stacks grow downward on all architectures, meaning the stack pointer decreases as the stack grows.\n\nSources#LNaN-LNaN" NaN file-path="stack.lo, stack.hi)`. Stacks grow downward on all architectures, meaning the stack pointer decreases as the stack grows.\n\nSources">Hii

Goroutine Stack Fields

The g structure contains several stack-related fields:

Field	Purpose
stack	Actual stack memory bounds
stackguard0	Guard value for user Go code stack growth checks
stackguard1	Guard value for system stack growth checks
stackLock	Lock for concurrent stack operations (sigprof/scang)

The stackguard0 field is compared against the stack pointer in the function prologue generated by the compiler. It is normally set to stack.lo + StackGuard, but can be set to the special value StackPreempt to trigger preemption.

The stackguard1 field serves a different purpose depending on the goroutine type:

• For g0 and gsignal stacks: set to stack.lo + StackGuard
• For regular goroutines: set to ~0 to trigger a crash if system stack code runs on a user stack

Sources: src/runtime/runtime2.go473-483

Sources: src/runtime/runtime2.go473-483

Stack Size Limits and Classes

Size Limits

The runtime enforces maximum stack sizes that vary by architecture:

Architecture	Maximum Stack Size
64-bit	1,000,000,000 bytes (1 GB)
32-bit	250,000,000 bytes (250 MB)

An upper ceiling of 2 * maxstacksize exists to prevent crashes when SetMaxStack is called with excessive values.

Sources: src/runtime/proc.go156-168

Stack Size Classes

Stacks are allocated in fixed size classes to enable efficient caching. The runtime uses multiple "orders" where each order is twice the size of the previous:

System	FixedStack	NumStackOrders	Cached Sizes
linux/darwin/bsd	2 KB	4	2KB, 4KB, 8KB, 16KB
windows/32	4 KB	3	4KB, 8KB, 16KB
windows/64	8 KB	2	8KB, 16KB
plan9	4 KB	3	4KB, 8KB, 16KB

Stacks larger than the maximum cached size are allocated directly from the heap. Each P (processor) maintains a per-order cache of up to 32 KB worth of stack segments per size class.

Sources: src/runtime/malloc.go135-150

Stack Allocation

Stack allocation is implemented by the stackalloc function, which uses a hierarchical caching strategy to minimize allocation overhead.

Stack Allocation Flow

Sources: src/runtime/stack.go339-451 src/runtime/proc.go152-295

Allocation Strategy Hierarchy

The stack allocator uses three levels of caching:

Level	Storage	Lock Required	Purpose
P-local cache	p.stackcache[order]	No	Fast path for small stacks
Global pool	stackpool[order]	Yes (stackpool[].item.mu)	Shared pool across Ps
OS allocation	sysAlloc	Yes (heap lock)	Fresh memory from OS

For stacks larger than _FixedStack (typically 2-8 KB), allocation bypasses the cache and goes directly to the OS via sysAlloc.

Constants:

• _StackCacheSize = 32 KB (maximum cached per order per P)
• _NumStackOrders = 2-4 (varies by OS/architecture)
• _FixedStack = 2-8 KB (minimum stack size)

Sources: src/runtime/stack.go67-140 src/runtime/malloc.go135-150

Stack Growth

Growth Trigger

Stack growth is triggered when the compiler-generated function prologue detects potential overflow. The compiler inserts a comparison of the stack pointer against g.stackguard0. When the condition is met, the function calls the runtime's morestack routine (implemented in assembly).

Stack Growth Detection Flow

Sources: src/runtime/stack.go20-67 src/runtime/stack.go935-1087

Growth Implementation

The newstack function coordinates stack growth:

Key Steps:

1. Size calculation: New stack size is computed based on requested frame size and current stack. Typically doubles the stack size, but respects minimum (_FixedStack) and maximum (maxstacksize) limits.

2. Stack allocation: Calls stackalloc(newsize) to obtain new stack memory.

3. Stack copying: The copystack function copies live data from old to new stack. This function:

   • Copies frame-by-frame from old stack to new stack
   • Uses stack maps to identify and adjust pointers
   • Handles special cases like defer records and panic structures

4. Sudog adjustment: Calls adjustsudogs(gp) to update sudog structures in channel wait queues that reference stack addresses. The g.activeStackChans flag indicates whether this step is necessary.

5. Old stack deallocation: Returns old stack via stackfree(oldstack).

6. Execution resumption: Uses gogo(&gp.sched) to resume execution on the new stack.

Special Handling:

Case	Field/Flag	Action
Preemption request	g.preempt = true	Call gopreempt_m() instead of growing
Active channels	g.activeStackChans = true	Acquire channel locks during adjustsudogs
No splitting allowed	g.throwsplit = true	Throw fatal error instead of growing

Sources: src/runtime/stack.go935-1087 src/runtime/stack.go795-920

Stack Growth and Preemption

The stackguard0 field serves a dual purpose. In addition to detecting stack overflow, it can be set to the special value StackPreempt to signal that the goroutine should be preempted:

Sources: src/runtime/runtime2.go473-483 src/runtime/runtime2.go514-516

Stack Shrinking

Shrinking Trigger and Implementation

Stack shrinking is initiated during garbage collection to reclaim unused stack space. The GC scans goroutine stacks via scanstack and may set the g.preemptShrink flag when detecting underutilization.

Stack Shrinking Flow

Sources: src/runtime/stack.go1090-1154 src/runtime/mgcmark.go1291-1345

Shrinking Process

The shrinkstack function performs the actual shrinking operation:

1. Threshold check: Shrinking only occurs if less than 1/4 of the stack is in use
2. Size calculation: New size is half the old size, but never below _FixedStack
3. Viability check: Ensures new size is at least twice the used space
4. Stack copying: Reuses copystack(gp, newsize) to copy to smaller stack
5. Deallocation: Returns old stack via stackfree(oldstack)

Shrinking is skipped if:

• Stack is already at minimum size (_FixedStack)
• Shrinking would not provide enough headroom (new size < used * 2)
• Goroutine has throwsplit flag set

Sources: src/runtime/stack.go1090-1154

Sources: src/runtime/runtime2.go516

Stack Guards and Overflow Detection

Guard Regions

The stack guard mechanism provides overflow detection without requiring a check on every instruction. The guard is positioned _StackGuard bytes above the bottom of the stack (stack.lo). The compiler generates different prologue code based on frame size:

Frame Size Categories:

Frame Size	Constant	Check Strategy
≤ _StackSmall	128 bytes	Simple compare: SP vs stackguard0
_StackSmall to _StackBig	~4 KB	Compare: SP - framesize + _StackSmall vs stackguard0
≥ _StackBig	~4 KB	Unconditional call to morestack

Functions with frames ≤ _StackSmall are allowed to protrude up to _StackSmall bytes below the guard without triggering overflow, optimizing the common case of small stack frames.

Key Constants (from stack.go):

_StackSystem = GOOS-dependent (e.g., 0 for most, 512 for Windows)
_StackGuard  = 928 bytes (Linux) or varies by OS
_StackSmall  = 128 bytes
_StackBig    = 4096 bytes

Special Values:

Value	Purpose
stackguard0 = stack.lo + _StackGuard	Normal overflow detection
stackguard0 = stackPreempt	Triggers preemption check instead

Sources: src/runtime/stack.go68-140

System Stack vs User Stack

Different goroutine types use different stackguard0 and stackguard1 configurations:

User Goroutines (regular g):

stackguard0 = stack.lo + _StackGuard  (or stackPreempt for preemption)
stackguard1 = stackFork               (~0, causes crash on misuse)

System Goroutines (g0, gsignal):

stackguard0 = stack.lo + _StackGuard
stackguard1 = stack.lo + _StackGuard

The stackguard1 field serves as a safety mechanism:

• On user goroutines, it is set to stackFork (~0), which causes a crash if runtime code that requires the system stack accidentally runs on a user stack
• On system goroutines (g0, gsignal), both guards point to the same location for consistent overflow detection

This configuration is set up in mcommoninit for M's system goroutines and in newproc1 for user goroutines.

Sources: src/runtime/runtime2.go473-483 src/runtime/proc.go1002-1041

Special Stack Types

g0 Stack

Each M (machine/OS thread) has a special g0 goroutine whose stack is used for:

• Runtime internal operations
• Stack growth operations (cannot grow stack while growing stack)
• CGO calls
• Signal handling setup

The g0 stack is typically allocated by the OS as the thread's default stack, making it safe to run C code compiled by gcc.

Sources: src/runtime/runtime2.go619

gsignal Stack

The gsignal goroutine has a dedicated stack for signal handling. This stack is separate from both user stacks and the g0 stack to ensure signal handlers can run even when other stacks are in inconsistent states.

The goSigStack field in the M structure holds the Go-allocated signal handling stack if the platform requires it.

Sources: src/runtime/runtime2.go626-627

Stack Type Comparison

Sources: src/runtime/runtime2.go619 src/runtime/runtime2.go626-627

Stack Copying and Pointer Adjustment

Challenges in Stack Copying

When a stack is copied during growth or shrinking, all pointers to the old stack must be updated. This includes:

1. Stack-internal pointers: Pointers within the stack that point to other locations on the same stack
2. Defer records: Defer statements that capture stack variables
3. Sudog structures: Channel operation waiters that reference stack memory
4. Active channels: Channels with operations in progress that reference the stack

The activeStackChans flag on the g structure indicates whether any unlocked channels point into the goroutine's stack. If set, stack copying must acquire channel locks to protect these regions.

Sources: src/runtime/runtime2.go525-530

Pointer Adjustment Algorithm

The runtime uses stack maps (generated by the compiler) to identify which stack slots contain pointers. During stack copying:

1. Walk the stack frames from bottom to top
2. For each frame, use the stack map to identify pointer slots
3. For each pointer that points to the old stack, calculate its offset and adjust it to point to the corresponding location in the new stack
4. Handle special cases like defer records and sudogs separately

Sources: src/runtime/runtime2.go525-530

Stack Allocation Caching

Per-P Stack Cache

Each processor (P) maintains a cache of free stacks to minimize allocation overhead:

Sources: src/runtime/malloc.go135-150

Each cache entry can hold up to _StackCacheSize (32 KB) worth of stacks for that size class. When the cache is full, stacks are returned to the global pool. When the cache is empty, stacks are obtained from the global pool or allocated fresh from the OS.

Sources: src/runtime/malloc.go135-150

Integration with Other Runtime Systems

Stack Scanning During GC

During garbage collection, the runtime scans goroutine stacks to find live pointers. This scanning:

1. Stops the goroutine at a safe point
2. Walks the stack frames using stack maps
3. Marks all reachable objects
4. May set preemptShrink if the stack is underutilized

The gcscandone flag in the g structure tracks whether a stack has been scanned during the current GC cycle.

Sources: src/runtime/runtime2.go524

Stack and Preemption

Asynchronous preemption uses stack guards as a signaling mechanism:

1. The scheduler sets g.preempt = true
2. The scheduler sets g.stackguard0 = StackPreempt
3. At the next function call, the goroutine checks stackguard0
4. The preemption check runs, and the goroutine yields if g.preempt is set

The preemptStop flag indicates whether to transition to _Gpreempted state or just deschedule.

Sources: src/runtime/runtime2.go514-515

Stack and CGO

When calling into C code, the runtime switches to the M's g0 stack:

1. The cgocall function switches from the current goroutine's stack to g0
2. C code executes on the g0 stack (which is safe for gcc-compiled code)
3. Return switches back to the goroutine's stack

This ensures that C code, which may not respect Go's stack conventions, operates on a stable, OS-allocated stack.

Sources: src/runtime/runtime2.go619

Error Conditions and Debugging

Stack Overflow Detection

When a stack overflow is detected, the runtime can respond in several ways depending on context:

• Normal overflow: Trigger stack growth
• g0/gsignal overflow: Fatal error (these stacks don't grow)
• Excessive growth: If a stack exceeds maxstacksize, panic
• System stack on user goroutine: Fatal error (detected via stackguard1 = ~0)

The badmorestackg0 and badmorestackgsignal functions handle the error cases for non-growable stacks.

Sources: src/runtime/proc.go590-605 src/runtime/proc.go607-611

Stack Debugging

Several debug flags and test functions assist with stack debugging:

• stackPoisonCopy: Poisons old stack memory after copying to detect use-after-free
• throwsplit: Flag on g that prevents stack splitting (for testing)
• ShrinkStackAndVerifyFramePointers: Test function that shrinks stack and verifies frame pointers

Sources: src/runtime/export_test.go435-450 src/runtime/runtime2.go525