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, int81;uint16, int162;uint32, int32, float324;uint64, int64, float64, complex648;complex12816. "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 arestruct of size %d could be %dandstruct 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 ofgo build -gcflags=-mwith 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=-mpasses-mto the compiler: "print optimization decisions".-m -mprints 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 heapon thefmt.Printlnline: passing a value tofmt.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 ofxin bytes, including padding (for a slice or string, only the header, not the data it points to).unsafe.Alignof(x): the alignmentxneeds.unsafe.Offsetof(s.f): where fieldfstarts inside the structs.
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
}
- Predict
unsafe.Sizeof(Order{}), then print it and every field'sOffsetof. - Reorder the fields for the smallest size.
- Write
NewOrderreturning*Orderand returningOrder. - Check with
-gcflags=-mand-benchmemwhich 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
- Does
func f() int { x := 5; p := &x; return *p }makexescape? Check with-gcflags=-m. - Make
counterfrom the video not escape: what if the closure is called inside the function instead of returned? - What's
unsafe.Sizeofofstruct{ a int8; b int64; c int16 }, and of the best order? - Why does
fmt.Println(x)makexescape?
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
- Stack vs heap in Go? Stack: per goroutine, freed on return, no GC. Heap: outlives the function or is shared; freed by the GC.
- 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.
- How do you see escape decisions?
go build -gcflags=-m(add another-mfor reasons). - 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.
- Is returning a pointer to a local variable safe in Go? Yes; it escapes to the heap.
- 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.
- 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.
- How do you reduce a struct's size? Order fields from largest alignment to smallest;
fieldalignmentreports 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=-mshowsmoved 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,Offsetofshow 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.