Escape Analysis

The compiler’s lifetime question

Go gives you no control over stack vs heap — and that’s deliberate. At compile time, for every value the compiler performs escape analysis: it tries to prove the value cannot be referenced after its function returns. If the proof succeeds, the value lives on the stack and costs nothing to reclaim. If the compiler can’t prove it, the value escapes to the heap and becomes the garbage collector’s problem.

graph TD
V["value created in func f"] --> Q{"can the compiler prove<br/>no reference survives f?"}
Q -->|"proven safe"| S["stack — free to reclaim"]
Q -->|"cannot prove / does survive"| H["heap — GC reclaims later"]

Note the asymmetry: escape analysis is conservative. When in doubt, it heap-allocates. A value escaping doesn’t mean it will be used later — only that the compiler couldn’t rule it out.

Seeing the decisions: -gcflags=-m

The decisions are invisible at runtime, but the compiler will tell you at build time. Pass -m and it prints what stays and what escapes:

$ go build -gcflags=-m ./...
# command-line-arguments
./main.go:8:9: &User{...} escapes to heap
./main.go:14:13: ... argument does not escape
./main.go:14:14: u escapes to heap
./main.go:20:6: moved to heap: buf

Read it like this:

• escapes to heap / moved to heap — this value is heap-allocated.
• does not escape — it stayed on the stack. Good.
• Add a second -m (-gcflags='-m -m') for the compiler’s reasoning — which assignment or call forced the escape.

A common surprise: fmt.Println(x) makes x escape, because Println takes ...interface{} and the compiler must take x’s address to box it into an interface.

The patterns that escape

A handful of constructs reliably push a value to the heap. This runnable program exercises them, then uses MemStats to confirm the heap traffic is real — even though the escape decision itself happened at compile time:

package main

import (
"fmt"
"runtime"
)

type Big struct{ data [64]int }

// 1. Returning a pointer to a local → escapes.
func makePtr() *Big { return &Big{} }

// 2. Stack-only: created, used, discarded. Does NOT escape.
func sumLocal() int {
var b Big // stays on the stack
for i := range b.data {
	b.data[i] = i
}
s := 0
for _, v := range b.data {
	s += v
}
return s
}

func mallocs() uint64 {
var m runtime.MemStats
runtime.ReadMemStats(&m)
return m.Mallocs
}

func main() {
// Stack path: 100k calls, near-zero heap growth.
a := mallocs()
total := 0
for i := 0; i < 100_000; i++ {
	total += sumLocal()
}
b := mallocs()
fmt.Printf("sumLocal: ~%d heap objects (stays on stack)\n", b-a)

// Heap path: each makePtr allocates.
c := mallocs()
keep := make([]*Big, 0, 100_000)
for i := 0; i < 100_000; i++ {
	keep = append(keep, makePtr())
}
d := mallocs()
fmt.Printf("makePtr: ~%d heap objects (escaped)\n", d-c)
_ = total
_ = keep
}

The first loop barely moves Mallocs; the second adds ~100,000. Same-looking code, opposite allocation behavior — and -gcflags=-m would have told you which is which before you ran it.

Common escape triggers

Reference

See also

• the stack & the heap — the two destinations escape analysis chooses between.
• the memory allocator — what services the heap allocations escapes create.
• interfaces, itab & eface — why interface assignment forces escapes.
• benchmarks — measuring allocations with -benchmem / ReportAllocs.

Next: where an escaped value actually lands — the memory allocator.

Related topics