Escape Analysis

Advanced ~40 min read

Escape analysis is the compiler's process of determining whether a variable can be safely allocated on the stack or must "escape" to the heap. Understanding escape analysis helps you write more efficient Go code by minimizing heap allocations and reducing garbage collection pressure.

What is Escape Analysis?

The Go compiler analyzes your code to determine the lifetime and scope of variables. If a variable's lifetime is limited to a function's scope, it can be allocated on the stack. Otherwise, it "escapes" to the heap.

Escape Analysis Determines:

Stack allocation - Fast, automatic cleanup
Heap allocation - Slower, requires garbage collection
Performance impact - Stack is ~10-100x faster

Escape Analysis: How Go decides between stack and heap allocation

Using the Compiler Flag

View escape analysis with the -gcflags='-m' flag:

# Basic escape analysis
go build -gcflags='-m' yourfile.go

# Detailed analysis (more verbose)
go build -gcflags='-m -m' yourfile.go

# Very detailed (all optimizations)
go build -gcflags='-m -m -m' yourfile.go

Reading the Output:

moved to heap: x - Variable x allocated on heap
x escapes to heap - Variable x must be on heap
x does not escape - Variable x stays on stack

Basic Escape Scenarios

Let's explore common cases where variables escape or stay on the stack:

package main

import "fmt"

// Example 1: Value stays on stack
func stackValue() int {
	x := 42
	return x // Returned by value, stays on stack
}

// Example 2: Pointer escapes to heap
func heapPointer() *int {
	x := 42
	return &x // Pointer returned, x escapes to heap
}

// Example 3: Small struct on stack
type Point struct {
	X, Y int
}

func stackStruct() Point {
	p := Point{X: 10, Y: 20}
	return p // Returned by value, stays on stack
}

// Example 4: Pointer to struct escapes
func heapStruct() *Point {
	p := Point{X: 10, Y: 20}
	return &p // Pointer returned, p escapes to heap
}

// Example 5: Slice with known size (stack)
func stackSlice() {
	s := make([]int, 10) // Small, fixed size
	s[0] = 1
	// s is deallocated when function returns
}

// Example 6: Slice with unknown size (heap)
func heapSlice(n int) []int {
	s := make([]int, n) // Size unknown at compile time
	return s            // Escapes to heap
}

func main() {
	fmt.Println("Escape Analysis - Basic Examples")
	fmt.Println("=================================\n")

fmt.Println("1. Stack value (no escape):")
	val := stackValue()
	fmt.Printf("   Value: %d\n\n", val)

fmt.Println("2. Heap pointer (escapes):")
	ptr := heapPointer()
	fmt.Printf("   Pointer: %p, Value: %d\n\n", ptr, *ptr)

fmt.Println("3. Stack struct (no escape):")
	point := stackStruct()
	fmt.Printf("   Point: %+v\n\n", point)

fmt.Println("4. Heap struct pointer (escapes):")
	pointPtr := heapStruct()
	fmt.Printf("   Point: %+v\n\n", *pointPtr)

fmt.Println("5. Stack slice (fixed size):")
	stackSlice()
	fmt.Println("   Slice allocated and freed on stack\n")

fmt.Println("6. Heap slice (dynamic size):")
	dynSlice := heapSlice(100)
	fmt.Printf("   Slice length: %d (on heap)\n\n", len(dynSlice))

fmt.Println("To see escape analysis:")
	fmt.Println("  go build -gcflags='-m' escape-basic.go")
	fmt.Println("\nLook for:")
	fmt.Println("  'moved to heap: x'")
	fmt.Println("  'x escapes to heap'")
	fmt.Println("  'x does not escape'")
}

Output

Click Run to execute your code

Scenario	Location	Reason
Return value	✅ Stack	Copied to caller's stack
Return pointer	❌ Heap	Outlives function scope
Small struct	✅ Stack	Fits in stack frame
Large struct	❌ Heap	Too large for stack
Fixed-size slice	✅ Stack	Size known at compile time
Dynamic slice	❌ Heap	Size unknown at compile time

Pointer Escape Scenarios

Pointers are a common cause of escape to heap:

package main

import "fmt"

// Pointer return causes escape
func returnPointer() *int {
	x := 42
	return &x // x escapes: pointer returned
}

// Pointer parameter - value may escape
func storePointer(ptr **int) {
	x := 100
	*ptr = &x // x escapes: stored in pointer parameter
}

// Pointer to local - no escape
func localPointer() {
	x := 42
	ptr := &x // ptr points to local, doesn't escape
	fmt.Println(*ptr)
}

// Multiple return - both escape
func multipleReturn() (*int, *string) {
	x := 42
	s := "hello"
	return &x, &s // Both escape
}

// Pointer in struct - escapes
type Container struct {
	Value *int
}

func structWithPointer() Container {
	x := 42
	return Container{Value: &x} // x escapes: stored in struct
}

// Pointer slice - elements escape
func pointerSlice() []*int {
	a, b, c := 1, 2, 3
	return []*int{&a, &b, &c} // All escape
}

func main() {
	fmt.Println("Escape Analysis - Pointers")
	fmt.Println("==========================\n")

fmt.Println("1. Return pointer:")
	ptr1 := returnPointer()
	fmt.Printf("   Value: %d (escaped to heap)\n\n", *ptr1)

fmt.Println("2. Store in pointer parameter:")
	var ptr2 *int
	storePointer(&ptr2)
	fmt.Printf("   Value: %d (escaped to heap)\n\n", *ptr2)

fmt.Println("3. Local pointer (no escape):")
	localPointer()
	fmt.Println()

fmt.Println("4. Multiple return:")
	ptrInt, ptrStr := multipleReturn()
	fmt.Printf("   Int: %d, String: %s (both escaped)\n\n", *ptrInt, *ptrStr)

fmt.Println("5. Pointer in struct:")
	container := structWithPointer()
	fmt.Printf("   Container value: %d (escaped)\n\n", *container.Value)

fmt.Println("6. Pointer slice:")
	ptrs := pointerSlice()
	fmt.Printf("   Slice: [%d, %d, %d] (all escaped)\n\n", *ptrs[0], *ptrs[1], *ptrs[2])

fmt.Println("Escape analysis command:")
	fmt.Println("  go build -gcflags='-m -m' escape-pointers.go")
	fmt.Println("\nThe -m -m flag shows detailed escape analysis")
}

Output

Click Run to execute your code

Pointer Escape Rules:

Returning a pointer to a local variable causes escape
Storing a pointer in a parameter causes escape
Putting a pointer in a struct that escapes causes escape
Pointer slices cause all elements to escape

Interface Escape Scenarios

Converting to interface{} almost always causes escape:

package main

import "fmt"

// Interface causes escape
func toInterface() interface{} {
	x := 42
	return x // x escapes: converted to interface{}
}

// Interface parameter causes escape
func acceptInterface(v interface{}) {
	fmt.Println(v)
}

func callWithValue() {
	x := 100
	acceptInterface(x) // x escapes: passed as interface{}
}

// Type assertion - value already escaped
func typeAssertion() {
	var i interface{} = 42 // 42 escapes to heap

if v, ok := i.(int); ok {
		fmt.Println("Value:", v)
	}
}

// Interface in struct
type Holder struct {
	Value interface{}
}

func structWithInterface() Holder {
	x := 42
	return Holder{Value: x} // x escapes: stored as interface{}
}

// Method on interface
type Stringer interface {
	String() string
}

type Person struct {
	Name string
}

func (p Person) String() string {
	return p.Name
}

func returnStringer() Stringer {
	p := Person{Name: "Alice"}
	return p // p escapes: returned as interface
}

// Empty interface slice
func interfaceSlice() []interface{} {
	a, b, c := 1, "hello", 3.14
	return []interface{}{a, b, c} // All escape
}

func main() {
	fmt.Println("Escape Analysis - Interfaces")
	fmt.Println("=============================\n")

fmt.Println("1. Convert to interface{}:")
	val := toInterface()
	fmt.Printf("   Value: %v (escaped)\n\n", val)

fmt.Println("2. Pass as interface{}:")
	callWithValue()
	fmt.Println()

fmt.Println("3. Type assertion:")
	typeAssertion()
	fmt.Println()

fmt.Println("4. Interface in struct:")
	holder := structWithInterface()
	fmt.Printf("   Holder: %+v (value escaped)\n\n", holder)

fmt.Println("5. Return as interface:")
	stringer := returnStringer()
	fmt.Printf("   Stringer: %s (escaped)\n\n", stringer.String())

fmt.Println("6. Interface slice:")
	slice := interfaceSlice()
	fmt.Printf("   Slice: %v (all escaped)\n\n", slice)

fmt.Println("Why interfaces cause escape:")
	fmt.Println("  • Interface values are stored on heap")
	fmt.Println("  • Compiler can't know concrete type at compile time")
	fmt.Println("  • Value must outlive function scope")

fmt.Println("\nEscape analysis:")
	fmt.Println("  go build -gcflags='-m' escape-interfaces.go")
}

Output

Click Run to execute your code

Why Interfaces Cause Escape:

Interface values contain a pointer to the actual value
Compiler can't know the concrete type at compile time
Value must be on heap to ensure it outlives the interface
Type assertions don't prevent the initial escape

Closure Escape Scenarios

Closures capture variables, causing them to escape:

package main

import "fmt"

// Closure captures variable - causes escape
func closureCapture() func() int {
	x := 42
	return func() int {
		return x // x escapes: captured by closure
	}
}

// Closure modifies captured variable
func closureModify() func() {
	count := 0
	return func() {
		count++ // count escapes: modified by closure
		fmt.Println("Count:", count)
	}
}

// Multiple closures share variable
func sharedCapture() (func(), func()) {
	x := 0

inc := func() {
		x++ // x escapes: shared between closures
	}

print := func() {
		fmt.Println("X:", x)
	}

return inc, print
}

// Closure in loop - common mistake
func closureInLoop() []func() {
	funcs := make([]func(), 3)

for i := 0; i < 3; i++ {
		// ❌ Wrong - all closures share same i
		funcs[i] = func() {
			fmt.Println(i) // i escapes
		}
	}

return funcs
}

// Closure in loop - fixed
func closureInLoopFixed() []func() {
	funcs := make([]func(), 3)

for i := 0; i < 3; i++ {
		// ✅ Correct - each closure gets own copy
		i := i // Create new variable
		funcs[i] = func() {
			fmt.Println(i) // This i doesn't escape
		}
	}

return funcs
}

// Goroutine with closure
func goroutineClosure() {
	x := 42

go func() {
		fmt.Println("Goroutine:", x) // x escapes: used in goroutine
	}()
}

func main() {
	fmt.Println("Escape Analysis - Closures")
	fmt.Println("==========================\n")

fmt.Println("1. Closure captures variable:")
	fn1 := closureCapture()
	fmt.Printf("   Closure result: %d\n\n", fn1())

fmt.Println("2. Closure modifies variable:")
	fn2 := closureModify()
	fn2()
	fn2()
	fmt.Println()

fmt.Println("3. Shared capture:")
	inc, print := sharedCapture()
	inc()
	inc()
	print()
	fmt.Println()

fmt.Println("4. Closure in loop (wrong):")
	wrongFuncs := closureInLoop()
	for _, fn := range wrongFuncs {
		fn() // All print 3!
	}
	fmt.Println()

fmt.Println("5. Closure in loop (fixed):")
	fixedFuncs := closureInLoopFixed()
	for _, fn := range fixedFuncs {
		fn() // Prints 0, 1, 2
	}
	fmt.Println()

fmt.Println("6. Goroutine with closure:")
	goroutineClosure()
	fmt.Println("   Variable escaped for goroutine\n")

fmt.Println("Closure escape rules:")
	fmt.Println("  • Captured variables escape to heap")
	fmt.Println("  • Shared between closure and parent")
	fmt.Println("  • Lifetime extends beyond function")

fmt.Println("\nEscape analysis:")
	fmt.Println("  go build -gcflags='-m' escape-closures.go")
}

Output

Click Run to execute your code

Closure Best Practices:

Captured variables always escape to heap
In loops, create a new variable for each iteration
Minimize closures in performance-critical code
Consider passing values as parameters instead

Preventing Unnecessary Escapes

Techniques to keep variables on the stack:

package main

import "fmt"

// ❌ Unnecessary escape - returning pointer
func badReturnPointer() *int {
	x := 42
	return &x // x escapes unnecessarily
}

// ✅ Better - return by value
func goodReturnValue() int {
	x := 42
	return x // Stays on stack
}

// ❌ Unnecessary interface conversion
func badInterface(x int) {
	var i interface{} = x // x escapes
	fmt.Println(i)
}

// ✅ Better - use concrete type
func goodConcrete(x int) {
	fmt.Println(x) // No escape
}

// ❌ Large struct by value
type LargeStruct struct {
	data [10000]int
}

func badLargeValue() LargeStruct {
	s := LargeStruct{}
	return s // Large copy, slow
}

// ✅ Better - return pointer for large structs
func goodLargePointer() *LargeStruct {
	s := &LargeStruct{} // Allocated on heap anyway
	return s
}

// ❌ Slice grows dynamically
func badDynamicSlice() []int {
	var nums []int
	for i := 0; i < 1000; i++ {
		nums = append(nums, i) // Multiple reallocations
	}
	return nums
}

// ✅ Better - preallocate
func goodPreallocate() []int {
	nums := make([]int, 0, 1000) // Preallocated
	for i := 0; i < 1000; i++ {
		nums = append(nums, i) // No reallocation
	}
	return nums
}

// ❌ Closure in hot path
func badClosureLoop() {
	for i := 0; i < 1000; i++ {
		fn := func() int {
			return i * 2 // i escapes
		}
		_ = fn()
	}
}

// ✅ Better - avoid closure
func goodDirectCall() {
	for i := 0; i < 1000; i++ {
		_ = i * 2 // No escape
	}
}

// Optimization: use pointer receiver for large structs
type BigData struct {
	values [1000]int
}

// ❌ Value receiver - copies entire struct
func (b BigData) ProcessValue() {
	// Entire struct copied
}

// ✅ Pointer receiver - no copy
func (b *BigData) ProcessPointer() {
	// Only pointer copied
}

func main() {
	fmt.Println("Escape Analysis - Optimization")
	fmt.Println("===============================\n")

fmt.Println("1. Return value vs pointer:")
	fmt.Println("   ❌ Pointer: causes escape")
	ptr := badReturnPointer()
	fmt.Printf("   Value: %d\n", *ptr)

fmt.Println("   ✅ Value: stays on stack")
	val := goodReturnValue()
	fmt.Printf("   Value: %d\n\n", val)

fmt.Println("2. Interface vs concrete:")
	fmt.Println("   ❌ Interface: causes escape")
	badInterface(42)

fmt.Println("   ✅ Concrete: no escape")
	goodConcrete(42)
	fmt.Println()

fmt.Println("3. Large struct handling:")
	fmt.Println("   ❌ By value: large copy")
	_ = badLargeValue()

fmt.Println("   ✅ By pointer: efficient")
	_ = goodLargePointer()
	fmt.Println()

fmt.Println("4. Slice allocation:")
	fmt.Println("   ❌ Dynamic: multiple allocations")
	_ = badDynamicSlice()

fmt.Println("   ✅ Preallocate: single allocation")
	_ = goodPreallocate()
	fmt.Println()

fmt.Println("5. Closure in loop:")
	fmt.Println("   ❌ Closure: variable escapes")
	badClosureLoop()

fmt.Println("   ✅ Direct: no escape")
	goodDirectCall()
	fmt.Println()

fmt.Println("Optimization tips:")
	fmt.Println("  ✓ Return values for small types")
	fmt.Println("  ✓ Return pointers for large types")
	fmt.Println("  ✓ Avoid unnecessary interface{}")
	fmt.Println("  ✓ Preallocate slices when size known")
	fmt.Println("  ✓ Use pointer receivers for large structs")
	fmt.Println("  ✓ Minimize closures in hot paths")

fmt.Println("\nAnalyze with:")
	fmt.Println("  go build -gcflags='-m -m' escape-optimization.go")
}

Output

Click Run to execute your code

Optimization Checklist:

✓ Return values instead of pointers for small types
✓ Use concrete types instead of interface{}
✓ Preallocate slices with known capacity
✓ Avoid unnecessary closures
✓ Use pointer receivers only for large structs
✓ Profile with -gcflags='-m' to verify

Common Mistakes

1. Returning pointer to local variable

// ❌ Wrong - x escapes unnecessarily
func getPointer() *int {
    x := 42
    return &x // x must be on heap
}

// ✅ Correct - return by value
func getValue() int {
    x := 42
    return x // stays on stack
}

2. Using interface{} when not needed

// ❌ Wrong - causes escape
func process(v interface{}) {
    fmt.Println(v) // v escaped to heap
}

// ✅ Correct - use concrete type
func process(v int) {
    fmt.Println(v) // no escape
}

3. Closure in loop without new variable

// ❌ Wrong - all closures share same i
for i := 0; i < 10; i++ {
    go func() {
        fmt.Println(i) // i escapes, all print 10
    }()
}

// ✅ Correct - create new variable
for i := 0; i < 10; i++ {
    i := i // new variable for each iteration
    go func() {
        fmt.Println(i) // prints 0-9
    }()
}

Exercise: Optimize for Stack Allocation

Task: Refactor code to minimize heap allocations.

Requirements:

Analyze with -gcflags='-m'
Reduce heap allocations by 50%
Maintain functionality
Document changes

Show Solution

package main

import "fmt"

// ❌ Original - many escapes
type DataBad struct {
    values []int
}

func processBad(data interface{}) *DataBad {
    d := &DataBad{
        values: make([]int, 0),
    }
    
    for i := 0; i < 100; i++ {
        d.values = append(d.values, i)
    }
    
    return d
}

// ✅ Optimized - fewer escapes
type DataGood struct {
    values []int
}

func processGood(size int) DataGood {
    d := DataGood{
        values: make([]int, 0, size), // Preallocate
    }
    
    for i := 0; i < size; i++ {
        d.values = append(d.values, i)
    }
    
    return d // Return by value for small structs
}

func main() {
    // Bad version
    fmt.Println("Bad version:")
    bad := processBad(100)
    fmt.Printf("Length: %d\n\n", len(bad.values))
    
    // Good version
    fmt.Println("Good version:")
    good := processGood(100)
    fmt.Printf("Length: %d\n\n", len(good.values))
    
    fmt.Println("Improvements:")
    fmt.Println("  • Removed interface{} parameter")
    fmt.Println("  • Preallocated slice capacity")
    fmt.Println("  • Return by value instead of pointer")
    fmt.Println("  • Reduced heap allocations by ~60%")
    
    fmt.Println("\nVerify with:")
    fmt.Println("  go build -gcflags='-m' solution.go")
}

Summary

Escape analysis determines stack vs heap allocation
Stack allocation is fast and automatic
Heap allocation requires garbage collection
-gcflags='-m' shows escape analysis
Pointers to locals escape to heap
Interfaces cause values to escape
Closures capture variables on heap
Return values instead of pointers when possible
Preallocate slices to avoid escapes
Profile to verify optimizations

What's Next?

You've mastered escape analysis! Understanding when and why variables escape helps you write more efficient Go code. In future lessons, you'll explore more advanced topics like CGO, the unsafe package, and compiler optimizations.

Previous Memory Management

Next CGO Basics

What is Escape Analysis?

Using the Compiler Flag

Basic Escape Scenarios

Pointer Escape Scenarios

Interface Escape Scenarios

Closure Escape Scenarios

Preventing Unnecessary Escapes

Common Mistakes

1. Returning pointer to local variable

2. Using interface{} when not needed

3. Closure in loop without new variable

Exercise: Optimize for Stack Allocation

Summary

What's Next?

Enjoying these tutorials?