SyntaxPilot
Courses/Go Programming/Lesson 55
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 55 of 89

Memory: stack, heap and escape analysis

stack vs heap allocationescape analysis-gcflags=-mwhat causes escapes (returning pointers, interfaces, closures)allocation costvalue vs pointer performance trade-offsstruct field alignment and paddingunsafe.SizeofAlignofOffsetoffieldalignment

These are the notes for Go episode 55. Every value lives either on a goroutine's stack (fast, freed when the function returns) or on the heap (shared, lives longer, freed later by the garbage collector). A function that returns the address of a local variable, a classic dangling pointer bug in C, works in Go because of escape analysis, and go build -gcflags=-m shows the compiler's decisions ("moved to heap: o"). We collect the usual reasons a value escapes, measure what a heap allocation costs with -benchmem, see when a pointer is the faster choice after all, and find the invisible padding bytes in a struct with unsafe.Sizeof, Alignof and Offsetof, removing them by putting the biggest fields first, which is what the fieldalignment analyzer suggests.

All outputs here are from real runs (Go 1.24.7, linux/amd64, a machine with 2 CPUs). Benchmark timings change between runs and machines; the allocation counts and sizes don't.

Facts and sources

  • The Go specification, section "Size and alignment guarantees" (from the Go 1.24.7 source): sizes byte, uint8, int8 1; uint16, int16 2; uint32, int32, float32 4; uint64, int64, float64, complex64 8; complex128 16. "For a variable x of struct type: unsafe.Alignof(x) is the largest of all the values unsafe.Alignof(x.f) for each field f of x, but at least 1."
  • golang.org/x/tools v0.40.0, go/analysis/passes/fieldalignment: "find structs that would use less memory if their fields were sorted"; its messages are struct of size %d could be %d and struct with %d pointer bytes could be %d.
  • The compiler messages quoted below (moved to heap, escapes to heap, does not escape, can inline) are real output of go build -gcflags=-m with Go 1.24.7.

Stack vs heap

In Raju's kitchen In a Go program
each cook's own counter: bowls piled on top, wiped when the dish is done the stack: one per goroutine, each call gets a fresh area, freed on return
the shared storeroom: things stay as long as anyone needs them the heap: values that outlive their function or are shared
a cleaner throws out what nobody uses the garbage collector (GC) frees unreachable heap values
  • Stack: a block of memory per goroutine (episode 43: it starts small and grows). Each function call gets a stack frame for its local variables; when the function returns, the whole frame is gone in one step. Allocating there is almost free and the GC never has to look at it.
  • Heap: memory for values that must live after the function that made them returns, or that are shared. Each heap value is an allocation, and the GC (episode 56) must later find out whether it's still used and free it.

Escape analysis

The puzzle: returning a pointer to a local

main.go:

package main

import "fmt"

type Order struct {
    ID    int
    Dish  string
    Price int
}

// returns a POINTER to a local variable. In C this is a classic bug.
func newOrder(id int) *Order {
    o := Order{ID: id, Dish: "masala dosa", Price: 90}
    return &o // o must outlive this function...
}

func total(a, b int) int {
    sum := a + b // sum dies with the function
    return sum
}

func main() {
    p := newOrder(7)
    fmt.Println(p.ID, p.Dish, p.Price, total(2, 3))
}

Commands:

$ go build -gcflags=-m
$ go run .

Real output (the compiler's notes are on stderr, the program's output on stdout):

$ go build -gcflags=-m
$ go run .
7 masala dosa 90 5
# shop
./main.go:12:6: can inline newOrder
./main.go:17:6: can inline total
./main.go:23:18: inlining call to newOrder
./main.go:24:45: inlining call to total
./main.go:24:16: inlining call to fmt.Println
./main.go:13:5: moved to heap: o
./main.go:24:16: ... argument does not escape
./main.go:24:18: p.ID escapes to heap
./main.go:24:24: p.Dish escapes to heap
./main.go:24:32: p.Price escapes to heap
./main.go:24:45: ~r0 escapes to heap

In C, o would live in newOrder's stack frame, freed on return, and the pointer would point at garbage: a dangling pointer. In Go it works, and the compiler says why: moved to heap: o.

Escape analysis is the compiler working out, at compile time, for every value, whether it can still be used after its function returns. If it can, the value escapes and is put on the heap; if not, it stays on the stack. You never choose; the compiler always picks a safe place. sum in total never leaves, so it stays on the stack and gets no message.

  • -gcflags=-m passes -m to the compiler: "print optimization decisions". -m -m prints more detail about why.
  • can inline newOrder: the compiler will copy this small function's body into its callers to save the cost of a call: inlining (episode 58).
  • p.ID escapes to heap on the fmt.Println line: passing a value to fmt.Println, whose parameters are ...any, stores it in an interface.

What makes a value escape

main.go:

package main

var keep *int // a package-level variable lives for the whole program

//go:noinline
func toInterface(x int) any { return x } // 1. stored in an interface

//go:noinline
func counter() func() int { // 2. captured by a closure that outlives us
    n := 0
    return func() int { n++; return n }
}

//go:noinline
func makeSlice(n int) []int { return make([]int, n) } // 3. size unknown when compiling

//go:noinline
func fixedSlice() int { s := make([]int, 8); return len(s) } // known, small, stays here

//go:noinline
func store(x int) { keep = &x } // 4. address saved somewhere that lives longer

func main() {
    toInterface(1)
    counter()()
    makeSlice(3)
    fixedSlice()
    store(5)
}

Commands:

$ go build -gcflags=-m

Real output:

$ go build -gcflags=-m
# shop
./main.go:11:12: can inline counter.func1
./main.go:6:38: x escapes to heap
./main.go:10:5: moved to heap: n
./main.go:11:12: func literal escapes to heap
./main.go:15:42: make([]int, n) escapes to heap
./main.go:18:34: make([]int, 8) does not escape
./main.go:21:12: moved to heap: x

//go:noinline is a compiler directive (a special comment, no space after //) that stops the compiler from inlining the function, so each message stays attached to its function.

Reason Compiler message Why
its address is returned moved to heap: o it must outlive the function
stored in an interface x escapes to heap an interface holds a pointer to its value
captured by a closure that outlives the function moved to heap: n, func literal escapes to heap the closure keeps using n
size unknown at compile time make([]int, n) escapes to heap the stack frame's size is fixed when compiling
small, known size, stays local make([]int, 8) does not escape fits in the frame
address saved somewhere longer-lived moved to heap: x a global (or map, channel, field of a heap value) keeps it

What an allocation costs

shop.go:

package shop

type Order struct {
    ID    int
    Dish  string
    Price int
}

//go:noinline
func NewOrderPtr(id int) *Order { return &Order{ID: id, Dish: "dosa", Price: 90} }

//go:noinline
func NewOrderVal(id int) Order { return Order{ID: id, Dish: "dosa", Price: 90} }

shop_test.go:

package shop

import "testing"

var sinkP *Order // keep results, so the compiler can't skip the work
var sinkV Order

func BenchmarkPointer(b *testing.B) {
    for i := 0; i < b.N; i++ {
        sinkP = NewOrderPtr(i) // the Order must live on the heap
    }
}

func BenchmarkValue(b *testing.B) {
    for i := 0; i < b.N; i++ {
        sinkV = NewOrderVal(i) // copied out: no heap at all
    }
}

Commands:

$ go test -bench . -benchmem

Real output:

$ go test -bench . -benchmem
goos: linux
goarch: amd64
pkg: shop
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkPointer-2      37889382            72.75 ns/op       32 B/op          1 allocs/op
BenchmarkValue-2        557145308            2.347 ns/op           0 B/op          0 allocs/op
PASS
ok      shop    6.157s

-benchmem adds two columns: B/op (bytes allocated per operation) and allocs/op (heap allocations per operation). The pointer version allocates one Order (32 bytes: an 8-byte int, a 16-byte string header and an 8-byte int) on the heap every time; the value version copies the struct into sinkV and allocates nothing. Every allocation also creates work for the garbage collector later.

Values vs pointers

shop.go:

package shop

type Menu struct {
    Prices [1024]int // 1024 ints = 8 KB
}

//go:noinline
func TodaysSpecialByValue(m Menu) int { // copies all 8 KB on every call
    return m.Prices[0]
}

//go:noinline
func TodaysSpecialByPointer(m *Menu) int { // copies 8 bytes: an address
    return m.Prices[0]
}

shop_test.go:

package shop

import "testing"

var menu Menu
var sink int

func BenchmarkByValue(b *testing.B) {
    for i := 0; i < b.N; i++ {
        sink = TodaysSpecialByValue(menu)
    }
}

func BenchmarkByPointer(b *testing.B) {
    for i := 0; i < b.N; i++ {
        sink = TodaysSpecialByPointer(&menu)
    }
}

Commands:

$ go test -bench . -benchmem

Real output:

$ go test -bench . -benchmem
goos: linux
goarch: amd64
pkg: shop
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkByValue-2      17091079            62.26 ns/op        0 B/op          0 allocs/op
BenchmarkByPointer-2    1000000000           0.6852 ns/op          0 B/op          0 allocs/op
PASS
ok      shop    1.902s

Passing Menu by value copies all 8 KB on every call; passing *Menu copies 8 bytes. Both functions only read the first price, so the copy is almost all the work. Neither allocates (menu is a package-level variable, which already lives outside any stack).

Prefer a value Prefer a pointer
small structs, numbers, read-only data big structs (copying costs)
can stay on the stack, no GC work the function must change the caller's value (episode 20)
no nil to check one shared copy for everyone

When it matters, measure with a benchmark and -gcflags=-m; escape analysis can surprise you both ways.

Alignment and padding

Packing a delivery box In memory
big jars only fit at the dividers, every 8 slots alignment: an int64 starts at an address that's a multiple of 8
empty gaps before a big jar padding: unused bytes the compiler adds
big jars first, small items after reorder fields, largest first

The processor reads memory in aligned chunks; a value whose address is a multiple of its alignment can be read in one go (on some processors a misaligned read isn't allowed at all). So the compiler places each field at a multiple of its alignment and inserts padding, and rounds the struct's size up to a multiple of its largest alignment so that every element of an array of the struct stays aligned.

Package unsafe contains operations that step around Go's type safety; Sizeof, Alignof and Offsetof are the safe part: they're computed by the compiler and only describe the layout.

  • unsafe.Sizeof(x): the size of x in bytes, including padding (for a slice or string, only the header, not the data it points to).
  • unsafe.Alignof(x): the alignment x needs.
  • unsafe.Offsetof(s.f): where field f starts inside the struct s.
package main

import (
    "fmt"
    "unsafe"
)

type Bill struct {
    Paid  bool  // 1 byte
    Total int64 // 8 bytes
    Veg   bool  // 1 byte
}

func main() {
    var b Bill
    fmt.Println("fields add up to:", 1+8+1, "bytes")
    fmt.Println("unsafe.Sizeof(b): ", unsafe.Sizeof(b))
    fmt.Println("Alignof(b.Total): ", unsafe.Alignof(b.Total))
    fmt.Println("Offsetof Paid, Total, Veg:",
        unsafe.Offsetof(b.Paid), unsafe.Offsetof(b.Total), unsafe.Offsetof(b.Veg))
    fmt.Println("one million bills:", 1_000_000*unsafe.Sizeof(b)/1_000_000, "MB")
}

Real output:

fields add up to: 10 bytes
unsafe.Sizeof(b):  24
Alignof(b.Total):  8
Offsetof Paid, Total, Veg: 0 8 16
one million bills: 24 MB

Layout: Paid at 0, 7 bytes of padding, Total at 8–15, Veg at 16, 7 bytes of padding at the end: 24 bytes, 14 of them padding.

The fix: biggest field first

package main

import (
    "fmt"
    "unsafe"
)

type Bill struct {
    Total int64 // biggest first
    Paid  bool
    Veg   bool
}

func main() {
    var b Bill
    fmt.Println("unsafe.Sizeof(b): ", unsafe.Sizeof(b))
    fmt.Println("Offsetof Total, Paid, Veg:",
        unsafe.Offsetof(b.Total), unsafe.Offsetof(b.Paid), unsafe.Offsetof(b.Veg))
    fmt.Println("one million bills:", 1_000_000*unsafe.Sizeof(b)/1_000_000, "MB")
}

Real output:

unsafe.Sizeof(b):  16
Offsetof Total, Paid, Veg: 0 8 9
one million bills: 16 MB

Same data, 16 bytes: a third less memory for a million bills.

fieldalignment

fieldalignment (golang.org/x/tools/go/analysis/passes/fieldalignment) is an analyzer, a program that reads your code and reports problems, like the checks inside go vet. It finds "structs that would use less memory if their fields were sorted" and reports struct of size 24 could be 16 (for our first Bill). It also reports pointer bytes: the part of a struct the GC must scan for pointers, which is smaller when pointer fields come first. It is not part of go vet and wasn't installed in the compiler used for this episode; install it with go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest and run fieldalignment ./....

Only reorder structs you have very many of, or that sit in hot loops; elsewhere keep the order that reads best.

Mini project: the lean order

type Order struct {
    Veg   bool
    ID    int64
    Paid  bool
    Qty   int16
    Price float64
    Rush  bool
}
  1. Predict unsafe.Sizeof(Order{}), then print it and every field's Offsetof.
  2. Reorder the fields for the smallest size.
  3. Write NewOrder returning *Order and returning Order.
  4. Check with -gcflags=-m and -benchmem which one allocates.
Solution
package main

import (
    "fmt"
    "unsafe"
)

type Order struct {
    Veg   bool
    ID    int64
    Paid  bool
    Qty   int16
    Price float64
    Rush  bool
}

type LeanOrder struct {
    ID    int64
    Price float64
    Qty   int16
    Veg   bool
    Paid  bool
    Rush  bool
}

func main() {
    var o Order
    fmt.Println("Order:", unsafe.Sizeof(o), "bytes")
    fmt.Println("offsets Veg ID Paid Qty Price Rush:", unsafe.Offsetof(o.Veg), unsafe.Offsetof(o.ID), unsafe.Offsetof(o.Paid),
        unsafe.Offsetof(o.Qty), unsafe.Offsetof(o.Price), unsafe.Offsetof(o.Rush))
    var l LeanOrder
    fmt.Println("LeanOrder:", unsafe.Sizeof(l), "bytes")
}

Real output:

Order: 40 bytes
offsets Veg ID Paid Qty Price Rush: 0 8 16 18 24 32
LeanOrder: 24 bytes

Veg 0, padding to 8, ID 8, Paid 16, padding to 18, Qty 18, padding to 24, Price 24, Rush 32, padding to 40. Reordered as ID, Price, Qty, Veg, Paid, Rush: 8 + 8 + 2 + 1 + 1 + 1 = 21, rounded up to 24. For steps 3 and 4, reuse the NewOrderPtr / NewOrderVal benchmark above: 1 allocs/op vs 0.

Common mistakes (and the real messages)

Mistake Real message / result Why Fix
thinking return &local is a bug (a C habit) works; moved to heap: o escape analysis nothing to fix
pointers everywhere "to be fast" 1 allocs/op heap + GC work values for small types
huge structs passed by value slower ns/op, 8 KB copied per call a full copy pass a pointer
adding field sizes by hand Sizeof = 24, not 10 padding unsafe.Sizeof
small fields between big ones struct of size 24 could be 16 padding gaps biggest first
unsafe.Sizeof of a slice to measure its data 24 whatever the length only the header len(s) * unsafe.Sizeof(s[0])
guessing about escapes surprised by -benchmem escape analysis is subtle -gcflags=-m, benchmarks

The real run behind the slice row:

package main

import (
    "fmt"
    "unsafe"
)

func main() {
    small := make([]int64, 3)
    big := make([]int64, 1_000_000)
    fmt.Println("Sizeof small:", unsafe.Sizeof(small), " Sizeof big:", unsafe.Sizeof(big))
    fmt.Println("data in big:", len(big)*int(unsafe.Sizeof(big[0])), "bytes")
    fmt.Println("Sizeof a string:", unsafe.Sizeof("masala dosa"))
}

Real output:

Sizeof small: 24  Sizeof big: 24
data in big: 8000000 bytes
Sizeof a string: 16

Practice

  1. Does func f() int { x := 5; p := &x; return *p } make x escape? Check with -gcflags=-m.
  2. Make counter from the video not escape: what if the closure is called inside the function instead of returned?
  3. What's unsafe.Sizeof of struct{ a int8; b int64; c int16 }, and of the best order?
  4. Why does fmt.Println(x) make x escape?
Solutions

1. No: p never leaves f, so x stays on the stack. The real -m output has no line about x at all.

2. func count3() int { n := 0; inc := func() { n++ }; inc(); inc(); inc(); return n }: the closure doesn't outlive count3. The real -m output is only can inline count3.func1 and three inlining call to count3.func1 lines: no moved to heap: n, so n stays on the stack.

3. a at 0, padding to 8, b at 8, c at 16, padding to 24: 24. As b, c, a: 8 + 2 + 1 = 11, rounded to 16.

4. fmt.Println takes ...any; putting x into an interface needs a pointer to a copy of x that may outlive the call, so the compiler puts it on the heap (for some small values it can avoid this, but not in general).

Quick quiz

1. struct { A bool; B int32; C bool } on linux/amd64: what's its unsafe.Sizeof? (From the video.)

A. 6 · B. 8 · C. 12 · D. 16

Answer

C. A 0, padding to 4, B 4–7, C 8, padding to 12. As B, A, C it's 8.

2. Who decides whether a Go value lives on the stack or the heap?

Answer

The compiler, by escape analysis, at compile time.

3. What does allocs/op mean in -benchmem output?

Answer

The number of heap allocations per benchmark iteration.

Interview questions

  1. Stack vs heap in Go? Stack: per goroutine, freed on return, no GC. Heap: outlives the function or is shared; freed by the GC.
  2. What is escape analysis? The compiler's compile-time analysis of whether a value can be used after its function returns; if so it's heap-allocated.
  3. How do you see escape decisions? go build -gcflags=-m (add another -m for reasons).
  4. Name things that cause escapes. Returning a pointer to a local, storing in an interface, closures that outlive the function, sizes unknown at compile time, storing a pointer in a global, map, channel or heap object.
  5. Is returning a pointer to a local variable safe in Go? Yes; it escapes to the heap.
  6. When should you pass a pointer instead of a value? Big structs, when the callee must modify the value, or when one copy must be shared; otherwise small values are often faster.
  7. What is struct padding? Unused bytes the compiler inserts so each field is aligned and the size is a multiple of the struct's alignment.
  8. How do you reduce a struct's size? Order fields from largest alignment to smallest; fieldalignment reports structs that could be smaller.

Glossary

Term Meaning Example
Stack per-goroutine memory; each call's frame is freed on return sum in total
Stack frame a function call's area on the stack newOrder's locals
Heap memory for values that outlive their function or are shared o after moved to heap
Allocation reserving memory on the heap for a value 1 allocs/op
Garbage collector (GC) frees heap values the program can no longer reach episode 56
Dangling pointer a pointer to memory that's been freed (a C bug) return &o in C
Escape analysis the compiler deciding stack or heap at compile time moved to heap: o
Escape a value that may be used after its function returns x escapes to heap
-gcflags=-m asks the compiler to print its optimization decisions go build -gcflags=-m
Inlining copying a small function's body into its caller can inline newOrder
//go:noinline a directive that forbids inlining a function above toInterface
Compiler directive a special //go: comment for the compiler //go:noinline
Closure a function value that captures variables around it func() int { n++; return n }
-benchmem adds B/op and allocs/op to benchmark output go test -bench . -benchmem
B/op, allocs/op bytes / heap allocations per operation 32 B/op 1 allocs/op
ns/op nanoseconds per operation benchmark speed
Alignment the address multiple a value must start at 8 for int64
Padding unused bytes inserted to keep fields aligned 7 bytes after Paid
unsafe the package for operations outside Go's type safety unsafe.Sizeof
unsafe.Sizeof a value's size in bytes, with padding 24
unsafe.Alignof the alignment a value needs 8
unsafe.Offsetof where a field starts inside its struct 0 8 16
Field reordering sorting fields to remove padding biggest first
Analyzer a program that checks code and reports problems fieldalignment, vet checks
fieldalignment an analyzer for structs that could be smaller struct of size 24 could be 16
Pointer bytes the prefix of a struct the GC must scan for pointers reported by fieldalignment

Summary

  • Stack: per goroutine, freed on return, free of GC work. Heap: outlives functions, shared, freed by the GC.
  • Escape analysis decides at compile time; go build -gcflags=-m shows moved to heap, escapes to heap, does not escape.
  • Values escape when their address is returned or stored somewhere long-lived, when put in an interface, captured by an outliving closure, or when their size is unknown.
  • Allocations cost time and GC work: count them with -benchmem. Small types → values; big or shared → pointers. Measure.
  • Alignment adds padding: unsafe.Sizeof, Alignof, Offsetof show it; biggest fields first removes it; fieldalignment finds it.

Next episode: the garbage collector: tri-colour concurrent mark and sweep, write barriers, the pacer, GOGC, GOMEMLIMIT, GODEBUG=gctrace=1, runtime.ReadMemStats, finalizers and runtime.AddCleanup, weak pointers.