SyntaxPilot
Courses/Go Programming/Lesson 77
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 77 of 89

Runtime internals tour

runtime packagegoroutine stack layout and growthinterface internals (iface, eface, itab)dynamic dispatch costmap and channel internals recapdefer implementation (open-coded defers)compiler pipeline (parse, type-check, SSA, machine code)go build -gcflags=-S assembly outputPlan 9 assembly (concept)

These are the notes for Go episode 77. For 76 episodes we drove the car; today we open the bonnet. Raju's sale day needs 100,000 helpers waiting at once, and operating-system threads would need 781 GB of stack for that. From that problem we invent the goroutine stack: start at 2 KB and grow by copying. Then we look inside an interface value (two machine words), price an interface call, peek inside a channel's ring buffer and a Swiss-table map, find out why a defer in a loop deadlocks and how the compiler builds defers, and finally follow the compiler from source code down to the assembly it writes.

All outputs below are from real runs (Go 1.24.7, linux/amd64, 2 CPUs, 16 November 2026), through the same runner the video's compiler uses. The runner prints each command as $ command and prints the error stream (stderr) after the normal output. Benchmark numbers depend on the machine and on what else it is doing: your numbers will differ, the comparison is what matters.

Warning. Several programs here read the runtime's private structures with unsafe. That is for learning only. The layouts are not part of the Go 1 compatibility promise (episode 2) and can change in any release. Never do this in real code.

Facts and sources

Every fact below was read from the Go 1.24.7 source and documentation that ship with the toolchain ($(go env GOROOT)/src and /doc):

  • runtime/stack.go: stackMin = 2048 (a new goroutine's stack is 2048 bytes). The stack shrinker's comment: "shrink the stack if gp is using less than a quarter of its current stack"; it halves the stack.
  • runtime/proc.go: "Max stack size is 1 GB on 64-bit, 250 MB on 32-bit" — maxstacksize = 1000000000 (64-bit) and 250000000 (32-bit). (Decimal, not 1<<30, "because they look nicer in the stack overflow failure message".)
  • runtime/runtime2.go: type iface struct { tab *itab; data unsafe.Pointer } and type eface struct { _type *_type; data unsafe.Pointer }. In the g struct (a goroutine): stack stack (lo, hi) then stackguard0 uintptr, "the stack pointer compared in the Go stack growth prologue", "offset known to liblink".
  • internal/abi/iface.go: type ITab struct { Inter *InterfaceType; Type *Type; Hash uint32 // copy of Type.Hash. Used for type switches.; Fun [1]uintptr // variable sized. fun[0]==0 means Type does not implement Inter. }
  • runtime/chan.go: type hchan struct { qcount uint // total data in the queue; dataqsiz uint // size of the circular queue; buf unsafe.Pointer; elemsize uint16; synctest bool; closed uint32; timer *timer; elemtype *_type; sendx uint // send index; recvx uint // receive index; recvq waitq // list of recv waiters; sendq waitq // list of send waiters; lock mutex }.
  • internal/runtime/maps/map.go: "The map design is based on Abseil's "Swiss Table" map design"; "Group: A group of abi.SwissMapGroupSlots (8) slots, plus a control word"; "Control word: An 8-byte word which denotes whether each slot is empty, deleted, or used. If a slot is used, its control byte also contains the lower 7 bits of the hash (H2)"; "H1: Upper 57 bits of a hash"; "Directory: Array of the tables used by the map". Swiss tables became the default map in Go 1.24 (episode 16).
  • cmd/compile/internal/walk/walk.go: const maxOpenDefers = 8. walk/stmt.go: open-coded defers are not used if there are more than 8 defers or a defer is in a loop. ssagen/ssa.go: open-coded defers are also turned off when NumReturns*NumDefers > 15.
  • cmd/compile/README.md: the compiler "may be logically split in four phases"; "the name "gc" stands for "Go compiler", and has little to do with uppercase "GC", which stands for garbage collection"; the middle end does "dead code elimination, (early) devirtualization, function call inlining, and escape analysis"; walk replaces "operations on maps and channels ... with runtime calls"; SSA is "a lower-level intermediate representation with specific properties that make it easier to implement optimizations"; GOSSAFUNC dumps every SSA pass to ssa.html.
  • cmd/compile/abi-internal.md (amd64): register R14 holds the "Current goroutine".
  • doc/asm.html ("A Quick Guide to Go's Assembler"): "The assembler is based on the input style of the Plan 9 assemblers"; "the compiler operates on a kind of semi-abstract instruction set ... when you see an instruction like MOV what the toolchain actually generates for that operation might not be a move instruction at all"; "There are four predeclared symbols that refer to pseudo-registers ... FP: Frame pointer: arguments and locals. PC: Program counter: jumps and branches. SB: Static base pointer: global symbols. SP: Stack pointer: the highest address within the local stack frame"; "data in the instructions flows from left to right: MOVQ $0, CX clears CX".
  • The 8 MB default thread stack is what pthread_attr_getstacksize reported on this Linux machine (see the C program below); other systems use other defaults.

The runtime: what runs under your code

A car's driver uses the steering and the pedals: that is your code. Underneath, the engine and gearbox are always running: that is the runtime, code that the Go toolchain links into every program you build. It schedules goroutines (episode 44), collects garbage (episode 56), grows stacks, and implements maps and channels. The dashboard lets the driver see inside: that is the runtime package, the standard-library package that lets your program ask the runtime questions.

main.go:

// $ go run .
package main

import (
    "fmt"
    "runtime"
)

func main() {
    fmt.Println(runtime.Version(), runtime.GOOS, runtime.GOARCH)
    fmt.Println("CPUs:", runtime.NumCPU(), "GOMAXPROCS:", runtime.GOMAXPROCS(0))
    fmt.Println("goroutines:", runtime.NumGoroutine())

    _, file, line, _ := runtime.Caller(0) // where am I?
    fmt.Println("this line:", file, line)

    runtime.GC() // ask the garbage collector to run now
    var ms runtime.MemStats
    runtime.ReadMemStats(&ms)
    fmt.Println("GC cycles so far:", ms.NumGC)
}

Output:

$ go run .
go1.24.7 linux amd64
CPUs: 2 GOMAXPROCS: 2
goroutines: 1
this line: main.go 13
GC cycles so far: 1
Function What it tells you
runtime.Version() the Go version that built the program
runtime.GOOS, runtime.GOARCH the operating system and CPU architecture it was built for (episode 2)
runtime.NumCPU() how many logical CPUs the machine has
runtime.GOMAXPROCS(0) how many OS threads may run Go code at the same time (0 means "just tell me, don't change it")
runtime.NumGoroutine() how many goroutines exist right now (main is one)
runtime.Caller(0) the file and line of the code that called it (0 = this function)
runtime.GC() run a garbage collection now (for tests and experiments, not production)
runtime.ReadMemStats(&ms) fill a MemStats with memory numbers: heap, stacks, GC count

The problem: 100,000 customers on hold

It's sale day. 100,000 customers are each waiting for a payment reply at the same moment, and each needs a helper: something that waits on their behalf.

If every helper is an operating-system thread, each gets a fixed block of memory called a stack. A stack is the memory a function uses for its local variables and to remember where to return. Each function call adds a frame (that call's slice of the stack) on top, and the frame is removed when the call returns.

How big is a thread's stack? Ask the operating system with a small C program:

main.c:

#include <pthread.h>
#include <stdio.h>

int main(void) {
    pthread_attr_t attr;
    size_t size;
    pthread_attr_init(&attr);
    pthread_attr_getstacksize(&attr, &size); // what a new OS thread gets
    printf("default thread stack: %zu bytes (%zu MB)\n", size, size / 1024 / 1024);
    printf("100,000 threads would reserve: %zu GB\n", size / 1024 / 1024 * 100000 / 1024);
    return 0;
}

Output:

default thread stack: 8388608 bytes (8 MB)
100,000 threads would reserve: 781 GB

781 GB of reserved stack. No sale-day server has that. Now the same in Go: 100,000 goroutines, each waiting on a channel like a customer on hold. StackInuse in MemStats is the memory currently used by goroutine stacks.

main.go:

// $ go run .
package main

import (
    "fmt"
    "runtime"
    "sync"
)

func main() {
    var before, after runtime.MemStats
    runtime.ReadMemStats(&before)

    const n = 100_000 // one goroutine per waiting customer
    var wg sync.WaitGroup
    stop := make(chan struct{})
    for i := 0; i < n; i++ {
        wg.Add(1)
        go func() { defer wg.Done(); <-stop }()
    }
    runtime.ReadMemStats(&after)
    fmt.Println("goroutines:", runtime.NumGoroutine())
    used := after.StackInuse - before.StackInuse
    fmt.Println("stack memory:", used/1024/1024, "MB")
    fmt.Println("per goroutine:", used/n, "bytes")
    close(stop)
    wg.Wait()
}

Output:

$ go run .
goroutines: 100001
stack memory: 195 MB
per goroutine: 2048 bytes

100,001 goroutines (counting main), 195 MB in total: 2048 bytes each. That is stackMin = 2048 in runtime/stack.go.

Why the threads failed

OS thread goroutine
Starting stack 8 MB (here), fixed 2 KB
Chosen before it starts, for the worst case small; grows when needed
100,000 of them 781 GB reserved 195 MB used

A thread's stack size is chosen up front, for the worst case, and almost all of it stays empty: code that just waits needs a few hundred bytes. Go starts small. That creates a new problem: what if one goroutine needs more than 2 KB?

Stack growth: moving to a bigger flat

depth calls itself 100,000 times and each frame holds 64 bytes, so it needs far more than 2 KB. We print the address of x, a local variable of main, before and after, using unsafe.Pointer (episode 75) and uintptr (an integer big enough to hold an address).

main.go:

// $ go run .
package main

import (
    "fmt"
    "unsafe"
)

func depth(n int) int {
    var pad [64]byte // a little space in every frame
    if n == 0 {
        return int(pad[0])
    }
    return depth(n-1) + int(pad[1])
}

func main() {
    x := 42 // lives on main's goroutine stack
    fmt.Printf("x is at %#x\n", uintptr(unsafe.Pointer(&x)))
    depth(100_000) // 100,000 calls deep: far more than 2 KB
    fmt.Printf("x is at %#x\n", uintptr(unsafe.Pointer(&x)))
    fmt.Println("x is still", x)
}

Output (addresses differ on every run):

$ go run .
x is at 0xc000092ef8
x is at 0xc0020dfef8
x is still 42

No crash, but x moved and still holds 42. The whole stack moved somewhere bigger. Like moving house:

  1. The flat is full → almost every Go function starts with a stack check in its prologue (its first few instructions): "is there room for my frame?"
  2. Move to a flat twice as big and carry every box → the runtime functions morestack and newstack allocate a stack twice the size, and copystack copies every frame into it.
  3. Update your address with the bank and the school → the runtime adjusts every pointer that points into the old stack. That's why x moved but still says 42.

When a goroutine uses less than a quarter of its stack, the garbage collector can shrink it by half.

This is also why the Go stack is called growable or contiguous: always one block, replaced by a bigger block when needed.

The 1 GB limit

main.go:

// $ go run .
package main

import "fmt"

func countdown(n int) int {
    return countdown(n+1) + 1 // no base case: it never stops
}

func main() {
    fmt.Println(countdown(0))
}

Output (first lines of the error stream; the trace continues for every goroutine):

$ go run .
runtime: goroutine stack exceeds 1000000000-byte limit
runtime: sp=0xc020160398 stack=[0xc020160000, 0xc040160000]
fatal error: stack overflow

runtime stack:
runtime.throw({0x4b5337?, 0x410b51?})
    /usr/local/go1.24.7/src/runtime/panic.go:1101 +0x48 fp=0x7ffe15dccae0 sp=0x7ffe15dccab0 pc=0x467908
runtime.newstack()
    /usr/local/go1.24.7/src/runtime/stack.go:1107 +0x5bb fp=0x7ffe15dccc18 sp=0x7ffe15dccae0 pc=0x45021b
runtime.morestack()
    /usr/local/go1.24.7/src/runtime/asm_amd64.s:621 +0x7a fp=0x7ffe15dccc20 sp=0x7ffe15dccc18 pc=0x46be9a

goroutine 1 gp=0xc000002380 m=0 mp=0x55f4c0 [running]:
main.countdown(0x2aaaa49?)
    main.go:5 +0x2b fp=0xc0201603a8 sp=0xc0201603a0 pc=0x491b0b
main.countdown(...)
    main.go:6
...44739049 frames elided...
main.main()
    main.go:10 +0x18 fp=0xc04015ff50 sp=0xc04015ff08 pc=0x491b38
exit status 2

On 64-bit systems the maximum stack is 1,000,000,000 bytes (about 1 GB; 250 MB on 32-bit). The trace shows the growth path: runtime.morestack called runtime.newstack, which refused to grow again. A fatal error is not a panic: recover cannot catch it, the program dies.

Goroutine stacks, written down

 stack.lo ─────────────────────────────────────────── stack.hi
 [ guard ][        free           ][ frame ][ frame ][ main ]
          ^ stackguard0            ^ SP      (frames are added downward)
  • Each goroutine (g in the runtime) records stack.lo and stack.hi, the two ends of its stack block, and stackguard0, a line a little above stack.lo.
  • SP, the stack pointer, is a CPU register holding the address of the top frame. Frames are added at lower addresses (the stack grows downward).
  • Prologue: if SP is below stackguard0, call morestack → newstack → copystack into a block twice the size, fix pointers, retry the function.
  • The GC halves a stack that uses less than a quarter of its size.
  • Limit: 1 GB on 64-bit → fatal error: stack overflow.

Interface internals: eface, iface and itab

In episode 21 we met the nil interface trap: an interface holding a nil pointer is not equal to nil. Now we can see why. An interface value is like a courier parcel:

Parcel Interface value
The label: what's inside the type word: which concrete type is stored
The box: the thing itself the data word: a pointer to the value
A how-to-use card on the label the itab: the type plus its method table (only for interfaces with methods)

A machine word is the natural unit of data of the CPU: 8 bytes on a 64-bit machine. So an interface value is 16 bytes. The runtime has two layouts:

  • eface ("empty face", empty interface): used for any / interface{}. Words: _type (pointer to the type's description) and data.
  • iface: used for interfaces with methods, such as Payer. Words: tab (pointer to an itab) and data.

We copy those layouts into our own structs and look at the words with unsafe:

main.go:

// $ go run .
package main

import (
    "fmt"
    "unsafe"
)

type Payer interface{ Pay(paise int) string }

type UPI struct{ id string }

func (u *UPI) Pay(paise int) string { return fmt.Sprint(u.id, " paid ", paise) }

// eface: what an empty interface (any) holds, two machine words
type eface struct{ typ, data unsafe.Pointer }

// iface: a non-empty interface, an itab pointer and a data pointer
type iface struct{ tab, data unsafe.Pointer }

func main() {
    var a any = 500
    fmt.Println("size of any:", unsafe.Sizeof(a), "bytes")
    e := (*eface)(unsafe.Pointer(&a))
    fmt.Println("type word set:", e.typ != nil, " value:", *(*int)(e.data))

    var p Payer     // nothing inside
    var u *UPI      // a nil pointer
    var q Payer = u // an interface holding a nil *UPI
    pi := (*iface)(unsafe.Pointer(&p))
    qi := (*iface)(unsafe.Pointer(&q))
    fmt.Println("p: tab", pi.tab != nil, "data", pi.data != nil, " p == nil:", p == nil)
    fmt.Println("q: tab", qi.tab != nil, "data", qi.data != nil, " q == nil:", q == nil)
}

Output:

$ go run .
size of any: 16 bytes
type word set: true  value: 500
p: tab false data false  p == nil: true
q: tab true data false  q == nil: false
  • any is 16 bytes: two words. Its data word points at 500.
  • p has no itab and no data: p == nil is true.
  • q has an itab (the type *UPI is known) and nil data. One word is set, so q != nil.

An interface is nil only when both words are empty. That's why a function returning error must return nil, never a nil *MyError (episode 24).

The itab

itab (one per (interface, concrete type) pair, built once and cached)
 ├── Inter  → the interface type (Payer)
 ├── Type   → the concrete type (*UPI)
 ├── Hash   → a copy of the type's hash, used to make type switches fast
 └── Fun[]  → method addresses, in the interface's method order

Calling q.Pay(5) compiles to: load q.tab, load Fun[0] from it, call that address with q.data as the receiver. This is dynamic dispatch: the function to call is decided at run time from data, not at compile time.

Dynamic dispatch cost

A benchmark (episode 42) measures how long code takes. BenchmarkDirect calls Tax on a GST value the compiler can see. BenchmarkInterface calls it through a Taxer returned by pick, which is marked //go:noinline (episode 76) so the compiler can't look inside and see the type.

shop.go:

package shop

type Taxer interface{ Tax(paise int) int }

type GST struct{}

func (GST) Tax(paise int) int { return paise * 18 / 100 }

//go:noinline
func pick() Taxer { return GST{} } // the caller can't see which type

shop_test.go:

package shop

import "testing"

var sink int

func BenchmarkDirect(b *testing.B) {
    g := GST{}
    for i := 0; i < b.N; i++ {
        sink = g.Tax(i) // known type: the call can even be inlined
    }
}

func BenchmarkInterface(b *testing.B) {
    t := pick()
    for i := 0; i < b.N; i++ {
        sink = t.Tax(i) // itab lookup, indirect call, no inlining
    }
}

Output:

$ go test -bench=. -benchtime=200000000x
goos: linux
goarch: amd64
pkg: shop
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkDirect-2       200000000            1.220 ns/op
BenchmarkInterface-2    200000000            2.017 ns/op
PASS
ok      shop    0.672s

ns/op is nanoseconds per call. Both are tiny; the interface call is a bit slower. The real cost is not the lookup: a direct call can be inlined (its body copied into the caller, so there is no call at all and further optimisations apply), and an indirect call (a call through an address loaded from memory) can't.

Devirtualization

If the compiler can prove which type an interface holds, it turns the interface call back into a direct call. That's devirtualization. -gcflags=-m prints the compiler's optimisation decisions:

main.go:

// $ go build -gcflags=-m .
package main

import "fmt"

type Taxer interface{ Tax(paise int) int }

type GST struct{}

func (GST) Tax(paise int) int { return paise * 18 / 100 }

func main() {
    var t Taxer = GST{} // the compiler can see the concrete type
    fmt.Println(t.Tax(1000))
}

Output:

$ go build -gcflags=-m .
# shop
./main.go:9:6: can inline GST.Tax
./main.go:13:22: devirtualizing t.Tax to GST
./main.go:13:22: inlining call to GST.Tax
./main.go:13:16: inlining call to fmt.Println
<autogenerated>:1: inlining call to GST.Tax
./main.go:12:22: GST{} does not escape
./main.go:13:16: ... argument does not escape
./main.go:13:22: ~r0 escapes to heap

devirtualizing t.Tax to GST, then inlining call to GST.Tax. Lesson: interfaces are cheap; design with them freely (episode 22) and measure only in hot loops. Go 1.21+ can also devirtualize using a CPU profile (profile-guided optimisation, episode 57).

Channel and map internals

unsafe.Sizeof gives the size of a variable's own part, its header, not the data it points to:

main.go:

// $ go run .
package main

import (
    "fmt"
    "unsafe"
)

func main() {
    var m map[string]int
    var ch chan int
    var s []int
    var str string
    var a any
    var f func()
    fmt.Println("map:   ", unsafe.Sizeof(m), "bytes, a pointer to the runtime's map")
    fmt.Println("chan:  ", unsafe.Sizeof(ch), "bytes, a pointer to an hchan")
    fmt.Println("func:  ", unsafe.Sizeof(f), "bytes, a pointer to the code (and closure)")
    fmt.Println("string:", unsafe.Sizeof(str), "bytes, pointer + length")
    fmt.Println("any:   ", unsafe.Sizeof(a), "bytes, type + data")
    fmt.Println("slice: ", unsafe.Sizeof(s), "bytes, pointer + length + capacity")
}

Output:

$ go run .
map:    8 bytes, a pointer to the runtime's map
chan:   8 bytes, a pointer to an hchan
func:   8 bytes, a pointer to the code (and closure)
string: 16 bytes, pointer + length
any:    16 bytes, type + data
slice:  24 bytes, pointer + length + capacity

A map, a channel and a func value are one pointer. Passing a map or a channel to a function copies that pointer, so everyone shares the same runtime structure. That's why a function can add to a map you pass it, but append on a slice you pass it is not seen by the caller unless you return the slice (episode 14).

hchan: a chai counter with 3 trays

A channel points to an hchan struct:

Chai counter hchan field
3 tray slots in a circle buf, a ring buffer (when you reach the end you continue from the start) of dataqsiz slots, qcount of them full
next empty tray, next full tray sendx, recvx: indexes that wrap around
people waiting to put or take sendq, recvq: queues of waiting goroutines
one person at the counter at a time lock: a mutex protecting all fields

This program copies the first fields of runtime.hchan in Go 1.24 and reads them (learning only):

main.go:

// $ go run .
package main

import (
    "fmt"
    "unsafe"
)

// The first fields of runtime.hchan in Go 1.24 (runtime/chan.go).
// Reading them is for learning only: never do this in real code.
type hchan struct {
    qcount   uint           // items in the buffer now
    dataqsiz uint           // buffer size (the cap)
    buf      unsafe.Pointer // the ring buffer
    elemsize uint16
    synctest bool
    closed   uint32
    timer    unsafe.Pointer
    elemtype unsafe.Pointer
    sendx    uint // where the next send goes
    recvx    uint // where the next receive comes from
}

func peek(name string, ch chan string) {
    h := *(**hchan)(unsafe.Pointer(&ch)) // a chan value is a pointer to an hchan
    fmt.Printf("%-10s qcount=%d size=%d sendx=%d recvx=%d closed=%d\n",
        name, h.qcount, h.dataqsiz, h.sendx, h.recvx, h.closed)
}

func main() {
    orders := make(chan string, 3) // a counter with 3 trays
    peek("new", orders)
    orders <- "chai"
    orders <- "samosa"
    peek("2 sent", orders)
    <-orders
    peek("1 taken", orders)
    orders <- "vada"
    orders <- "poha" // sendx wrapped around the ring
    peek("ring full", orders)
    close(orders)
    peek("closed", orders)
}

Output:

$ go run .
new        qcount=0 size=3 sendx=0 recvx=0 closed=0
2 sent     qcount=2 size=3 sendx=2 recvx=0 closed=0
1 taken    qcount=1 size=3 sendx=2 recvx=1 closed=0
ring full  qcount=3 size=3 sendx=1 recvx=1 closed=0
closed     qcount=3 size=3 sendx=1 recvx=1 closed=1

After "vada" goes into slot 2, sendx would be 3 = the size, so it wraps to 0; "poha" goes into slot 0 and sendx becomes 1. Closing sets closed but keeps the three items: receivers still get them (episode 47), then the zero value with ok == false.

What happens on a send: 1. Lock the hchan. 2. If a receiver is waiting in recvq, copy the value directly to it and wake it (no buffer used). 3. Else if the buffer has room, copy into buf[sendx], advance sendx, qcount++. 4. Else park the sender on sendq (it sleeps until a receiver arrives). An unbuffered channel always takes step 2 or 4.

Maps inside: Swiss tables (Go 1.24)

Since Go 1.24 the built-in map is a Swiss table, a hash-table design from Google's Abseil C++ library (episode 16 introduced hash tables and buckets).

  • The 64-bit hash of a key is split: H1 = upper 57 bits, H2 = lower 7 bits.
  • Slots come in groups of 8, each group with an 8-byte control word: one control byte per slot saying empty, deleted, or used plus that slot's H2.
  • Lookup: H1 picks the group to start in; all 8 control bytes are compared with H2 at once (one word-sized operation); only slots whose byte matches compare the real key. If not found and the group had no empty slot, probe the next group.
  • A big map is a directory of tables; the upper hash bits pick the table, and each table grows on its own, so one insert never has to copy the whole map.

How defer works

The problem: "I'll lock the cash box when I'm done"

Raju adds bills to the day's total. For each bill he locks the cash box (mu.Lock(), episode 45), adds it, and says "I'll unlock when I'm done" (defer mu.Unlock(), episode 10). He writes it in a loop:

main.go:

// $ go run .
package main

import (
    "fmt"
    "sync"
)

var mu sync.Mutex
var total int

func addBills(bills []int) {
    for _, p := range bills {
        mu.Lock()
        defer mu.Unlock() // "unlock when this bill is done"... really?
        total += p
        fmt.Println("added", p)
    }
}

func main() {
    addBills([]int{120, 80, 45})
    fmt.Println("total:", total)
}

Output:

$ go run .
added 120
fatal error: all goroutines are asleep - deadlock!

goroutine 1 [sync.Mutex.Lock]:
internal/sync.runtime_SemacquireMutex(0xc000062028?, 0x20?, 0xa?)
    /usr/local/go1.24.7/src/runtime/sema.go:95 +0x25
internal/sync.(*Mutex).lockSlow(0x57f0f0)
    /usr/local/go1.24.7/src/internal/sync/mutex.go:149 +0x15d
internal/sync.(*Mutex).Lock(...)
    /usr/local/go1.24.7/src/internal/sync/mutex.go:70
sync.(*Mutex).Lock(...)
    /usr/local/go1.24.7/src/sync/mutex.go:46
main.addBills({0xc000092f08, 0x3, 0x40afe8?})
    main.go:13 +0xe5
main.main()
    main.go:21 +0x3f
exit status 2

Why: a deferred call runs when the function returns, not at the end of the loop body. The second Lock waits for an Unlock that is still queued. A deadlock is when every goroutine is waiting for something that can never happen.

The fix: one function per bill.

main.go:

// $ go run .
package main

import (
    "fmt"
    "sync"
)

var mu sync.Mutex
var total int

func addBill(p int) {
    mu.Lock()
    defer mu.Unlock() // runs when addBill returns: after every bill
    total += p
    fmt.Println("added", p)
}

func main() {
    for _, p := range []int{120, 80, 45} {
        addBill(p)
    }
    fmt.Println("total:", total)
}

Output:

$ go run .
added 120
added 80
added 45
total: 245

Two ways the compiler builds defer

The debug flag -gcflags=-d=defer makes the compiler say how it built each defer:

shop.go:

package shop

import "sync"

var mu sync.Mutex
var total int

// one defer, at the top level of the function
func AddBill(p int) {
    mu.Lock()
    defer mu.Unlock()
    total += p
}

// the same defer, but written inside a loop
func AddBills(bills []int) {
    for range bills {
        mu.Lock()
        defer mu.Unlock() // runs at function end: one bill only, or it deadlocks
        total += bills[0]
    }
}

shop_test.go:

package shop

import "testing"

func BenchmarkOpenCoded(b *testing.B) {
    for i := 0; i < b.N; i++ {
        AddBill(100)
    }
}

func BenchmarkInLoop(b *testing.B) {
    one := []int{100}
    for i := 0; i < b.N; i++ {
        AddBills(one)
    }
}

Output:

$ go build -gcflags=-d=defer .
$ go test -bench=. -benchtime=20000000x
goos: linux
goarch: amd64
pkg: shop
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkOpenCoded-2    20000000            23.47 ns/op
BenchmarkInLoop-2       20000000            85.33 ns/op
PASS
ok      shop    2.203s
--- stderr ---
# shop
./shop.go:11:5: open-coded defer
./shop.go:19:9: heap-allocated defer

(The runner prints the compiler's messages, which go to stderr, after the normal output.) Same code, a different machine underneath, and the loop version is several times slower per call.

Open-coded defer Defer record (heap or stack allocated)
How the compiler copies the deferred call into the function at every return each defer statement creates a record on the goroutine's defer list; deferreturn runs the list at return
Bookkeeping one byte, deferBits: one bit per defer statement that has been reached a record per executed defer
When used at most 8 defers, none in a loop, returns × defers ≤ 15 otherwise (a loop means the count is only known at run time)
Cost almost free an allocation and a list walk

Either way, a panic still runs every deferred call (the runtime finds open-coded defers through FUNCDATA tables), so recover and cleanup keep working.

The compiler pipeline

The Go compiler is called gc, meaning "Go compiler" (nothing to do with GC, the garbage collector). It lives in cmd/compile. Like a kitchen turning a recipe into a meal:

Kitchen Compiler phase What happens
Read the recipe: words, then steps Front end: parse + type-check the source is split into tokens (words like func, Add, (), built into a syntax tree, and type-checked (every expression gets a type; errors like "mismatched types" come from here). Same ideas as go/parser and go/types in episode 76.
Plan the cooking Middle end on IR IR = intermediate representation, the compiler's own tree. Passes: dead code elimination, devirtualization, inlining, escape analysis (episode 55). Then walk splits complex statements and replaces map and channel operations with runtime calls (m[k] becomes a call into the map code).
Cook on this kitchen's stove Back end: SSA → machine code IR becomes SSA; generic passes simplify it; lower turns it into instructions for this GOARCH; regalloc chooses CPU registers; then machine code is written to an object file and the linker joins everything (including the runtime) into the binary.

-gcflags=-S: the assembly the compiler wrote

Add adds 5% tax: paise + paise/20.

tax/tax.go:

// $ go build -gcflags=-S ./tax
package tax

// Add adds 5% tax to a price in paise.
func Add(paise int) int {
    return paise + paise/20
}

Output (stderr):

# shop/tax
shop/tax.Add STEXT nosplit size=41 args=0x8 locals=0x0 funcid=0x0 align=0x0
    0x0000 00000 (tax/tax.go:4) TEXT    shop/tax.Add(SB), NOSPLIT|NOFRAME|ABIInternal, $0-8
    0x0000 00000 (tax/tax.go:4) FUNCDATA    $0, gclocals·FzY36IO2mY0y4dZ1+Izd/w==(SB)
    0x0000 00000 (tax/tax.go:4) FUNCDATA    $1, gclocals·FzY36IO2mY0y4dZ1+Izd/w==(SB)
    0x0000 00000 (tax/tax.go:4) FUNCDATA    $5, shop/tax.Add.arginfo1(SB)
    0x0000 00000 (tax/tax.go:4) FUNCDATA    $6, shop/tax.Add.argliveinfo(SB)
    0x0000 00000 (tax/tax.go:4) PCDATA  $3, $1
    0x0000 00000 (tax/tax.go:5) MOVQ    AX, CX
    0x0003 00003 (tax/tax.go:5) SARQ    $63, AX
    0x0007 00007 (tax/tax.go:5) MOVQ    AX, DX
    0x000a 00010 (tax/tax.go:5) MOVQ    $-3689348814741910323, AX
    0x0014 00020 (tax/tax.go:5) MOVQ    DX, BX
    0x0017 00023 (tax/tax.go:5) IMULQ   CX
    0x001a 00026 (tax/tax.go:5) ADDQ    CX, DX
    0x001d 00029 (tax/tax.go:5) SARQ    $4, DX
    0x0021 00033 (tax/tax.go:5) SUBQ    BX, DX
    0x0024 00036 (tax/tax.go:5) LEAQ    (DX)(CX*1), AX
    0x0028 00040 (tax/tax.go:5) RET
    0x0000 48 89 c1 48 c1 f8 3f 48 89 c2 48 b8 cd cc cc cc  H..H..?H..H.....
    ...

How to read it: - TEXT shop/tax.Add(SB), NOSPLIT|NOFRAME|ABIInternal, $0-8 starts the function: no stack check needed (NOSPLIT, it uses no stack), frame size 0, 8 bytes of arguments. - FUNCDATA / PCDATA are tables for the garbage collector and the stack maps (which words hold pointers), not instructions. - The argument arrives in register AX (Go's register-based calling convention, ABIInternal). - There is no divide instruction. $-3689348814741910323 is 0xCCCCCCCCCCCCCCCD: the compiler multiplies by a "magic" constant (IMULQ keeps the high 64 bits in DX) and shifts right (SARQ $4), which equals dividing by 20 but is much faster than a real division. The SARQ $63 / SUBQ pair corrects the result for negative numbers.

SSA: every value assigned once

SSA (static single assignment) is a form where every value gets a name (v6, v8, …) and is assigned exactly once. Because each name has one definition, the compiler can see where every value comes from, which makes optimisations simpler. GOSSAFUNC=Add saves every SSA pass for Add into an HTML file:

$ GOSSAFUNC=Add go build ./tax
# shop/tax
dumped SSA for Add,1 to ./ssa.html

From that ssa.html (shortened):

// start (from the type-checked IR)
v6  = Arg <int> {paise}
v8  = Const64 <int> [20]
v9  = Div64 <int> v6 v8
v10 = Add64 <int> v6 v9
Ret v11

// after the "lower" pass (amd64)
v3  = MOVQconst <uint64> [-3689348814741910323]
v4  = HMULQ <int> v3 v6
v7  = SARQconst <int> [4] v5
v10 = ADDQ <int> v9 v6

At the start it is Div64 then Add64, just like the source. After lower, the division is a multiply-high (HMULQ) and a shift. Other passes (deadcode, prove, regalloc, …) each rewrite this list; open the file in a browser and click through them.

go tool objdump: the finished binary

Disassembling turns machine code back into readable instructions. go tool objdump does it for a built binary:

main.go:

// $ go build -o shop .
// $ go tool objdump -s main.main shop
package main

import "fmt"

//go:noinline
func addTax(paise int) int {
    return paise + paise/20 // 5% tax
}

func main() {
    fmt.Println(addTax(2000))
}

Output (first and last lines):

TEXT main.main(SB) main.go
  main.go:10        0x491b20        493b6610        CMPQ SP, 0x10(R14)
  main.go:10        0x491b24        7656            JBE 0x491b7c
  main.go:10        0x491b26        55          PUSHQ BP
  main.go:10        0x491b27        4889e5          MOVQ SP, BP
  main.go:10        0x491b2a        4883ec38        SUBQ $0x38, SP
  main.go:11        0x491b2e        b8d0070000      MOVL $0x7d0, AX
  main.go:11        0x491b33        e8a8ffffff      CALL main.addTax(SB)
  ...
  main.go:12        0x491b7b        c3          RET
  main.go:10        0x491b7c        0f1f4000        NOPL 0(AX)
  main.go:10        0x491b80        e81ba3fdff      CALL runtime.morestack_noctxt.abi0(SB)
  main.go:10        0x491b85        eb99            JMP main.main(SB)

The very first instruction, CMPQ SP, 0x10(R14), is the stack check from the moving-house story. On amd64, R14 holds the current goroutine (g); 16 bytes (0x10) into g, after stack.lo and stack.hi, is stackguard0. JBE ("jump if below or equal") goes to the call to runtime.morestack_noctxt, which grows the stack, then JMP main.main starts the function again. MOVL $0x7d0, AX is 2000, the argument.

Plan 9 assembly

Go's assembly follows the input style of the Plan 9 assemblers. Plan 9 is an operating system from Bell Labs where Go's creators Rob Pike and Ken Thompson worked (episode 1).

MOVQ $0, CX      // data flows left → right: CX = 0
  • Direction: source first, destination last, on every architecture.
  • Size suffix: Q quad word = 8 bytes, L long = 4, W word = 2, B byte = 1.
  • Pseudo-registers (not real registers; names the toolchain manages): SB static base, for globals (foo(SB) is the global foo); FP frame pointer, for arguments; SP stack pointer, for locals; PC program counter, for jumps.
  • A hand-written function lives in a .s file next to the Go file that declares it: TEXT ·Add(SB), NOSPLIT, $0-16 (the middle dot · separates package and name; $0-16 = 0 bytes of frame, 16 bytes of arguments and results).
  • It is a semi-abstract instruction set: the toolchain does part of instruction selection, so a MOV may become another real instruction.

You'll rarely write assembly (the standard library uses it for crypto and math hot spots), but now you can read what the compiler gives you.

Under the bonnet, on one page

Layer What it does
your code functions, types, goroutines
compiler (gc) parse, type-check, inline, devirtualize, escape analysis, walk, SSA, machine code with stack checks
runtime scheduler, GC, growable stacks, maps (Swiss tables), channels (hchan), defers
OS threads, memory, files
  • goroutine: 2 KB stack, grows by copying, shrinks when < ¼ used, 1 GB limit.
  • interface: 2 words; nil only when both are empty; the itab holds the method table.
  • map, chan, func: one pointer to a runtime structure.
  • defer: open-coded (almost free) when ≤ 8, not in a loop, returns × defers ≤ 15.

Mini project: peek under the bonnet

  1. stackgrow: start 1,000 goroutines that recurse to depth 0, 10, 100 and 1,000 and print StackInuse while they wait.
  2. ifacepeek: print the two words of five different any values and explain each.
  3. bench: benchmark a direct, an interface and a generic call, and read -gcflags=-m.
  4. asm: compare the assembly for x/20, x/16, x%10 and an unsigned x/16 with -gcflags=-S.
  5. ssaloop: find a bounds check the prove pass removes, and one it can't.
Solution 1: stackgrow

stackgrow/main.go:

package main

import (
    "fmt"
    "runtime"
    "sync"
)

func dig(n int) int {
    var pad [128]byte // some room in every frame
    if n == 0 {
        return int(pad[0])
    }
    return dig(n-1) + int(pad[1])
}

func stackMB() uint64 {
    var ms runtime.MemStats
    runtime.ReadMemStats(&ms)
    return ms.StackInuse / 1024 / 1024
}

func main() {
    const workers = 1000
    for _, depth := range []int{0, 10, 100, 1000} {
        var wg sync.WaitGroup
        start, stop := make(chan struct{}), make(chan struct{})
        for i := 0; i < workers; i++ {
            wg.Add(1)
            go func() {
                defer wg.Done()
                dig(depth) // grow this goroutine's stack
                start <- struct{}{}
                <-stop // keep the grown stack alive
            }()
        }
        for i := 0; i < workers; i++ {
            <-start
        }
        fmt.Printf("depth %4d: StackInuse %3d MB\n", depth, stackMB())
        close(stop)
        wg.Wait()
    }
}

Output:

$ go run main.go
depth    0: StackInuse   2 MB
depth   10: StackInuse   4 MB
depth  100: StackInuse  15 MB
depth 1000: StackInuse 250 MB

Each stack grows in doublings (2 KB → 4 → 8 → …) and stays grown while the goroutine lives: at depth 1000 each needs about 150 KB of frames, so it has a 256 KB stack. Note that a goroutine keeps its big stack until the GC shrinks it, so one deep call early in a long-lived goroutine costs memory.

Solution 2: ifacepeek

ifacepeek/main.go:

package main

import (
    "errors"
    "fmt"
    "unsafe"
)

type eface struct{ typ, data unsafe.Pointer }

func words(name string, v any) {
    e := (*eface)(unsafe.Pointer(&v))
    fmt.Printf("%-14s type word set: %-5v data word set: %-5v v == nil: %v\n",
        name, e.typ != nil, e.data != nil, v == nil)
}

type Order struct{ ID int }

func main() {
    var nilOrder *Order
    words("nil any", nil)                 // both words empty
    words("int 500", 500)                 // type int, data points at 500
    words("string chai", "chai")          // type string, data points at a string header
    words("nil *Order", nilOrder)         // type *Order, data nil: NOT nil
    words("error value", errors.New("x")) // type *errors.errorString
}

Output:

$ go run main.go
nil any        type word set: false data word set: false v == nil: true
int 500        type word set: true  data word set: true  v == nil: false
string chai    type word set: true  data word set: true  v == nil: false
nil *Order     type word set: true  data word set: false v == nil: false
error value    type word set: true  data word set: true  v == nil: false

Only the first is nil. The fourth is the trap: a type with no value.

Solution 3: direct vs interface vs generic

bench/shop.go:

package shop

type Taxer interface{ Tax(paise int) int }

type GST struct{}

func (GST) Tax(paise int) int { return paise * 18 / 100 }

//go:noinline
func pick() Taxer { return GST{} }

// generic version: T is known for each instantiation shape
func TaxAll[T Taxer](t T, paise int) int { return t.Tax(paise) }

bench/shop_test.go:

package shop

import "testing"

var sink int

func BenchmarkDirect(b *testing.B) {
    g := GST{}
    for i := 0; i < b.N; i++ {
        sink = g.Tax(i)
    }
}

func BenchmarkInterface(b *testing.B) {
    t := pick()
    for i := 0; i < b.N; i++ {
        sink = t.Tax(i)
    }
}

func BenchmarkGeneric(b *testing.B) {
    g := GST{}
    for i := 0; i < b.N; i++ {
        sink = TaxAll(g, i)
    }
}

Output:

$ go build -gcflags=-m .
./shop.go:7:6: can inline GST.Tax
<autogenerated>:1: inlining call to GST.Tax
$ go test -bench=. -benchtime=200000000x
goos: linux
goarch: amd64
pkg: shop
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkDirect-2       200000000            1.531 ns/op
BenchmarkInterface-2    200000000            3.350 ns/op
BenchmarkGeneric-2      200000000            2.266 ns/op
PASS
ok      shop    1.458s

Direct is fastest (inlined). The generic call sits in between: Go compiles generics by GC shape stenciling (one copy of the code per memory shape, plus a hidden dictionary that describes the type), so a method call on a type parameter may still go through the dictionary. (This run was on a busy 2-CPU machine, so the absolute numbers are higher than in the video.)

Solution 4: division in assembly

asm/div/div.go:

package div

func By20(x int) int    { return x / 20 }
func By16(x int) int    { return x / 16 }
func Mod10(x int) int   { return x % 10 }
func UBy16(x uint) uint { return x / 16 }

Output of go build -gcflags=-S ./div (FUNCDATA, PCDATA and byte dumps removed):

shop/div.By20 STEXT nosplit size=38 args=0x8 locals=0x0 funcid=0x0 align=0x0
    TEXT    shop/div.By20(SB), NOSPLIT|NOFRAME|ABIInternal, $0-8
    MOVQ    AX, CX
    SARQ    $63, AX
    MOVQ    AX, DX
    MOVQ    $-3689348814741910323, AX
    MOVQ    DX, BX
    IMULQ   CX
    LEAQ    (DX)(CX*1), AX
    SARQ    $4, AX
    SUBQ    BX, AX
    RET
shop/div.By16 STEXT nosplit size=19 args=0x8 locals=0x0 funcid=0x0 align=0x0
    TEXT    shop/div.By16(SB), NOSPLIT|NOFRAME|ABIInternal, $0-8
    MOVQ    AX, CX
    SARQ    $63, AX
    SHRQ    $60, AX
    ADDQ    CX, AX
    SARQ    $4, AX
    RET
shop/div.Mod10 STEXT nosplit size=50 args=0x8 locals=0x0 funcid=0x0 align=0x0
    TEXT    shop/div.Mod10(SB), NOSPLIT|NOFRAME|ABIInternal, $0-8
    MOVQ    AX, CX
    SARQ    $63, AX
    MOVQ    AX, DX
    MOVQ    $-3689348814741910323, AX
    MOVQ    DX, BX
    IMULQ   CX
    ADDQ    CX, DX
    SARQ    $3, DX
    SUBQ    BX, DX
    LEAQ    (DX)(DX*4), DX
    SHLQ    $1, DX
    SUBQ    DX, CX
    MOVQ    CX, AX
    RET
shop/div.UBy16 STEXT nosplit size=5 args=0x8 locals=0x0 funcid=0x0 align=0x0
    TEXT    shop/div.UBy16(SB), NOSPLIT|NOFRAME|ABIInternal, $0-8
    SHRQ    $4, AX
    RET
  • x/20: magic multiply + shift, no IDIV.
  • x/16 (signed): a shift, plus a fix-up (SHRQ $60 adds 15 for negative numbers so the result rounds toward zero like Go requires).
  • x%10: compute x/10 with a magic multiply, then x - (q*5)*2 using LEAQ and SHLQ instead of a multiply.
  • unsigned x/16: a single SHRQ $4. Unsigned types can make arithmetic cheaper when the value can never be negative.
Solution 5: bounds checks and the prove pass

A bounds check is the code that makes s[i] panic with "index out of range" when i is not in 0..len(s)-1. The prove pass removes checks it can prove are always true.

ssaloop/sum/sum.go:

package sum

func Sum(prices []int) int {
    total := 0
    for i := 0; i < len(prices); i++ {
        total += prices[i] // bounds check: is i < len(prices)?
    }
    return total
}

func Third(prices []int) int {
    return prices[2] // needs a bounds check: len could be < 3
}

Output:

$ go build -gcflags=-d=ssa/check_bce/debug=1 ./sum
# shop/sum
sum/sum.go:12:15: Found IsInBounds
$ GOSSAFUNC=Sum go build ./sum
# shop/sum
dumped SSA for Sum,1 to ./ssa.html

check_bce reports bounds checks that remain: only line 12 (prices[2]). In Sum the loop condition i < len(prices) proves the index is in range, so in ssa.html the IsInBounds value is present in the early passes and gone after prove.

Common mistakes (and the real messages)

Mistake Real message / symptom Why Fix
recursion with no base case runtime: goroutine stack exceeds 1000000000-byte limit / fatal error: stack overflow stacks grow, but only to 1 GB a base case, or a loop
defer mu.Unlock() inside a loop fatal error: all goroutines are asleep - deadlock! defer runs at function end, not iteration end one function per iteration (or unlock explicitly)
returning a nil *MyError as error err != nil is true the interface's type/itab word is set return nil
keeping uintptr(unsafe.Pointer(&x)) for later a stale address after the stack moves stacks are copied; a uintptr is just a number, not updated keep a real pointer
reading runtime structs with unsafe garbage after a Go upgrade internals change in any release learning only
guessing what's slow optimising the wrong thing the compiler already inlines, devirtualizes, replaces division benchmark, -gcflags=-m, -gcflags=-S, pprof (episode 57)

Practice

  1. Why can 100,000 goroutines fit in memory when 100,000 OS threads can't?
  2. A goroutine holds p := &x (a real pointer to its own local x) and its stack grows. Is p still valid?
  3. How many machine words is a []string? A map[string][]int? A chan int? An error?
  4. var e *MyErr; var err error = e — what are err's two words, and is err == nil?
  5. Which of these defers is open-coded? (a) one defer at the top of a function; (b) a defer inside for; (c) 9 defer statements in one function.
  6. Why does x/20 not produce a divide instruction?
  7. What does CMPQ SP, 0x10(R14) at the start of a function do?
Solutions

1. A goroutine starts with a 2 KB stack that grows only if needed (195 MB for 100,000 in our run); a thread reserves its full stack (8 MB here, 781 GB for 100,000).

2. Yes. When the runtime copies a stack it adjusts every real pointer into it. Only a uintptr copy of the address goes stale.

3. []string: 3 words (24 bytes: pointer, length, capacity). map[string][]int: 1 word (a pointer). chan int: 1 word. error: 2 words (an interface: itab + data).

4. itab word = the itab for (error, *MyErr), data word = nil. err == nil is false.

5. Only (a). (b) is in a loop and (c) has more than 8 defers, so both use defer records.

6. Division is slow on CPUs; dividing by a constant can be replaced by a multiply with a "magic" constant and a shift, which gives the same result much faster.

7. It's the stack check: it compares the stack pointer with stackguard0, which is 16 bytes into the current goroutine (R14). If there isn't room, the following JBE jumps to runtime.morestack, which grows the stack.

Quick quiz

type Shape interface{ Area() int }

type Sq struct{ s int }

func (q *Sq) Area() int { return q.s * q.s }

func find() Shape {
    var q *Sq // nil
    return q
}

func main() {
    fmt.Println(find() == nil)
}

What does it print? (a) true (b) false (c) a compile error (d) a nil pointer panic

Answer

(b) false. find returns an interface whose itab word says *Sq and whose data word is nil. One word is set, so the interface is not nil.

Interview questions

  1. How big is a goroutine's stack, and what happens when it runs out? Starts at 2 KB. The function prologue compares SP with stackguard0; if there's no room, morestack allocates a stack twice the size, copies the frames and adjusts pointers. The GC shrinks stacks using under a quarter. The maximum is 1 GB on 64-bit, after which the program dies with fatal error: stack overflow.
  2. What is an interface value in memory? Two words: for any, a type pointer and a data pointer (eface); for an interface with methods, an itab pointer and a data pointer (iface). The itab holds the interface type, the concrete type, a hash and the method addresses.
  3. Why is an interface holding a nil pointer not nil? Because its type/itab word is set; an interface is nil only when both words are nil.
  4. What does an interface method call cost? A load of the itab, a load of the method address, and an indirect call; a few nanoseconds. The bigger cost is that it blocks inlining, unless the compiler devirtualizes it.
  5. How is a channel implemented? As an hchan: a lock, a ring buffer (buf, qcount, dataqsiz, sendx, recvx), a closed flag, and queues of waiting senders and receivers. A send hands the value straight to a waiting receiver if there is one.
  6. How are Go maps implemented since 1.24? Swiss tables: groups of 8 slots with a control word of 7-bit hash fragments (H2) checked together; H1 chooses the group; a directory of tables that grow independently.
  7. Why is defer cheap now? Open-coded defers (since Go 1.14): the compiler inlines the deferred calls at each return and tracks them with a bitmask. It falls back to defer records for defers in loops, more than 8 defers, or many returns.
  8. Describe the Go compiler's phases. Parse → type-check → IR (noding) → middle end (inlining, devirtualization, escape analysis, dead code) → walk (order, desugaring, runtime calls) → SSA (generic passes) → lowering and machine-specific passes, register allocation → machine code → link.
  9. How do you see what the compiler did? -gcflags=-m (inlining, escape, devirtualization), -gcflags=-S (assembly), GOSSAFUNC=Name (SSA passes), go tool objdump (the final binary), -d=ssa/check_bce/debug=1 (bounds checks).

Glossary

Term Meaning Example
runtime the code the Go toolchain links into every program: scheduler, GC, stacks, maps, channels it runs your goroutines
runtime package the standard-library package for asking the runtime questions runtime.NumGoroutine()
GOMAXPROCS how many OS threads may run Go code at the same time runtime.GOMAXPROCS(0) → 2
MemStats a struct of memory numbers filled by runtime.ReadMemStats ms.NumGC, ms.StackInuse
OS thread a unit of execution scheduled by the operating system each has an 8 MB stack here
stack memory a function uses for its local variables and return address x := 42 in main
frame one function call's part of the stack each depth(n) call adds one
stack pointer (SP) CPU register holding the address of the top frame CMPQ SP, ...
stackMin the starting goroutine stack size, 2048 bytes 100,000 goroutines → 195 MB
prologue a function's first instructions, which include the stack check CMPQ SP, 0x10(R14)
stackguard0 the line in a goroutine's stack below which it must grow 16 bytes into g
morestack / newstack / copystack runtime functions that allocate a bigger stack and copy frames into it seen in the overflow trace
stack growth replacing a full stack with one twice the size, copying frames and fixing pointers x moved but kept 42
stack shrinking the GC halving a stack that uses under a quarter of its size after a deep call returns
stack overflow exceeding the maximum stack size (1 GB on 64-bit) fatal error: stack overflow
fatal error a runtime failure that recover can't catch; the program exits deadlock, stack overflow
uintptr an integer type big enough to hold an address; not tracked as a pointer uintptr(unsafe.Pointer(&x))
machine word the CPU's natural unit of data, 8 bytes on 64-bit an interface is 2 words
interface value a pair of words: what type is stored, and where the value is var p Payer
eface the runtime layout of an empty interface (any): _type + data var a any = 500
iface the runtime layout of a non-empty interface: tab (itab) + data var q Payer = u
itab per (interface, type) table: interface type, concrete type, hash, method addresses (Payer, *UPI)
nil interface an interface with both words empty var p Payer
dynamic dispatch choosing the function to call at run time from the itab q.Pay(5)
indirect call a call through an address loaded from memory CALL via Fun[0]
inlining copying a function's body into its caller instead of calling it inlining call to GST.Tax
devirtualization turning an interface call into a direct call when the type is provable devirtualizing t.Tax to GST
benchmark / ns/op a test that times code; nanoseconds per operation BenchmarkDirect-2 ... 1.220 ns/op
header the fixed-size part of a value that points to its data a slice header is 24 bytes
hchan the runtime struct behind a channel make(chan string, 3)
ring buffer a fixed array used in a circle: after the last slot comes the first sendx wraps to 0
sendx / recvx the next slot to send into / receive from sendx=1 after wrapping
sendq / recvq queues of goroutines waiting to send / receive a full channel parks senders
hash / hash table a number computed from a key, used to choose where to store it; a table built on it map[string]int
Swiss table the hash-table design behind Go maps since 1.24: groups of 8 slots plus a control word Abseil's design
H1 / H2 the upper 57 bits (choose the group) and lower 7 bits (stored in the control byte) of a key's hash compared 8 at a time
control word 8 bytes per group, one per slot: empty, deleted, or used + H2
directory the array of tables in a big map, chosen by the upper hash bits each table grows alone
defer a call scheduled to run when the surrounding function returns defer mu.Unlock()
deadlock every goroutine waiting for something that can never happen the second Lock in the loop
open-coded defer a defer the compiler inlines at each return, tracked by deferBits ./shop.go:11:5: open-coded defer
deferBits one byte, one bit per defer statement reached at most 8 defers
heap-allocated defer / defer record a record on the goroutine's defer list, run by deferreturn ./shop.go:19:9: heap-allocated defer
gc (compiler) the Go compiler, cmd/compile; not the garbage collector go build runs it
token the smallest meaningful piece of source text func, Add, (
syntax tree a tree representing the structure of the source a return node with a + child
type-check giving every expression a type and reporting type errors mismatched types int and string
front / middle / back end parse and type-check / IR optimisations / SSA and machine code
IR intermediate representation: the compiler's own tree between source and SSA inlining works on IR
escape analysis deciding whether a value can stay on the stack or must go to the heap GST{} does not escape
walk the pass that orders evaluation and replaces map/channel operations with runtime calls m[k] → a map function call
SSA static single assignment: every value named and assigned exactly once v9 = Div64 v6 v8
lowering rewriting generic SSA into this CPU's instructions Div64 → HMULQ + shift
register allocation (regalloc) choosing which CPU register holds each value AX, CX, DX
linker joins compiled packages and the runtime into one binary the last step of go build
-gcflags flags passed to the compiler by go build/go test -gcflags=-m, -gcflags=-S
GOSSAFUNC environment variable that dumps one function's SSA passes to ssa.html GOSSAFUNC=Add go build
assembly human-readable machine instructions ADDQ CX, DX
disassemble / go tool objdump turn machine code in a binary back into assembly -s main.main
TEXT, FUNCDATA, PCDATA start of a function; tables for the GC and stack maps TEXT shop/tax.Add(SB)
magic-number division replacing division by a constant with a multiply and shift 0xCCCC...CD for /20
bounds check / prove pass the check that makes s[i] panic when out of range; the pass that removes provable ones Found IsInBounds
R14 (amd64) the register holding the current goroutine in Go's internal ABI CMPQ SP, 0x10(R14)
Plan 9 assembly the assembler style Go uses, from Bell Labs' Plan 9 OS MOVQ $0, CX
pseudo-register a name managed by the toolchain, not a real register: SB, FP, SP, PC foo(SB)
semi-abstract instruction set instructions that the toolchain may map to different real CPU instructions MOV might become a clear
GC shape stenciling / dictionary how Go compiles generics: one copy per memory shape plus a hidden type description TaxAll[GST]

Summary

  • The runtime is linked into every Go program; the runtime package lets you read its dials.
  • Goroutine stacks start at 2 KB, grow by copying to twice the size (the prologue's stack check calls morestack), shrink when under a quarter used, and stop at 1 GB.
  • An interface is two words. eface = type + data; iface = itab + data. It is nil only when both are empty.
  • An interface call goes through the itab (dynamic dispatch); its real cost is lost inlining, and devirtualization often removes it.
  • Maps, channels and funcs are one pointer. A channel is an hchan with a ring buffer and wait queues; a map is a Swiss table.
  • defer runs at function return. Open-coded defers are almost free; a defer in a loop is a record per iteration (and in our cash-box case, a deadlock).
  • The compiler: parse, type-check, IR passes, walk, SSA, lowering, machine code. Read it with -gcflags=-m, -gcflags=-S, GOSSAFUNC and go tool objdump.
  • Go's Plan 9-style assembly flows left to right and uses pseudo-registers SB, FP, SP and PC.

Next episode: Interview prep: language fundamentals.