Compiler on Opensource internals

range over func: The Compiler Turns a Loop Into a Coroutine

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: for x := range f never becomes a loop in the machine code. A compiler pass rewrites it into f(func(x T) bool { ... }) – the iterator calls your body, and your body returns true to keep going. There is no coroutine in that path at all. The coroutine shows up in iter.Pull, which inverts the direction of control and needs a way to suspend a caller in the middle of a function. In this tree that coroutine is a goroutine, switched with gogo rather than by copying stacks.

Go 1.23 added range over a function. It reads like a loop, but it is nothing of the kind, and the difference shows up in profiles, in stack traces, and in what a defer inside the body actually does.

This is a walk through how it works, based on reading the Go 1.28 development tree: the compiler pass in src/cmd/compile/internal/rangefunc/rewrite.go, the runtime coroutine machinery in src/runtime/coro.go, and the standard library in src/iter/iter.go.

The shape of the feature

An iterator is a function that takes a yield callback:

 go
 
 
// src/iter/iter.go:219
// Seq is an iterator over sequences of individual values.
// When called as seq(yield), seq calls yield(v) for each value v in the sequence,
// stopping early if yield returns false.
// See the [iter] package documentation for more details.
type Seq[V any] func(yield func(V) bool)

// Seq2 is an iterator over sequences of pairs of values, most commonly key-value pairs.
// When called as seq(yield), seq calls yield(k, v) for each pair (k, v) in the sequence,
// stopping early if yield returns false.
// See the [iter] package documentation for more details.
type Seq2[K, V any] func(yield func(K, V) bool)

That is the whole interface. The iterator pushes values at the callback; the callback returns false to say “stop”. The iter package documents the contract from the iterator’s side:

Yield panics if called after it returns false.

So an iterator is not allowed to keep calling yield after the loop body has said stop. That is a promise the compiler cannot check statically, so it checks at runtime.

The rewrite pass

The whole feature is implemented by a front-end pass that runs before the compiler’s normal IR generation. Its package comment is the best description of the design in the tree:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:10
// # Theory of Operation
//
// The basic idea is to rewrite
//
// 	for x := range f {
// 		...
// 	}
//
// into
//
// 	f(func(x T) bool {
// 		...
// 	})
//
// But it's not usually that easy.

The “not usually that easy” is the rest of the file, and it is worth reading because every piece of it corresponds to a rule you already know from Go syntax: break becomes return false, continue becomes return true, a return from inside the body has to unwind through the iterator, and a labelled break out of two nested loops needs a numeric code to say which loop it meant.

The generated code uses three hidden variables, all named with a # prefix so they show up as internal in a debugger:

#yield1, #yield2, … – the generated body closures.
#next – an integer code saying what to do when the iterator returns.
#state1, #state2, … – the iterator-misbehaviour state machine.

A plain loop body becomes a closure that returns true at the end:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:176
// 	for x := range f {
// 		...
// 		if ... { break }
// 		...
// 	}
//
// becomes
//
// 		{
// 			var #state1 = abi.RF_READY
// 			f(func(x T1) bool {
// 				if #state1 != abi.RF_READY { #state1 = abi.RF_PANIC; runtime.panicrangestate(#state1) }
// 				#state1 = abi.RF_PANIC
// 				...
// 				if ... { #state1 = abi.RF_DONE ; return false }
// 				...
// 				#state1 = abi.RF_READY
// 				return true
// 			})
// 	 if #state1 == abi.RF_PANIC {
// 	 	// the code for the loop body did not return normally
// 	 	panic(runtime.panicrangestate(abi.RF_MISSING_PANIC))
// 	 }
// 			#state1 = abi.RF_EXHAUSTED
// 		}

Note the shape of the result: the loop is gone. What is left is a call to the iterator with a closure, followed by some checks.

The compiler builds exactly that. endLoop constructs the block, the closure declaration, the call, and the post-checks:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:1127
	// Give the closure generated for the body a name, to help the debugger connect it to its frame, if active.
	r.bodyClosureCount++
	clo := r.bodyFunc(nfor.Body.List, syntax.UnpackListExpr(rclause.Lhs), rclause.Def, ftyp, start, end)
	cloDecl, cloVar := r.declSingleVar(fmt.Sprintf("#yield%d", r.bodyClosureCount), clo.GetTypeInfo().Type, clo)
	setPos(cloDecl, start)

	// Build X(bodyFunc)
	call := &syntax.ExprStmt{
		X: &syntax.CallExpr{
			Fun: rclause.X,
			ArgList: []syntax.Expr{
				r.useObj(cloVar),
			},
		},
	}
	setPos(call, start)

and the closure itself is a plain function literal whose last statement is return true:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:1298
	// Original loop body (already rewritten by editStmt during inspect).
	bodyFunc.Body.List = append(bodyFunc.Body.List, body...)

	// end of loop body, set state to abi.RF_READY and return true to continue iteration
	if r.checkFuncMisuse() {
		bodyFunc.Body.List = append(bodyFunc.Body.List, r.setState(abi.RF_READY, end))
	}
	ret := &syntax.ReturnStmt{Results: r.useObj(r.true)}
	ret.SetPos(end)
	bodyFunc.Body.List = append(bodyFunc.Body.List, ret)

	return bodyFunc
}

So for x := range f compiles to a call, and your loop body compiles to a closure. That is why the loop body shows up in stack traces as a separate frame with a name like f.func1, and why runtime.Caller inside the body reports the iterator’s frame, not the caller’s.

Checking that the iterator behaves

The #stateN variables exist to catch an iterator that calls yield at the wrong time. The states are shared between the compiler and the runtime, and they live in internal/abi:

 go
 
 
// src/internal/abi/rangefuncconsts.go:7
type RF_State int

// These constants are shared between the compiler, which uses them for state functions
// and panic indicators, and the runtime, which turns them into more meaningful strings
// For best code generation, RF_DONE and RF_READY should be 0 and 1.
const (
	RF_DONE = RF_State(iota) // body of loop has exited in a non-panic way
	RF_READY // body of loop has not exited yet, is not running -- this is not a panic index
	RF_PANIC // body of loop is either currently running, or has panicked
	RF_EXHAUSTED // iterator function return, i.e., sequence is "exhausted"
	RF_MISSING_PANIC = 4 // body of loop panicked but iterator function defer-recovered it away
)

The runtime side is a single function that panics with the right message:

 go
 
 
// src/runtime/panic.go:371
var rangeDoneError = error(errorString("range function continued iteration after function for loop body returned false"))
var rangePanicError = error(errorString("range function continued iteration after loop body panic"))
var rangeExhaustedError = error(errorString("range function continued iteration after whole loop exit"))
var rangeMissingPanicError = error(errorString("range function recovered a loop body panic and did not resume panicking"))

//go:noinline
func panicrangestate(state int) {
	switch abi.RF_State(state) {
	case abi.RF_DONE:
		panic(rangeDoneError)
	case abi.RF_PANIC:
		panic(rangePanicError)
	case abi.RF_EXHAUSTED:
		panic(rangeExhaustedError)
	case abi.RF_MISSING_PANIC:
		panic(rangeMissingPanicError)
	}
	throw("unexpected state passed to panicrangestate")
}

RF_MISSING_PANIC is the interesting one. If the loop body panics and the iterator swallows the panic with its own recover, the body never gets to return normally and the loop never sees RF_PANIC cleared. The compiler checks for that after the iterator returns and reports it, rather than letting a panic vanish.

`defer` inside the loop body

A defer in a range-over-func body is a problem, because the body is a closure: the deferred call would run when the closure returns, i.e. at the end of each iteration, rather than at the end of the enclosing function.

The rewrite pass solves this with a token. The package comment spells out the protocol:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:480
// # Defers
//
// The last wrinkle is handling defer statements. If we have
//
// 	for range f {
// 		defer print("A")
// 	}
//
// we cannot rewrite that into
//
// 	f(func() {
// 		defer print("A")
// 	})
//
// because the deferred code will run at the end of the iteration, not
// the end of the containing function. To fix that, the runtime provides
// a special hook that lets us obtain a defer "token" representing the
// outer function and then use it in a later defer to attach the deferred
// code to that outer function.
//
// Normally,
//
// 	defer print("A")
//
// compiles to
//
// 	runtime.deferproc(func() { print("A") })
//
// This changes in a range-over-func. For example:
//
// 	for range f {
// 		defer print("A")
// 	}
//
// compiles to
//
// 	var #defers = runtime.deferrangefunc()
// 	f(func() {
// 		runtime.deferprocat(func() { print("A") }, #defers)
// 	})

The token is an any holding a pointer to an atomic list head. The runtime side keeps two lists: the goroutine’s ordinary defer chain, and a separate atomic chain for the body closure’s defers, so that the body can push onto it from a different goroutine without disturbing the main chain:

 go
 
 
// src/runtime/panic.go:405
// The g._defer list is now a linked list of deferred calls,
// but an atomic list hanging off:
//
//		g._defer => d4 -> d3 -> drangefunc -> d2 -> d1 -> nil
//	 | .head
//	 |
//	 +--> dY -> dX -> nil
//
// with each -> indicating a d.link pointer, and where drangefunc
// has the d.rangefunc = true bit set.
// Note that the function being ranged over may have added
// its own defers (d4 and d3), so drangefunc need not be at the
// top of the list when deferprocat is used. This is why we pass
// the atomic head explicitly.

When the runtime reaches the drangefunc marker during unwinding, it calls deferconvert, which atomically steals the extra list and splices it into the main chain in the right order:

 go
 
 
// src/runtime/panic.go:505
// deferconvert converts the rangefunc defer list of d0 into an ordinary list
// following d0.
// See the doc comment for deferrangefunc for details.
func deferconvert(d0 *_defer) {
	head := d0.head
	if raceenabled {
		racereadpc(unsafe.Pointer(head), sys.GetCallerPC(), abi.FuncPCABIInternal(deferconvert))
	}
	tail := d0.link
	d0.rangefunc = false

	var d *_defer
	for {
		d = head.Load()
		if head.CompareAndSwap(d, badDefer()) {
			break
		}
	}
	if d == nil {
		return
	}
	for d1 := d; ; d1 = d1.link {
		d1.sp = d0.sp
		d1.pc = d0.pc
		if d1.link == nil {
			d1.link = tail
			break
		}
	}
	d0.link = d
	return
}

d1.sp = d0.sp and d1.pc = d0.pc are what make the defers belong to the outer function’s frame: the runtime decides which deferred calls run in which frame by comparing stack pointers.

There is a catch, and the runtime enforces it: the token is poisoned once the loop is over, so a body that calls yield after the iterator returned and then defers something gets a hard error rather than silent corruption:

 go
 
 
// src/runtime/panic.go:480
// badDefer returns a fixed bad defer pointer for poisoning an atomic defer list head.
func badDefer() *_defer {
	return (*_defer)(unsafe.Pointer(uintptr(1)))
}

`recover` inside the loop body

recover has the same problem for the same reason: it decides whether to recover by looking at the frame it was called from, and the body’s frame is not the frame of the function that wrote the loop.

The rewrite pass handles it with a second token. The compiler rewrites recover() in a body into runtime.gorecoverat(#recover), where #recover was computed once, on entry to the enclosing function:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:544
// Whether such a recover takes effect depends only on the frame the loop is
// in, so the runtime can decide that part on entry to the function, while
// that frame is the current one, and hand back the panic the body would
// recover:
//
// 	var #recover = runtime.recoverrangefunc()
// 	f(func() {
// 		runtime.gorecoverat(#recover)
// 	})
//
// The token is the panic itself, or nil if a recover in the body would not
// take effect. Unlike the frame it stands for, it does not move when the
// stack grows, so the body can hold onto it. gorecoverat recovers that panic
// if it is still the one being processed.

And the runtime side:

 go
 
 
// src/runtime/panic.go:1094
// recoverrangefunc is called on entry to a range-over-func loop whose body
// calls recover. The body runs in a frame of its own, called from the iterator,
// so a recover there cannot tell that it is, in the source, a call made directly
// in this function. This does the part of that decision that depends on the frame,
// while the frame is the current one, and returns the panic the body may recover,
// or nil if a recover in the body does not take effect.
//
// See also ../cmd/compile/internal/rangefunc/rewrite.go.
func recoverrangefunc() any {
	p := recoverablePanic(3) // skip systemstack_switch, recoverablePanic, recoverrangefunc
	if p == nil {
		// Either nothing is panicking, or this function is not the one the
		// panic deferred, so nothing in it can recover.
		return nil
	}
	return p
}

Note the recover() in the body is not the ordinary recover. The compiler swaps it out at the syntax level:

 go
 
 
// src/cmd/compile/internal/rangefunc/rewrite.go:835
	// The call is in the body of a range-over-func loop, which runs in a
	// frame of its own. Hand the runtime the token for the frame of the
	// function the loop is written in, so that it can decide whether to
	// recover as if the call were made where it is in the source.
	x.Fun = runtimeSym(r.info, "gorecoverat")
	setPos(x.Fun, x.Pos())
	x.ArgList = []syntax.Expr{r.recoverToken()}
	setPos(x.ArgList[0], x.Pos())

Where the coroutine actually is

So far, nothing needs a coroutine: the iterator calls the body, the body returns a bool, control flows back to the iterator. That is a plain call, and it is cheap.

The coroutine appears when you want to invert the direction of control: pull values out of a push iterator one at a time. That is iter.Pull, and it is the only user of the runtime’s coroutine machinery.

 go
 
 
// src/iter/iter.go:239
// Pull converts the “push-style” iterator sequence seq
// into a “pull-style” iterator accessed by the two functions
// next and stop.
//
// Next returns the next value in the sequence
// and a boolean indicating whether the value is valid.
// When the sequence is over, next returns the zero V and false.
// It is valid to call next after reaching the end of the sequence
// or after calling stop. These calls will continue
// to return the zero V and false.
//
// Stop ends the iteration. It must be called when the caller is
// no longer interested in next values and next has not yet
// signaled that the sequence is over (with a false boolean return).
// It is valid to call stop multiple times and when next has
// already returned false. Typically, callers should “defer stop()”.
//
// It is an error to call next or stop from multiple goroutines
// simultaneously.
//
// If the iterator panics during a call to next (or stop),
// then next (or stop) itself panics with the same value.
func Pull[V any](seq Seq[V]) (next func() (V, bool), stop func()) {

The trick is that next has to return a value from the middle of an arbitrary iterator function, and then next has to be callable again to resume it. That requires suspending the iterator’s stack mid-function and resuming it later. In this tree, the runtime does it with a goroutine.

The coro type is deliberately tiny:

 go
 
 
// src/runtime/coro.go:12
// A coro represents extra concurrency without extra parallelism,
// as would be needed for a coroutine implementation.
// The coro does not represent a specific coroutine, only the ability
// to do coroutine-style control transfers.
// It can be thought of as like a special channel that always has
// a goroutine blocked on it. If another goroutine calls coroswitch(c),
// the caller becomes the goroutine blocked in c, and the goroutine
// formerly blocked in c starts running.
// These switches continue until a call to coroexit(c),
// which ends the use of the coro by releasing the blocked
// goroutine in c and exiting the current goroutine.
//
// Coros are heap allocated and garbage collected, so that user code
// can hold a pointer to a coro without causing potential dangling
// pointer errors.
type coro struct {
	gp guintptr
	f func(*coro)

	// State for validating thread-lock interactions.
	mp *m
	lockedExt uint32 // mp's external LockOSThread counter at coro creation time.
	lockedInt uint32 // mp's internal lockOSThread counter at coro creation time.
}

“Extra concurrency without extra parallelism” is the key phrase. A coro is a goroutine, but the switch does not go through the scheduler.

Creating one spawns a goroutine blocked in corostart:

 go
 
 
// src/runtime/coro.go:39
// newcoro creates a new coro containing a
// goroutine blocked waiting to run f
// and returns that coro.
func newcoro(f func(*coro)) *coro {
	c := new(coro)
	c.f = f
	pc := sys.GetCallerPC()
	gp := getg()
	systemstack(func() {
		mp := gp.m
		start := corostart
		startfv := *(**funcval)(unsafe.Pointer(&start))
		gp = newproc1(startfv, gp, pc, true, waitReasonCoroutine)

		// Scribble down locked thread state if needed and/or donate
		// thread-lock state to the new goroutine.
		if mp.lockedExt+mp.lockedInt != 0 {
			c.mp = mp
			c.lockedExt = mp.lockedExt
			c.lockedInt = mp.lockedInt
		}
	})
	gp.coroarg = c
	c.gp.set(gp)
	return c
}

Switching is where the “no scheduler” promise is kept:

 go
 
 
// src/runtime/coro.go:97
// coroswitch_m is the implementation of coroswitch
// that runs on the m stack.
//
// Note: Coroutine switches are expected to happen at
// an order of magnitude (or more) higher frequency
// than regular goroutine switches, so this path is heavily
// optimized to remove unnecessary work.
// The fast path here is three CAS: the one at the top on gp.atomicstatus,
// the one in the middle to choose the next g,
// and the one at the bottom on gnext.atomicstatus.
// It is important not to add more atomic operations or other
// expensive operations to the fast path.
func coroswitch_m(gp *g) {

and the final hand-off is a gogo, which is the runtime’s longjmp:

 go
 
 
// src/runtime/coro.go:258
	// Switch to gnext. Does not return.
	gogo(&gnext.sched)
}

gogo is assembly that restores a saved stack pointer, frame pointer and program counter, and jumps:

 asm
 
 
// src/runtime/asm_amd64.s:397
TEXT gogo<>(SB), NOSPLIT, $0
	get_tls(CX)
	MOVQ	DX, g(CX)
	MOVQ	DX, R14		// set the g register
	MOVQ	gobuf_sp(BX), SP	// restore SP
	MOVQ	gobuf_ctxt(BX), DX
	MOVQ	gobuf_bp(BX), BP
	MOVQ	$0, gobuf_sp(BX)	// clear to help garbage collector
	MOVQ	$0, gobuf_ctxt(BX)
	MOVQ	$0, gobuf_bp(BX)
	MOVQ	gobuf_pc(BX), BX
	JMP	BX

So the coroutine’s “stack” is an ordinary goroutine stack, allocated from the runtime’s stack pool with a minimum of 2 KiB:

 go
 
 
// src/runtime/stack.go:77
	// The minimum size of stack used by Go code
	stackMin = 2048

and the coroutine’s state lives in the goroutine’s sched field, a gobuf:

 go
 
 
// src/runtime/runtime2.go:303
type gobuf struct {
	// ctxt is unusual with respect to GC: it may be a
	// heap-allocated funcval, so GC needs to track it, but it
	// needs to be set and cleared from assembly, where it's
	// difficult to have write barriers. However, ctxt is really a
	// saved, live register, and we only ever exchange it between
	// the real register and the gobuf. Hence, we treat it as a
	// root during stack scanning, which means assembly that saves
	// and restores it doesn't need write barriers. It's still
	// typed as a pointer so that any other writes from Go get
	// write barriers.
	sp uintptr
	pc uintptr
	g guintptr
	ctxt unsafe.Pointer
	lr uintptr
	bp uintptr // for framepointer-enabled architectures
}

iter.Pull ties it together. The yield closure the iterator calls switches back to the caller, and the caller’s next switches forward:

 go
 
 
// src/iter/iter.go:271
	c := newcoro(func(c *coro) {
		race.Acquire(unsafe.Pointer(&pull.racer))
		if pull.done {
			race.Release(unsafe.Pointer(&pull.racer))
			return
		}
		yield := func(v1 V) bool {
			if pull.done {
				return false
			}
			if !pull.yieldNext {
				panic("iter.Pull: yield called again before next")
			}
			pull.yieldNext = false
			pull.v, pull.ok = v1, true
			race.Release(unsafe.Pointer(&pull.racer))
			coroswitch(c)
			race.Acquire(unsafe.Pointer(&pull.racer))
			return !pull.done
		}

The pull struct is shared between the two goroutines, and the racer field is how the race detector is told that the handoff is happening.

Trade-offs

What the rewrite buys: range over a function costs one indirect call per element, with no allocation, no scheduler involvement, and no state machine in the runtime. The generated closure is a normal Go function that the compiler can inline and optimise like any other.

What it costs: the loop body is no longer a loop body. It is a closure, so it cannot break out of an enclosing non-range loop without the #next code machinery, it cannot return values without assigning to named results first, and it shows up in stack traces as its own frame.

What the coroutine buys: iter.Pull can turn any push iterator into a pull iterator, including ones written in terms of yield inside a deeply nested function. The suspended iterator keeps its whole stack alive, so Pull works with arbitrary iterators.

What it costs: a goroutine per Pull, with at least a 2 KiB stack, plus the coro object, plus the pull struct. The switch is a hand-rolled gogo rather than a scheduler round trip, so it skips the scheduler’s work-stealing and preemption machinery – which is exactly why the runtime comments warn against adding work to that path.

Caveats

A range-over-func body is a closure, not a loop body. break and continue work, but goto out of it is rewritten into a numeric protocol, and return with values has to write to named results first.

recover inside the body is a different recover. The compiler rewrites it to runtime.gorecoverat, with a token captured when the loop was entered.

A defer inside the body runs at the end of the enclosing function, not at the end of the iteration. That is deliberate and it surprises people.

The body frame is visible in stack traces, and runtime.Caller from inside it reports the iterator’s caller, not your caller.

An iterator that keeps calling yield after the body returns false is a runtime panic, not a hang: panicrangestate turns the state mismatch into range function continued iteration after function for loop body returned false.

An iterator that swallows a panic from the body is reported, via RF_MISSING_PANIC. A recover in the iterator that hides a body panic is almost always a bug, and the compiler makes it loud.

iter.Pull is not free. Each call allocates a goroutine stack, a coro, and the shared state struct. If you are pulling thousands of values out of a sequence, pull the whole sequence into a slice instead.

iter.Pull is not safe for concurrent use. The documentation says it plainly: “It is an error to call next or stop from multiple goroutines simultaneously.”

The iterator must not retain the yield function and call it later. The runtime poisons the token when the loop ends, so a late defer in the body throws rather than corrupting memory.

Wrapping up

The one thing to remember: for x := range f becomes f(func(x T) bool { ... }). Your loop body is a closure that the iterator calls, and it returns true to continue. There is no loop in the machine code and no coroutine in the common path.

The part people get wrong: the coroutine is not part of range over func. It is part of iter.Pull, which inverts control and therefore needs to suspend a function mid-flight. In this tree that suspension is a goroutine plus a gogo, so pulling values costs a goroutine stack.

What to go do about it: if you write iterators, read the “Theory of Operation” comment at the top of src/cmd/compile/internal/rangefunc/rewrite.go – it is the closest thing to a specification of what the compiler will do with your code. And if you are pulling values one at a time out of a hot path, measure it: iter.Pull is convenient, not free.

How Go Deletes Your Bounds Checks: The Facts Table That Proves i < len(s)

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Every s[i] in Go compiles to a compare-and-panic. Then the compiler tries to prove the compare is always true and deletes it. The proof lives in cmd/compile/internal/ssacompile/prove.go, and it works by tracking relations between SSA values in separate domains — signed, unsigned, pointer, boolean — because the same bit pattern means different things in each. When the facts table learns 0 <= i < len(s) on one branch, it can answer the question “is i in bounds?” with a constant true, and the branch disappears.

Every index operation in Go is a potential panic. That is a language guarantee, and it is enforced by the compiler generating a comparison and a branch to a panic call. The interesting question is what happens after that.

Go has always deleted bounds checks it can prove redundant. It is one of the oldest and most valuable optimisations in the compiler, and it is also one of the least known. The mechanism is a static analysis pass called prove, and its data structure is a small, sound, deliberately incomplete theorem prover.

What a bounds check looks like

In SSA, an index operation becomes an IsInBounds value. The architecture rules lower it to a single unsigned compare:

text

// src/cmd/compile/internal/ssa/_gen/AMD64.rules:463
(IsInBounds idx len) => (SETB (CMPQ idx len))

One CMPQ, one SETB. Cheap. But not free — it is a branch that the CPU cannot predict, sitting in the middle of what is otherwise a tight loop.

The generic rules can also fold it away at the lowering level, before the prove pass ever runs:

text

// src/cmd/compile/internal/ssa/_gen/generic.rules:265
(IsInBounds (ZeroExt8to32 _) (Const32 [c])) && (1 << 8) <= c => (ConstBool [true])
(IsInBounds (ZeroExt16to32 _) (Const32 [c])) && (1 << 16) <= c => (ConstBool [true])
(IsInBounds x x) => (ConstBool [false])

The first two are trivially true: a byte cannot index past 256 elements. The third is a curiosity — s[s] is always out of bounds, because the length is strictly less than the length.

But these are special cases. The general case needs real reasoning.

Domains: the key insight

Here is the problem that makes naive range analysis wrong in Go.

 go
 
 
func f(x int) {
 var a [4]int
 _ = a[x] // must panic for x >= 4 or x < 0
}

If you only tracked “x is between 0 and 3”, you would prove the check redundant — and be wrong, because x could be -1.

The classic fix is to track signedness. Go’s prove pass goes further: it maintains a set of domains per value, and relations are only ever transferred within a domain.

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:85
// domain represents the domain of a variable pair in which a set
// of relations is known. For example, relations learned for unsigned
// pairs cannot be transferred to signed pairs because the same bit
// representation can mean something else.
type domain uint

const (
	signed domain = 1 << iota
	unsigned
	pointer
	boolean
)

And the relation itself is a three-bit mask:

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:65
type relation uint

const (
	lt relation = 1 << iota
	eq
	gt
)

var relationStrings = [...]string{
	0: "none", lt: "<", eq: "==", lt | eq: "<=",
	gt: ">", gt | lt: "!=", gt | eq: ">=", gt | eq | lt: "any",
}

So “less than”, “equal”, “greater than” are three independent bits, and a relation is a set of possibilities, not a single answer. Before a branch, the compiler knows x could be less than, equal to, or greater than y. After a branch on x < y, the relation on the taken edge becomes {lt} and on the other edge becomes {eq, gt}.

This is a “domain-partitioned range analysis” and it is the standard trick for making bounds-check elimination sound in the presence of signed arithmetic.

The facts table

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:146

// factsTable keeps track of relations between pairs of values.
//
// The fact table logic is sound, but incomplete. Outside of a few
// special cases, it performs no deduction or arithmetic. While there
// are known decision procedures for this, the ad hoc approach taken
// by the facts table is effective for real code while remaining very
// efficient.
type factsTable struct {
	// unsat is true if facts contains a contradiction.
	//
	// Note that the factsTable logic is incomplete, so if unsat
	// is false, the assertions in factsTable could be satisfiable
	// *or* unsatisfiable.
	unsat bool // true if facts contains a contradiction
	unsatDepth int // number of unsat checkpoints

	// order* is a couple of partial order sets that record information
	// about relations between SSA values in the signed and unsigned
	// domain.
	orderS *ssa.Poset
	orderU *ssa.Poset

Two things in that comment are worth pausing on.

“Sound, but incomplete.” The analysis never claims a check is redundant unless it is definitely redundant. It may leave redundant checks in place. That is the right trade for a compiler: a missed optimisation costs a nanosecond, an unsound one is a memory-safety bug.

“Known decision procedures for this.” There are complete algorithms for this problem (Presburger arithmetic, mostly). The compiler does not use them because they are slow. This is a deliberate engineering choice: an ad-hoc analysis that is fast enough to run on every function beats a complete one that is not.

The table keeps several kinds of facts:

orderS / orderU: two partial orders, one per numeric domain, tracking which values are greater than which.
additions: a map from a base value to a list of values equal to it plus a constant delta.
orderings: explicit pairwise relations.
limits: per-value numeric bounds.

That last one is where the really clever bit lives.

Limits: knowing the range of a value

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:120
// a Limit records known upper and lower bounds for a value.
//
// If we have min>max or umin>umax, then this Limit is
// called "unsatisfiable". When we encounter such a Limit, we
// know that any code for which that Limit applies is unreachable.
// We don't particularly care how unsatisfiable limits propagate,
// including becoming satisfiable, because any optimization
// decisions based on those limits only apply to unreachable code.
type Limit struct {
	Min, Max int64 // min <= value <= max, signed
	Umin, Umax uint64 // umin <= value <= umax, unsigned
	// For booleans, we use 0==false, 1==true for both ranges
	// For pointers, we use 0,0,0,0 for nil and minInt64,maxInt64,1,maxUint64 for nonnil
}

A Limit is a range, and it is not just a range — it is a range in both domains simultaneously, plus the ability to represent “unsatisfiable”, which means “this code is unreachable”.

The initialisation is where the type system leaks into the analysis:

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:66
	// Default limits based on type.
	lim := NoLimitForBitsize(uint(v.Type.Size()) * 8)

	// Tighter limits on some opcodes.
	switch v.Op {
	// constants
	case ssaop.OpConst64:
		lim = Limit{Min: v.AuxInt, Max: v.AuxInt, Umin: uint64(v.AuxInt), Umax: uint64(v.AuxInt)}
	...
	// extensions
	case ssaop.OpZeroExt8to64, ssaop.OpZeroExt8to32, ssaop.OpZeroExt8to16:
		lim = lim.SignedMinMax(0, 1<<8-1)
		lim = lim.UnsignedMax(1<<8 - 1)

A uint8 has limits [0, 255]. A zero-extended byte has the same limits. A sign-extended byte has [-128, 127]. All of this is derived from the SSA opcode, before any dataflow — the type of the value tells you its range.

Then there is the length operation, which is the one that matters for bounds checks:

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:95
	// length operations
	case ssaop.OpSliceLen, ssaop.OpSliceCap:
		f := v.Block.Func
		elemSize := uint64(v.Args[0].Type.Elem().Size())
		if elemSize > 0 {
			heapSize := uint64(1)<<(uint64(f.Config.PtrSize)*8) - 1
			maximumElementsFittingInHeap := heapSize / elemSize
			lim = lim.UnsignedMax(maximumElementsFittingInHeap)
		}
		fallthrough
	case ssaop.OpStringLen:
		lim = lim.signedMin(0)

A slice length cannot exceed the number of elements that could physically fit in the address space. On a 64-bit machine, a []byte can have at most 2^64 - 1 elements. On a 32-bit machine, at most 2^32 - 1. This bound is weak in absolute terms, but it is exactly what is needed to make unsigned comparisons sound.

Learning from branches

The prove pass walks the control flow graph, and at each branch it refines the facts. The refinement is where IsInBounds gets its power:

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:460
		case ssaop.OpIsInBounds, ssaop.OpIsSliceInBounds:
			// 0 <= a0 < a1 (or 0 <= a0 <= a1)
			r := lt
			if v.Op == ssaop.OpIsSliceInBounds {
				r |= eq
			}
			if isTrue {
				// On the positive branch, we learn:
				// signed: 0 <= a0 < a1 (or 0 <= a0 <= a1)
				// unsigned: a0 < a1 (or a0 <= a1)
				ft.setNonNegative(v.Args[0])
				ft.update(v.Block, v.Args[0], v.Args[1], signed, r)
				ft.update(v.Block, v.Args[0], v.Args[1], unsigned, r)
			} else {
				// On the negative branch, we learn (0 > a0 ||
				// a0 >= a1). In the unsigned domain, this is
				// simply a0 >= a1 (which is the reverse of the
				// positive branch, so nothing surprising).
				// But in the signed domain, we can't express the ||
				// condition, so check if a0 is non-negative instead,
				// to be able to learn something.
				r ^= lt | gt | eq // >= (index) or > (slice)
				if ft.isNonNegative(v.Args[0]) {
					ft.update(v.Block, v.Args[0], v.Args[1], signed, r)
				}
				ft.update(v.Block, v.Args[0], v.Args[1], unsigned, r)
				// TODO: v.Block is wrong here
			}

Read the positive branch carefully. When the compiler knows IsInBounds(i, n) is true, it learns two things: i is non-negative, and i < n. Those are separate facts, and the second one is exactly what a later IsInBounds(i, n) needs to be proved true.

The negative branch shows the domain partition doing its job. When the check fails, the compiler learns i >= n in the unsigned domain unconditionally, but in the signed domain it can only learn that if it already knows i is non-negative — because the failure condition is i < 0 || i >= n, and the signed domain cannot express a disjunction. The comment says exactly that:

But in the signed domain, we can’t express the || condition, so check if a0 is non-negative instead, to be able to learn something.

That is a small piece of textbook reasoning, expressed as three lines of Go.

The chunked-access special case

There is one genuinely clever piece of reasoning in the pass, and it handles the pattern that shows up in every hand-written parser:

 go
 
 
for i := 0; i+4 <= len(s); i++ {
 x := binary.BigEndian.Uint32(s[i:])
 ...
}

Here the compiler must prove i, i+1, i+2 and i+3 are all in bounds.

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:1937
func checkForChunkedIndexBounds(ft *factsTable, b *ssa.Block, index, bound *ssa.Value, isReslice bool) bool {
	if bound.Op != ssaop.OpSliceLen && bound.Op != ssaop.OpStringLen && bound.Op != ssaop.OpSliceCap {
		return false
	}

	// this is a slice bounds check against len or capacity,
	// and refers back to a prior check against length, which
	// will also work for the cap since that is not smaller
	// than the length.

	slice := bound.Args[0]
	lim := ft.limits[index.ID]
	if lim.Min < 0 {
		return false
	}
	i, delta := isConstDelta(index)
	if i == nil {
		return false
	}
	if delta < 0 {
		return false
	}

The comment inside the function is a worked example of the logic:

 go
 
 
	// special case for blocked iteration over a slice.
	// slicelen > i + delta && <==== if clauses above
	// && index >= 0 <==== if clause above
	// delta >= 0 && <==== if clause above
	// slicelen-K >/>= x <==== checked below
	// && K >=/> delta <==== checked below
	// then v > w
	// example: i <=/< len - 4/3 means i+{0,1,2,3} are legal indices

And the implementation:

 go
 
 
	for o := ft.orderings[i.ID]; o != nil; o = o.next {
		if o.d != signed {
			continue
		}
		if ow := o.w; ow.Op == ssaop.OpAdd64 {
			var lenOffset *ssa.Value
			if bound := ow.Args[0]; (bound.Op == ssaop.OpSliceLen || bound.Op == ssaop.OpStringLen) && bound.Args[0] == slice {
				lenOffset = ow.Args[1]
			} else if bound := ow.Args[1]; (bound.Op == ssaop.OpSliceLen || bound.Op == ssaop.OpStringLen) && bound.Args[0] == slice {
				lenOffset = ow.Args[0]
			}
			if lenOffset == nil || lenOffset.Op != ssaop.OpConst64 {
				continue
			}
			if K := -lenOffset.AuxInt; K >= 0 {
				or := o.r
				if isReslice {
					K++
				}
				if or == lt {
					or = lt | eq
					K++
				}
				if K < 0 { // We hate thinking about overflow
					continue
				}

				if delta < K && or == lt|eq {
					return true
				}
			}
		}
	}
	return false
}

The idea: if the compiler knows i < len(s) - 4 (or i <= len(s) - 4), then i+3 < len(s) and the check on i+3 is redundant. The K bookkeeping handles the off-by-one difference between < and <=, and the reslice case (which allows the last element) needs an extra increment.

The comment // We hate thinking about overflow is doing a lot of work. K is derived from a negated constant, and negating math.MinInt64 overflows. The code refuses to reason about it rather than getting it wrong.

The `Limit` type is more than a range

Look again at the arithmetic operations available on a Limit:

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:308
func (l Limit) Add(l2 Limit, b uint) Limit {

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:349
func (l Limit) Sub(l2 Limit, b uint) Limit {

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:367
func (l Limit) Mul(l2 Limit, b uint) Limit {

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:401
func (l Limit) Com(b uint) Limit {

Add, Sub, Mul, Com (complement), Neg, Ctz, Bitlen, Popcount, Exp2. This is an interval-arithmetic library, embedded in the compiler, used to compute the range of a value from the ranges of its inputs.

The Com case is a nice example of the domain partition earning its keep:

 go
 
 
// src/cmd/compile/internal/ssa/prove.go:401
func (l Limit) Com(b uint) Limit {

Complementing a signed value gives a different range than complementing an unsigned one, and the type knows which domain it is in.

The `poset`: transitivity for free

The orderS and orderU fields are *ssa.Poset — partial orders. That is the trick that makes the analysis cheap: you do not need to record a < b and b < c and a < c separately. The poset derives the third from the first two.

The explicit orderings map is for facts the poset cannot represent:

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:176
	// orderings contains a list of known orderings between values.
	// These lists are indexed by v.ID.
	// We do not record transitive orderings. Only explicitly learned
	// orderings are recorded. Transitive orderings can be obtained
	// by walking along the individual orderings.
	orderings map[ssa.ID]*ordering

So the poset handles the “greater than” relation (a total order on values, which is transitive) and the explicit list handles the mixed relations (!=, <=, >=) that are not.

Proving the check itself

Now the payoff. When the compiler reaches an IsInBounds, it asks whether the facts table already implies it:

 go
 
 
// src/cmd/compile/internal/ssacompile/prove.go:2157
	case ssaop.OpIsInBounds:
		if checkForChunkedIndexBounds(ft, b, v.Args[0], v.Args[1], false) {
			if b.Func.Pass.Debug > 0 {
				b.Func.Warnl(v.Pos, "Proved %s for blocked indexing", v.Op)
			}
			ft.booleanTrue(v)
		}

ft.booleanTrue(v) sets the value’s limit to the constant 1. Once the value is a compile-time constant, the branch that depends on it folds away, and the panic path becomes dead code.

The b.Func.Warnl call is only active with -d=ssa/prove/debug=1 — the compiler will tell you exactly which checks it proved:

text

$ go build -gcflags='-d=ssa/prove/debug=1' ./...

How do you check the compiler’s work?

There is a dedicated debug facility:

 go
 
 
// src/cmd/compile/internal/ssacompile/checkbce.go:14
// checkbce prints all bounds checks that are present in the function.
// Useful to find regressions. checkbce is only activated when with
// corresponding debug options, so it's off by default.
// See test/checkbce.go
func checkbce(f *ssa.Func) {
	if f.Pass.Debug <= 0 && !logopt.Enabled() {
		return
	}

With -d=ssa/checkbce/debug=1 you get a list of every bounds check that survived the optimisation. That is exactly the tool you want when you have written a hot loop and want to know why the check is still there.

The SSA dump itself (-d=ssa/dump=1) shows the IsInBounds values and, after the prove pass, whether they have been folded to ConstBool [true].

Trade-offs

Sound but incomplete. The analysis will leave provably-redundant checks in place. This is deliberate. A complete decision procedure exists (Presburger arithmetic) but is too slow to run on every function.

Domain partitioning costs completeness. Because signed and unsigned facts never mix freely, the analysis sometimes cannot prove things it “should” be able to. The || handling in the negative branch is the visible symptom.

The factsTable is ad hoc. The source says so, and it is a feature: the implementation optimises for real code shapes rather than for theoretical completeness.

Bounds checks are cheap, but not free. A CMPQ and a SETB are one instruction each. The branch is the expensive part, because it is unpredictable in exactly the loops where you care about performance.

Loop induction variables get special treatment. There is a whole separate file, loopbce.go, for finding induction variables and rewriting loops into “downward counting” form, which is easier to prove:

 go
 
 
// src/cmd/compile/internal/ssacompile/loopbce.go:25
type indVar struct {
	ind *ssa.Value // induction variable
	nxt *ssa.Value // the incremented variable
	min *ssa.Value // minimum value, inclusive/exclusive depends on flags
	max *ssa.Value // maximum value, inclusive/exclusive depends on flags
	entry *ssa.Block // the block where the edge from the succeeded comparison of the induction variable goes to, means when the bound check has passed.
	step int64 // it will always be positive.
	flags indVarFlags
	// Invariant: for all blocks dominated by entry:
	//	min <= ind < max [if flags == 0]
	//	min < ind < max [if flags == indVarMinExc]
	//	min <= ind <= max [if flags == indVarMaxInc]
	//	min < ind <= max [if flags == indVarMinExc|indVarMaxInc]
}

The Invariant comment is the contract, and the flag-based inclusivity is what lets the analysis handle for i := 0; i < n; i++ and for i := 0; i <= n-1; i++ with the same machinery.

Caveats

You cannot rely on a check being removed. The analysis may change between Go releases, or not fire for your particular code shape. If your code depends on the check not being there for performance, that is fragile.

The //go:nosplit and unsafe escape hatches bypass all of this. If you use unsafe, the compiler will not add checks in the first place, and the prove pass has nothing to work with.

Bounds checks on struct fields and pointers are different. The analysis here is about slice and string indexing. A nil-pointer dereference is a different check (OpIsNonNil), handled by the same facts table but with different rules — note the pointer domain in the domain type.

The -d=ssa/checkbce output is a debugging aid, not a contract. It prints what the pass saw, in the pass’s own terms.

IsSliceInBounds allows the last element, IsInBounds does not. The difference is one bit in the relation (r |= eq), and it matters for three-index slicing s[i:j:k].

Wrapping up

The one thing to remember: Go’s bounds-check elimination is a domain-partitioned range analysis. The same bit pattern means different things as a signed and an unsigned number, so the compiler keeps separate facts for each domain and refuses to mix them.

The part people get wrong: the compiler does not remove the check because it “knows” the index is small. It removes the check because an earlier branch already established the fact, and it re-establishes that fact on the taken edge. The proof is a dataflow property, not a syntactic one.

What to go do about it: write loops in the shape the analysis likes — for i := range s, or for i := 0; i < len(s); i++ — and check your work with -gcflags='-d=ssa/checkbce/debug=1'. If a check survives that you thought would go, the loop shape is probably the reason.

How Go Allocates Registers: The SSA Backend's Linear Scan Pass

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go does not use graph colouring. Its register allocator is a greedy linear scan: walk the function’s instructions in order, move each value into a register just before it is used, and when every register is busy, evict the value whose next use is farthest in the future. That last rule is the whole spill heuristic in one sentence.

Most compilers that people admire use a graph-colouring register allocator: build an interference graph, colour it, and hope. Go does not. Go’s allocator is a linear scan, and understanding why it is a linear scan — and what it gives up — explains a lot about the shape of Go’s generated code.

This is a walk through how it works, based on reading the Go 1.28 development tree (src/cmd/compile/internal/ssacompile/regalloc.go and src/cmd/compile/internal/ssa/).

Where the code lives

One structural note before diving in, because it is confusing the first time you go looking. The SSA backend used to be one package. It is now split in two:

src/cmd/compile/internal/ssa/ holds the data structures: Value, Block, Func, the Location interface, the opcode tables (ssa/ssaop/), and the rewrite rules (ssa/_gen/*.rules).
src/cmd/compile/internal/ssacompile/ holds the passes: the whole register allocator lives in ssacompile/regalloc.go (3835 lines), and the pass list is in ssacompile/compile.go.

The old ssa/regalloc.go is now just the design essay — the long comment at the top of the file is the canonical description of the algorithm:

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:5
// Register allocation.
//
// We use a version of a linear scan register allocator. We treat the
// whole function as a single long basic block and run through
// it using a greedy register allocator. Then all merge edges
// (those targeting a block with len(Preds)>1) are processed to
// shuffle data into the place that the target of the edge expects.
//
// The greedy allocator moves values into registers just before they
// are used, spills registers only when necessary, and spills the
// value whose next use is farthest in the future.
//
// The register allocator requires that a block is not scheduled until
// at least one of its predecessors have been scheduled. The most recent
// such predecessor provides the starting register state for a block.
//
// It also requires that there are no critical edges (critical =
// comes from a block with >1 successor and goes to a block with >1
// predecessor). This makes it easy to add fixup code on merge edges -
// the source of a merge edge has only one successor, so we can add
// fixup code to the end of that block.

“We treat the whole function as a single long basic block.” That is the key sentence and the key simplification. A classical linear-scan allocator (Wimmer, Wegen) works on intervals over a linearised instruction stream and needs the CFG to be reducible. Go’s version sidesteps the whole problem: it does not try to assign a value to a register for its entire live range. It assigns registers late, at the point of use, and deals with the CFG afterwards by shuffling values on merge edges.

The SSA form

Before the allocator runs, the function is in static single assignment form. The package README describes the building blocks:

 text
 
 
// src/cmd/compile/internal/ssa/README.md:30
#### Values

Values are the basic building blocks of SSA. Per SSA's very definition,
a value is defined exactly once, but it may be used any number of times. A value
mainly consists of a unique identifier, an operator, a type, and some arguments.

An operator or `Op` describes the operation that computes the value. The
semantics of each operator can be found in `_gen/*Ops.go`. For example, `OpAdd8`
takes two value arguments holding 8-bit integers and results in their addition.
Here is a possible SSA representation of the addition of two `uint8` values:

	// var c uint8 = a + b
	v4 = Add8 <uint8> v2 v3

A Value in the code is a struct with an ID, an Op, a type, some arguments, a block, and a position:

 go
 
 
// src/cmd/compile/internal/ssa/value.go:21
// A Value represents a value in the SSA representation of the program.
// The ID and Type fields must not be modified. The remainder may be modified
// if they preserve the value of the Value (e.g. changing a (mul 2 x) to an (add x x)).
type Value struct {
	// A unique identifier for the value. For performance we allocate these IDs
	// densely starting at 1. There is no guarantee that there won't be occasional holes, though.
	ID ID

	// The operation that computes this value. See op.go.
	Op ssaop.Op

	// The type of this value. Normally this will be a Go type, but there
	// are a few other pseudo-types, see ../types/type.go.
	Type *types.Type

The Op type is generated from the _gen/*Ops.go tables:

 go
 
 
// src/cmd/compile/internal/ssa/ssaop/op.go:52
// An Op encodes the specific operation that a Value performs.
// Opcodes' semantics can be modified by the type and aux fields of the Value.
// For instance, OpAdd can be 32 or 64 bit, signed or unsigned, float or complex, depending on Value.Type.
// Semantics of each op are described in the opcode files in _gen/*Ops.go.
// There is one file for generic (architecture-independent) ops and one file
// for each architecture.
type Op int32

And the opcode table, which is the machine-readable description of every operation’s register behaviour:

 go
 
 
// src/cmd/compile/internal/ssa/ssaop/op.go:60
type OpInfo struct {
	Name string
	Reg RegInfo
	AuxType AuxType
	ArgLen int32 // the number of arguments, -1 if variable length
	asm obj.As
	Generic bool // this is a generic (arch-independent) opcode
	Rematerializeable bool // this op is rematerializeable
	Commutative bool // this operation is commutative (e.g. addition)
	ResultInArg0 bool // (first, if a tuple) output of v and v.Args[0] must be allocated to the same register
	ResultNotInArgs bool // outputs must not be allocated to the same registers as inputs
	ClobberFlags bool // this op clobbers flags register
	NeedIntTemp bool // need a temporary free integer register
	Call bool // is a function call

Three fields in there matter enormously to the allocator:

Reg — the input and output register constraints.
Rematerializeable — can this value be recomputed rather than spilled?
ResultInArg0 — the output must live in the same register as input 0.

Rematerializeable is a big deal. A constant can be rematerialized for free, so it never needs a spill slot:

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:163
// Rematerializeable reports whether the register allocator should recompute
// a value instead of spilling/restoring it.
func (v *Value) Rematerializeable() bool {
	if !ssaop.OpcodeTable[v.Op].Rematerializeable {
		return false
	}
	for _, a := range v.Args {
		// Fixed-register allocations (SP, SB, etc.) are always available.
		// Any other argument of an opcode makes it not rematerializeable.
		if !ssaop.OpcodeTable[a.Op].FixedReg {
			return false
		}
	}
	return true
}

The output of the pass: `Location`

When the allocator is done, it has to tell the rest of the compiler where each value lives. The answer is a Location:

 go
 
 
// src/cmd/compile/internal/ssa/location.go:44
// A place that an ssa variable can reside.
type Location interface {
	String() string // name to use in assembly templates: AX, 16(SP), ...
}

That is the entire interface. One method. A location is either a machine register or a stack slot. The stack slot case is a LocalSlot:

 go
 
 
// src/cmd/compile/internal/ssa/location.go:35
type LocalSlot struct {
	N *ir.Name // an ONAME *ir.Name representing a stack location.
	Type *types.Type // type of slot
	Off int64 // offset of slot in N

	SplitOf *LocalSlot // slot is a decomposition of SplitOf
	SplitOffset int64 // .. at this offset.
}

The mapping lives on the function, indexed by value ID:

 go
 
 
// src/cmd/compile/internal/ssa/func.go:59
	// when register allocation is done, maps value ids to locations
	RegAlloc []Location

and the setter is where the allocator writes its answers:

 go
 
 
// src/cmd/compile/internal/ssa/stackalloc.go:400
func (f *Func) SetHome(v *Value, loc Location) {
	for v.ID >= ID(len(f.RegAlloc)) {
		f.RegAlloc = append(f.RegAlloc, nil)
	}
	f.RegAlloc[v.ID] = loc
}

Once this array is populated, the backend asks each value where it is:

 go
 
 
// src/cmd/compile/internal/ssa/value.go:573
// ResultReg returns the result register assigned to v, in cmd/internal/obj/$ARCH numbering.
// It is similar to Reg and Reg0, except that it is usable interchangeably for all Value Ops.
// If you know v.Op, using Reg or Reg0 (as appropriate) will be more efficient.
func (v *Value) ResultReg() int16 {
	reg := v.Block.Func.RegAlloc[v.ID]
	if reg == nil {
		v.Fatalf("nil reg for value: %s\n%s\n", v.LongString(), v.Block.Func)
	}
	if pair, ok := reg.(LocPair); ok {
		reg = pair[0]
	}
	if reg == nil {
		v.Fatalf("nil reg0 for value: %s\n%s\n", v.LongString(), v.Block.Func)
	}
	return reg.(*ssabase.Register).ObjNum
}

The state of the allocator

The allocator keeps a regAllocState, and the interesting fields are the register file and the per-value state:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:172
type regState struct {
	v *ssa.Value // Original (preregalloc) Value stored in this register.
	c *ssa.Value // A Value equal to v which is currently in a register. Might be v or a copy of it.
	// If a register is unused, v==c==nil
}

Note the two values. v is the original SSA value; c is the value currently in the register, which may be a copy of v. The distinction matters because the allocator inserts copies freely to satisfy register constraints.

The per-value state is in the ssa package, since it is shared between the allocator and other passes:

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:147
// A ValState records the register allocation state for a (pre-regalloc) value.
type ValState struct {
	Regs ssaop.RegMask // the set of registers holding a Value (usually just one)
	Uses *Use // list of uses in this block
	Spill *Value // spilled copy of the Value (if any)
	RestoreMin int32 // minimum of all restores' blocks' sdom.entry
	RestoreMax int32 // maximum of all restores' blocks' sdom.exit
	NeedReg bool // cached value of !v.Type.IsMemory() && !v.Type.IsVoid() && !.v.Type.IsFlags()
	Rematerializeable bool // cached value of v.rematerializeable()
}

Uses is the linear-scan bookkeeping: a linked list of upcoming uses, each with a distance — how many instructions away the use is:

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:136
type Use struct {
	// distance from start of the block to a use of a value
	// Dist == 0 used by first instruction in block
	// Dist == len(b.Values)-1 used by last instruction in block
	// Dist == len(b.Values) used by block's control value
	// Dist > len(b.Values) used by a subsequent block
	Dist int32
	Pos src.XPos // source position of the use
	Next *Use // linked list of uses of a value in nondecreasing dist order
}

Dist is the whole basis of the spill heuristic. A value whose next use is 40 instructions away is a much better spill candidate than one used on the next line.

Phase one: liveness

Before allocating anything, the allocator needs to know which values are live at the end of each block, and how far away their next use is. computeLive does that:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:3218
type liveInfo struct {
	ID ssa.ID // ID of value
	dist int32 // # of instructions before next use
	pos src.XPos // source position of next use
}

// computeLive computes a map from block ID to a list of value IDs live at the end
// of that block. Together with the value ID is a count of how many instructions
// to the next use of that value. The resulting map is stored in s.live.
func (s *regAllocState) computeLive() {
	f := s.f
	// single block functions do not have variables that are live across
	// branches
	if len(f.Blocks) == 1 {
		return
	}
	po := f.Postorder()
	s.live = make([][]liveInfo, f.NumBlocks())
	s.desired = make([]desiredState, f.NumBlocks())
	s.loopnest = f.Loopnest()

and the algorithm itself, with the paper it is adapted from:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:3248
	// Liveness analysis.
	// This is an adapted version of the algorithm described in chapter 2.4.2
	// of Fabrice Rastello's On Sparse Intermediate Representations.
	// https://web.archive.org/web/20240417212122if_/https://inria.hal.science/hal-00761555/file/habilitation.pdf#section.50
	//
	// For our implementation, we fall back to a traditional iterative algorithm when we encounter
	// Irreducible CFGs. They are very uncommon in Go code because they need to be constructed with
	// gotos and our current loopnest definition does not compute all the information that
	// we'd need to compute the loop ancestors for that step of the algorithm.
	//
	// Additionally, instead of only considering non-loop successors in the initial DFS phase,
	// we compute the liveout as the union of all successors. This larger liveout set is a subset
	// of the final liveout for the block and adding this information in the DFS phase means that
	// we get slightly more accurate distance information.

So the liveness is a sparse-map dataflow, with a “distance to next use” attached to each live value. That distance is what makes the spill heuristic smart rather than random.

One special case in there: a function call clobbers everything, so anything live across a call is pushed far into the future:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:3318
				if ssaop.OpcodeTable[v.Op].Call {
					if numCalls != nil {
						numCalls[b.ID]++
					}
					rematIDs = rematIDs[:0]
					c := live.Contents()
					for i := range c {
						c[i].Val += unlikelyDistance
						vid := c[i].Key
						if s.values[vid].Rematerializeable {
							rematIDs = append(rematIDs, vid)
						}
					}
					// We don't spill rematerializeable values, and assuming they
					// are live across a call would only force shuffle to add some
					// (dead) constant rematerialization. Remove them.
					for _, r := range rematIDs {
						live.Remove(r)
					}
				}

unlikelyDistance is 100 instructions. And rematerializable values (constants) are dropped from the live set entirely across a call, because you can always just recompute them.

Phase two: the linear scan

The main loop walks the blocks in a chosen order and, within each block, walks the instructions in order. For each instruction, it moves the operands into the registers the instruction wants.

The shape of the whole pass:

 text
 
 
 for each block b in visitOrder:
 compute use distances for b (backwards liveness)
 pick a "primary predecessor" and adopt its register state
 assign registers to b's phis
 |
 +-- for each instruction in b:
 | for each input i:
 | if v is already in a register: use it
 | else if v can be rematerialized: recompute it
 | else: load it from its spill slot
 | assign the output register
 |
 +-- afterwards: place the spills that were created
 +-- afterwards: shuffle values on merge edges

The state that makes this work is regAllocState, and the fields that matter are the register file, the set of registers in use, and the set of registers that must not be spilled:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:210
	// current state of each register.
	// Includes only registers in allocatable.
	regs []regState

	// registers that contain values which can't be kicked out
	nospill ssaop.RegMask

	// mask of registers currently in use
	used ssaop.RegMask

	// mask of registers used since the start of the current block
	usedSinceBlockStart ssaop.RegMask

	// mask of registers used in the current instruction
	tmpused ssaop.RegMask

Which registers are even eligible? That is decided per architecture at init time, and SP, SB and the g register are always excluded:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:650
	// Figure out which registers we're allowed to use.
	s.allocatable = s.f.Config.GpRegMask.Union(s.f.Config.FpRegMask).Union(s.f.Config.SpecialRegMask).Union(s.f.Config.SimdRegMask).Union(s.f.Config.SimdMaskReg)
	s.allocatable = s.allocatable.RemoveReg(s.SPReg)
	s.allocatable = s.allocatable.RemoveReg(s.SBReg)
	if s.f.Config.HasGReg {
		s.allocatable = s.allocatable.RemoveReg(s.GReg)
	}

Choosing a register

allocReg is the heart of it. Pick an unused register if there is one; otherwise evict somebody:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:360
// allocReg chooses a register from the set of registers in mask.
// If there is no unused register, a Value will be kicked out of
// a register to make room.
func (s *regAllocState) allocReg(mask ssaop.RegMask, v *ssa.Value) ssaop.Register {
	if v.OnWasmStack {
		return noRegister
	}

	mask = mask.Intersect(s.allocatable)
	mask = mask.Minus(s.nospill)
	if mask.Empty() {
		s.f.Fatalf("no register available for %s", v.LongString())
	}

	// Pick an unused register if one is available.
	if !mask.Minus(s.used).Empty() {
		r := s.pickReg(mask.Minus(s.used))
		s.usedSinceBlockStart = s.usedSinceBlockStart.AddReg(r)
		return r
	}

	// Pick a value to spill. Spill the value with the
	// farthest-in-the-future use.
	// TODO: Prefer registers with already spilled Values?
	// TODO: Modify preference using affinity graph.
	// TODO: if a single value is in multiple registers, spill one of them
	// before spilling a value in just a single register.

	// Find a register to spill. We spill the register containing the value
	// whose next use is as far in the future as possible.
	// https://en.wikipedia.org/wiki/Page_replacement_algorithm#The_theoretically_optimal_page_replacement_algorithm
	var r ssaop.Register
	maxuse := int32(-1)
	for t := ssaop.Register(0); t < s.numRegs; t++ {
		if !mask.HasReg(t) {
			continue
		}
		v := s.regs[t].v
		if n := s.values[v.ID].Uses.Dist; n > maxuse {
			// v's next use is farther in the future than any value
			// we've seen so far. A new best spill candidate.
			r = t
			maxuse = n
		}
	}

That comment is worth pausing on: it links to the theoretically optimal page replacement algorithm. This is exactly the Belady optimal algorithm from virtual memory, transplanted to register allocation. The value whose next use is farthest away is the one whose register you can steal with the least harm.

Before actually evicting, the allocator tries to be clever: if the victim could be moved to a free register instead of spilled, it moves it:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:417
	// Try to move it around before kicking out, if there is a free register.
	// We generate a Copy and record it. It will be deleted if never used.
	v2 := s.regs[r].v
	m := s.compatRegs(v2.Type).Minus(s.used).Minus(s.tmpused).RemoveReg(r)
	if !m.Empty() && !s.values[v2.ID].Rematerializeable && countRegs(s.values[v2.ID].Regs) == 1 {
		s.usedSinceBlockStart = s.usedSinceBlockStart.AddReg(r)
		r2 := s.pickReg(m)
		c := s.curBlock.NewValue1(v2.Pos, ssaop.OpCopy, v2.Type, s.regs[r].c)
		if s.f.Pass.Debug > ssa.RegDebug {
			fmt.Printf("copy %s to %s : %s\n", v2, c, &s.registers[r2])
		}
		s.setOrig(c, v2)
		s.assignReg(r2, v2, c)
	}

A copy is cheaper than a spill: no memory traffic, no reload. And note the !s.values[v2.ID].Rematerializeable condition — if the victim can be recomputed, recomputing it is free, so there is no point copying it.

Spilling

makeSpill creates the spill value. Note that it does not know where the spill will go yet:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:449
// makeSpill returns a Value which represents the spilled value of v.
// b is the block in which the spill is used.
func (s *regAllocState) makeSpill(v *ssa.Value, b *ssa.Block) *ssa.Value {
	vi := &s.values[v.ID]
	if vi.Spill != nil {
		// Final block not known - keep track of subtree where restores reside.
		vi.RestoreMin = min(vi.RestoreMin, s.sdom[b.ID].Entry)
		vi.RestoreMax = max(vi.RestoreMax, s.sdom[b.ID].Exit)
		return vi.Spill
	}
	// Make a spill for v. We don't know where we want
	// to put it yet, so we leave it blockless for now.
	spill := s.f.NewValueNoBlock(ssaop.OpStoreReg, v.Type, v.Pos)
	// We also don't know what the spill's arg will be.
	// Leave it argless for now.
	s.setOrig(spill, v)
	vi.Spill = spill
	vi.RestoreMin = s.sdom[b.ID].Entry
	vi.RestoreMax = s.sdom[b.ID].Exit
	return spill
}

OpStoreReg and OpLoadReg are the two pseudo-ops that implement the spill mechanism. They are ordinary SSA ops, generated into the opcode table like everything else:

 go
 
 
// src/cmd/compile/internal/ssa/ssaop/opGen.go:7213
	OpStoreReg
	OpLoadReg

The StoreReg/LoadReg pair is what turns into an actual store and load in the machine-code backend. On amd64:

 go
 
 
// src/cmd/compile/internal/amd64/ssa.go:1387:1388
	case ssaop.OpStoreReg:
		if v.Type.IsFlags() {
			v.Fatalf("store flags not implemented: %v", v.LongString())
			return
		}
		r := v.Args[0].Reg()
		if v.Type.IsSIMD() {
			r = simdOrMaskReg(v.Args[0])
		}
		p := s.Prog(storeByRegWidth(r, v.Type.Size(), hasAVX(v)))
		p.From.Type = obj.TYPE_REG
		p.From.Reg = r

The whole spill/restore dance is described in the design essay:

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:34
// pre-regalloc:
// (1) v = Op ...
// (2) x = Op ...
// (3) ... = Op v ...
//
// post-regalloc:
// (1) v = Op ... : AX // computes v, store result in AX
// s = StoreReg v // spill v to a stack slot
// (2) x = Op ... : AX // some other op uses AX
// c = LoadReg s : CX // restore v from stack slot
// (3) ... = Op c ... // use the restored value

Restoring

allocValToReg is the mirror image. It gets a value into a register, either by copying it, rematerializing it, or loading it from its spill slot:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:564:564
	} else {
		// Load v from its spill location.
		spill := s.makeSpill(v, s.curBlock)
		if s.f.Pass.Debug > ssa.LogSpills {
			s.f.Warnl(vi.Spill.Pos, "load spill for %v from %v", v, spill)
		}
		c = s.curBlock.NewValue1(pos, ssaop.OpLoadReg, v.Type, spill)
		sourceMask := s.compatRegs(v.Type)
		if !sourceMask.HasReg(r) && !onWasmStack {

Three ways to get a value into a register, in order of preference:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:521
	// Allocate v to the new register.
	var c *ssa.Value
	if !vi.Regs.Empty() {
		// Copy from a register that v is already in.
		var current *ssa.Value
		if !vi.Regs.Minus(s.allocatable).Empty() {
			// v is in a fixed register, prefer that
			current = v
		} else {
			r2 := s.pickReg(vi.Regs)
			if s.regs[r2].v != v {
				panic("bad register state")
			}
			current = s.regs[r2].c
			s.usedSinceBlockStart = s.usedSinceBlockStart.AddReg(r2)
		}
		c = s.curBlock.NewValue1(pos, ssaop.OpCopy, v.Type, current)
	} else if v.Rematerializeable() {
		// Rematerialize instead of loading from the spill location.
		c = v.CopyIntoWithXPos(s.curBlock, pos)

Copy if it is already in a register, rematerialize if it can be recomputed, load from the spill slot otherwise.

Placing the spill

Now the hard bit: the spill has to be scheduled somewhere. The spill must dominate every restore of the value, and it must be issued at a point where the value is still in a register.

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:53
// What remains is the question of where to schedule the spill.
// During allocation, we keep track of the dominator of all restores of v.
// The spill of v must dominate that block. The spill must also be issued at
// a point where v is still in a register.
//
// To find the right place, start at b, the block which dominates all restores.
// - If b is v.Block, then issue the spill right after v.
// It is known to be in a register at that point, and dominates any restores.
// - Otherwise, if v is in a register at the start of b,
// put the spill of v at the start of b.
// - Otherwise, set b = immediate dominator of b, and repeat.

The implementation walks the dominator tree looking for the best place, with a hard cutoff:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:2226
		v := s.orig[i]

		// Walk down the dominator tree looking for a good place to
		// put the spill of v. At the start "best" is the best place
		// we have found so far.
		// TODO: find a way to make this O(1) without arbitrary cutoffs.
		if v == nil {
			panic(fmt.Errorf("nil v, s.orig[%d], vi = %v, spill = %s", i, vi, spill.LongString()))
		}
		best := v.Block
		bestArg := v
		var bestDepth int16
		if s.loopnest != nil && s.loopnest.B2L[best.ID] != nil {
			bestDepth = s.loopnest.B2L[best.ID].Depth
		}
		b := best
		const maxSpillSearch = 100

and the loop-depth check, which avoids putting a spill inside a deeper loop than necessary:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:2264
			if depth > bestDepth {
				// Don't push the spill into a deeper loop.
				continue
			}

That is a real optimisation: a spill inside a hot loop body would be executed on every iteration.

Phi elimination

Phis are the reason merge edges are hard. Before the allocator runs, the compiler tries to eliminate as many phis as possible by turning them into copies:

 go
 
 
// src/cmd/compile/internal/ssa/copyelim.go:9
// PhiElimValue tries to convert the phi v to a copy.
func PhiElimValue(v *Value) bool {
	if v.Op != ssaop.OpPhi {
		return false
	}

	// If there are two distinct args of v which
	// are not v itself, then the phi must remain.
	// Otherwise, we can replace it with a copy.
	var w *Value
	for _, x := range v.Args {
		if x == v {
			continue
		}
		if x == w {
			continue
		}
		if w != nil {
			return false
		}
		w = x
	}

A phi with one distinct input is just a copy, and the copy can then be eliminated by copy propagation. That pass runs in a loop until nothing changes:

 go
 
 
// src/cmd/compile/internal/ssacompile/copyelim.go:105
func phielim(f *ssa.Func) {
	for {
		change := false
		for _, b := range f.Blocks {
			for _, v := range b.Values {
				// This is an early place in SSA where all values are examined.
				// Rewrite all 0-sized Go values to remove accessors, dereferences, loads, etc.
				if t := v.Type; (t.IsStruct() || t.IsArray()) && t.Size() == 0 {
					v.Reset(ssaop.OpEmpty)
				}
				// Modify all values so no arg (including args
				// of OpCopy) is a copy.
				copyelimValue(v)
				change = ssa.PhiElimValue(v) || change
			}
		}
		if !change {
			break
		}
	}
}

What survives is a real phi, and the allocator has to handle it: the phi and all of its inputs must end up in the same register, or the merge edge needs a shuffle.

Merge edges: the shuffle

The linear scan treats the function as one long block, which means at a merge point the predecessors might disagree about what is in which register. shuffle fixes that up, edge by edge:

 go
 
 
// src/cmd/compile/internal/ssacompile/regalloc.go:2326
// shuffle fixes up all the merge edges (those going into blocks of indegree > 1).
func (s *regAllocState) shuffle(stacklive [][]ssa.ID) {
	var e edgeState
	e.s = s
	e.cache = map[ssa.ID][]*ssa.Value{}
	e.contents = map[ssa.Location]contentRecord{}

The edgeState machinery is the most intricate part of the whole allocator. Its job is: given the register state at the end of the predecessor and the register state wanted at the start of the successor, insert copies to reconcile them.

The pass ordering constraints in the compiler’s pass list encode the requirements:

 go
 
 
// src/cmd/compile/internal/ssacompile/compile.go:534
	// regalloc requires the removal of all critical edges
	{"critical", "regalloc"},
	// regalloc requires all the values in a block to be scheduled
	{"schedule", "regalloc"},

and further down:

 go
 
 
// src/cmd/compile/internal/ssacompile/compile.go:548
	// the rules in late lower run after the general rules.
	{"lower", "late lower"},

and:

 go
 
 
// src/cmd/compile/internal/ssacompile/compile.go:550:548
	// flagalloc needs instructions to be scheduled.
	{"schedule", "flagalloc"},
	// regalloc needs flags to be allocated first.
	{"flagalloc", "regalloc"},

So the ordering is: lower to machine ops, schedule the instructions, allocate the flags register, remove critical edges, then regalloc. Flag allocation has to come first because flags live in their own register on x86 and the main allocator needs to know that register is taken.

The full pass list, for context:

 go
 
 
// src/cmd/compile/internal/ssacompile/compile.go:469
	{Name: "critical", Fn: critical, Required: true}, // remove critical edges
	{Name: "phi tighten", Fn: phiTighten}, // place rematerializable phi args near uses to reduce value lifetimes
	{Name: "likelyadjust", Fn: likelyadjust},
	{Name: "layout", Fn: layout, Required: true}, // schedule blocks
	{Name: "schedule", Fn: schedule, Required: true}, // schedule values
	{Name: "late nilcheck", Fn: nilcheckelim2},
	{Name: "flagalloc", Fn: flagalloc, Required: true}, // allocate flags register
	{Name: "regalloc", Fn: regalloc, Required: true}, // allocate int & float registers + stack slots
	{Name: "loop rotate", Fn: loopRotate},
	{Name: "trim", Fn: trim}, // remove empty blocks

Stack slots: the other allocator

Register allocation and stack slot allocation are separate. The register allocator spills to a logical spill value; the stack allocator then decides where in the frame that spill physically lives.

And here — unlike the register allocator — Go does build an interference graph:

 go
 
 
// src/cmd/compile/internal/ssa/stackalloc.go:120
	// Compute liveness info for values needing a slot.
	s.computeLive(spillLive)

	// Build interference graph among values needing a slot.
	s.buildInterferenceGraph()

and the graph is built by backward liveness:

 go
 
 
// src/cmd/compile/internal/ssa/stackalloc.go:407
func (s *StackAllocState) buildInterferenceGraph() {
	f := s.f
	if n := f.NumValues(); cap(s.interfere) >= n {
		s.interfere = s.interfere[:n]
	} else {
		s.interfere = make([][]ID, n)
	}
	live := f.NewSparseSet(f.NumValues())
	defer f.RetSparseSet(live)
	for _, b := range f.Blocks {
		// Propagate liveness backwards to the start of the block.
		// Two values interfere if one is defined while the other is live.
		live.Clear()
		live.addAll(s.Live[b.ID])
		for i := len(b.Values) - 1; i >= 0; i-- {
			v := b.Values[i]
			if s.values[v.ID].needSlot {
				live.Remove(v.ID)
				for _, id := range live.Contents() {
					// Note: args can have different types and still interfere
					// (with each other or with other values). See issue 23522.
					if s.values[v.ID].typ.Compare(s.values[id].typ) == types.CMPeq || hasAnyArgOp(v) || s.values[id].isArg {
						s.interfere[v.ID] = append(s.interfere[v.ID], id)
						s.interfere[id] = append(s.interfere[id], v.ID)
					}
				}
			}

The interference graph is used to decide which spilled values can share a stack slot. Two values that are never live at the same time can occupy the same memory. That is a straight graph-colouring problem over a small number of “colours” (the byte offsets within the slot), and it is where Go does use the classic technique.

Looking at it yourself

GOSSAFUNC is the tool for this. The SSA README explains it:

 text
 
 
// src/cmd/compile/internal/ssa/README.md:187
### Playing with SSA

A good way to see and get used to the compiler's SSA in action is via
`GOSSAFUNC`. For example, to see func `Foo`'s initial SSA form and final
generated assembly, one can run:

	GOSSAFUNC=Foo go build

The generated `ssa.html` file will also contain the SSA func at each of the
compile passes, making it easy to see what each pass does to a particular
program.

Adding + writes plain text dumps to stdout instead:

 text
 
 
// src/cmd/compile/internal/ssa/README.md:221
// If non-HTML dumps are needed, append a "+" to the GOSSAFUNC value
// and dumps will be written to stdout:

	GOSSAFUNC=Bar+ go build

And you can name specific passes:

 text
 
 
// src/cmd/compile/internal/ssa/README.md:209
// The user can print the Control Flow Graph(CFG) by specifying
// the GOSSAFUNC value in the following format:

	GOSSAFUNC="$FunctionName:$PassName1,$PassName2,..." go build

// For example, the following command will print SSA with CFGs attached to
// the "sccp" and "generic deadcode" pass columns:

	GOSSAFUNC="blah.Foo:sccp,generic deadcode" go build

The regalloc and stackalloc columns in the HTML dump show you exactly which values got which register, and which got spilled.

Trade-offs

What a linear scan gives you: compile speed. A graph-colouring allocator has to build and colour a graph, and graph colouring is super-linear in the worst case. A linear scan is essentially one pass over the instruction stream. For a language that compiles a large program in a couple of seconds, that matters.

What it costs you: quality. A graph-colouring allocator can find any assignment with no conflicts; a linear scan is greedy and makes locally-optimal choices that can be globally bad. The classic case is a loop with high pressure, where the greedy allocator spills a value that a smarter allocator would have kept.

Why “treat the whole function as one long basic block” is a good trade: it removes the need for live-range intervals and holes, which is where most of the complexity of a classical linear scan lives. Go pays for that with the merge-edge shuffle at the end.

Why the Belady heuristic is worth it: evicting the value whose next use is farthest away is provably the best choice for minimising page faults in a FIFO-ish setting, and it is a good approximation here. The alternative — evicting the oldest value — is what you get for free from a naive linear scan, and it is much worse.

Why rematerialization matters so much: a value that can be recomputed never needs a slot, never needs a load, and never causes a spill. Go gets this for free for constants. It is a big reason why Go’s generated code is often better than you would expect from such a simple allocator.

Caveats

The algorithm is not a textbook linear scan. It is a variant, and the comments are careful to say “a version of” a linear scan allocator. The biggest deviation is that allocation happens at the point of use rather than over an interval.

“Treat the whole function as one long basic block” is a simplification, not a description of the implementation. The allocator does maintain per-block register state (endRegs, startRegs) and does respect the block structure; it just does not compute global intervals.

The output is not-quite-SSA. The design essay is explicit about this:

 go
 
 
// src/cmd/compile/internal/ssa/regalloc.go:92
// Note: regalloc generates a not-quite-SSA output. If we have:
//
// b1: x = ... : AX
// x2 = StoreReg x
// ... AX gets reused for something else ...
// if ... goto b3 else b4
//
// b3: x3 = LoadReg x2 : BX b4: x4 = LoadReg x2 : CX
// ... use x3 ... ... use x4 ...
//
// b2: ... use x3 ...
//
// If b3 is the primary predecessor of b2, then we use x3 in b2 and
// add a x4:CX->BX copy at the end of b4.
// But the definition of x3 doesn't dominate b2. We should really
// insert an extra phi at the start of b2 (x5=phi(x3,x4):BX) to keep
// SSA form. For now, we ignore this problem as remaining in strict
// SSA form isn't needed after regalloc. We'll just leave the use
// of x3 not dominated by the definition of x3, and the CX->BX copy
// will have no use (so don't run deadcode after regalloc!).
// TODO: maybe we should introduce these extra phis?

The spill search has an arbitrary cutoff. const maxSpillSearch = 100 bounds the dominator-tree walk. On a function with an enormous dominator tree, the spill might be placed worse than optimal.

WebAssembly is a special case. The wasm backend keeps values on the wasm value stack rather than in registers, and the allocator has explicit branches for v.OnWasmStack throughout, including a comment admitting that the stack optimisation “in practice… breaks” in some cases.

Register pressure is not the only source of spills. A function call clobbers everything, so any value live across a call needs a spill slot regardless of how few registers are in use.

The RegAlloc array is indexed by value ID, so it is as large as the highest value ID. For a function with many values, that array is noticeably wasteful, which is why the compiler caches and reuses it between functions.

Wrapping up

The one thing to remember: Go’s register allocator is greedy and linear, and when it has to spill, it spills the value whose next use is farthest away — Belady’s optimal page replacement, applied to registers. If you want fewer spills, shorten the live ranges, not the function.

The part people get wrong: inlining makes register pressure worse, not better. Every inlined copy of a function has its own live ranges, and the allocator is working on the whole expanded function at once. A function that was register-pressure-bound before inlining can become spill-bound after, which is why the inliner has a “big function” rule.

What to go do about it: run GOSSAFUNC=YourFunc+ go build and look at the regalloc column. If you see StoreReg/LoadReg pairs, count them and look at where the loads are. Spills concentrated right after a call mean the function is holding too much across the call; spills inside a loop body mean the loop body is too big.

Go's Linker Deletes Code You Never Call: Method Pruning and Reachability

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go binaries are not “the standard library plus your code”. The linker floods the symbol graph starting at main.main, keeps only what it reaches, and then throws away the method tables of surviving types unless an interface or a reflective call could reach them. Everything it drops is gone from the binary — code, DWARF, and (with -s) the symbol table.

Every Go binary you ship contains a net/http server, a crypto/tls stack, a JSON encoder, and about nine hundred other packages’ worth of code. Almost none of it is running. Most of it is not even in the binary.

The Go linker does a reachability analysis over the symbol graph and deletes what it cannot prove is live. The interesting part is not that it deletes unreachable functions — that is easy. It is what it does with methods, because a method can be reached three ways and only one is visible in the object file.

This is a walk through how it works, based on reading the Go 1.28 development tree.

The rule the linker follows

The whole design is stated in one comment, in src/cmd/link/internal/ld/deadcode.go, and it comes down to three ways a method of a reachable type can be invoked:

A direct call — handled by the flood fill.
A call through an interface — handled by signature matching, which is deliberately over-conservative.
A call through reflection — handled by giving up.

The flood fill

The pass itself is a worklist algorithm over the symbol graph. The deadcodePass struct holds the state:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:22
type deadcodePass struct {
	ctxt *Link
	ldr *loader.Loader
	wq heap // work queue, using min-heap for better locality

	ifaceMethod map[methodsig]bool // methods called from reached interface call sites
	genericIfaceMethod map[string]bool // names of methods called from reached generic interface call sites
	markableMethods []methodref // methods of reached types
	reflectSeen bool // whether we have seen a reflect method call
	dynlink bool

The roots are main.main (or the entry symbol), runtime.unreachableMethod, the dynamic exports, and the package init tasks:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:82
	// runtime.unreachableMethod is a function that will throw if called.
	// We redirect unreachable methods to it.
	names = append(names, "runtime.unreachableMethod")

Marking is simple — a bitmap on the loader, and a push onto a min-heap so the traversal visits symbols in a cache-friendly order:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:359
func (d *deadcodePass) mark(symIdx, parent loader.Sym) {
	if symIdx != 0 && !d.ldr.AttrReachable(symIdx) {
		d.wq.push(symIdx)
		d.ldr.SetAttrReachable(symIdx, true)
		if buildcfg.Experiment.FieldTrack && d.ldr.Reachparent[symIdx] == 0 {
			d.ldr.Reachparent[symIdx] = parent
		}
		if *flagDumpDep {

Reachparent is a nice touch: with the FieldTrack experiment on, the linker records which symbol made each symbol live.

Where the method table lives

A method is not a symbol you can point at directly from the type descriptor. The rtype holds an array of reflect.method structs, and each entry has three relocations (mtyp, ifn, tfn). The compiler marks those relocations with a special type, R_METHODOFF, so the linker can find them:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:384
func dmethodptrOff(c rttype.Cursor, x *obj.LSym) {
	c.WriteInt32(0)
	c.Reloc(obj.Reloc{Type: objabi.R_METHODOFF, Sym: x})
}

And the table itself is written into the UncommonType section that follows the common type data:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:345
	c.Field("Mcount").WriteUint16(uint16(mcount))
	c.Field("Xcount").WriteUint16(uint16(xcount))
	c.Field("Moff").WriteUint32(uint32(dataAdd))
	// Note: there is an unused uint32 field here.

	// Write the backing array for the []method field.
	array := rttype.NewArrayCursor(lsym, off+int64(dataAdd), rttype.Method, mcount)
	for i, a := range m {
		exported := types.IsExported(a.name.Name)
		var pkg *types.Pkg
		if !exported && a.name.Pkg != typePkg(t) {
			pkg = a.name.Pkg

Note Mcount (all methods) and Xcount (exported methods). Different numbers, and that distinction is what makes pruning possible: the exported prefix is the part reflection can reach.

The linker sees these relocations while flooding but does not follow them immediately — that would keep every method of every reachable type alive. Instead it records them as “markable”:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:184
			case objabi.R_METHODOFF:
				if i+2 >= relocs.Count() {
					panic("expect three consecutive R_METHODOFF relocs")
				}
				if usedInIface {
					methods = append(methods, methodref{src: symIdx, r: i})
					// The method descriptor is itself a type descriptor, and
					// it can be used to reach other types, e.g. by using
					// reflect.Type.Method(i).Type.In(j). We need to traverse
					// its child types with UsedInIface set. (See also the
					// comment below.)
					rs := r.Sym()
					if !d.ldr.AttrUsedInIface(rs) {
						d.ldr.SetAttrUsedInIface(rs, true)

Two things are happening. The method is only a candidate if its type is “used in interface” — converted to an interface somewhere, so an interface call might dispatch to it. And the method’s own type descriptor is marked reachable, because reflect.Type.Method(i).Type.In(j) reaches types through it.

At the end of the flood, the candidate methods are decoded. The linker reads the method’s name and type straight out of the type descriptor:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:543
func (d *deadcodePass) decodetypeMethods(ldr *loader.Loader, arch *sys.Arch, symIdx loader.Sym, relocs *loader.Relocs) []methodsig {
	p := ldr.Data(symIdx)
	if !decodetypeHasUncommon(arch, p) {
		panic(fmt.Sprintf("no methods on %q", ldr.SymName(symIdx)))
	}
	off := abi.RTypeSize(decodetypeKind(arch, p), arch.PtrSize)

	mcount := int(decodeInuxi(arch, p[off+4:], 2))
	moff := int(decodeInuxi(arch, p[off+4+2+2:], 4))
	off += moff // offset to array of reflect.method values

mcount and moff are read straight out of the UncommonType header the compiler wrote. This is the linker and the compiler agreeing on a binary layout — which is why internal/abi exists, and why the compiler has a separate rttype package mirroring it.

The pruning loop

Pruning is not a single pass, because pruning a method can reveal new interfaces, which keep more methods alive. The loop repeats until the work queue drains:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:455
	for {
		// Mark all methods that could satisfy a discovered
		// interface as reachable. We recheck old marked interfaces
		// as new types (with new methods) may have been discovered
		// in the last pass.
		rem := d.markableMethods[:0]
		for _, m := range d.markableMethods {
			if (d.reflectSeen && (m.isExported() || d.dynlink)) || d.ifaceMethod[m.m] || d.genericIfaceMethod[m.m.name] {
				d.markMethod(m)
			} else {
				rem = append(rem, m)
			}

That single if is the whole method-pruning policy. A candidate method survives if any of these hold:

reflectSeen and the method is exported — reflection could call it.
d.ifaceMethod[m.m] — some reachable interface has a method with the same name and the same function type.
d.genericIfaceMethod[m.m.name] — some reachable generic interface call site named this method.

The matching is by signature, not by implementation. If any reachable interface declares a Read([]byte) (int, error), every interface-used type with a matching method keeps it — even if it could never be assigned to that interface. The comment calls this “extremely conservative, but easy and correct”, and it is: the analysis is linear and cannot drop a live method.

The reflection escape hatch

The third route — reflection — is where the linker gives up, and when it gives up is the single biggest lever on binary size. The compiler sets a flag on the function that does the reflective lookup. If the method name is a compile-time constant, it can emit a precise relocation:

 go
 
 
// src/cmd/compile/internal/walk/expr.go:1140
	if ir.IsConst(targetName, constant.String) {
		name := constant.StringVal(targetName.Val())
		w.curfunc.LSym.AddRel(base.Ctxt, obj.Reloc{
			Type: objabi.R_USENAMEDMETHOD,
			Sym: staticdata.StringSymNoCommon(name),
		})
	} else {
		w.curfunc.LSym.Set(obj.AttrReflectMethod, true)
	}

If the name is not constant, the function gets the REFLECTMETHOD attribute and the linker will keep every exported method of every reachable type. The linker sees this through the loader:

 go
 
 
// src/cmd/link/internal/loader/loader.go:1252
// Returns whether the i-th symbol has ReflectMethod attribute set.
func (l *Loader) IsReflectMethod(i Sym) bool {
	return l.SymAttr(i)&goobj.SymFlagReflectMethod != 0
}

And the flood pass flips a single global boolean the moment it sees one:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:141
		// Methods may be called via reflection. Give up on static analysis,
		// and mark all exported methods of all reachable types as reachable.
		d.reflectSeen = d.reflectSeen || d.ldr.IsReflectMethod(symIdx)

There is a second, sneakier way to get flagged. reflect.Value.Method and reflect.Value.MethodByName are function values, and the compiler flags any function whose address is taken for that purpose:

 go
 
 
// src/cmd/compile/internal/staticdata/data.go:291
		// A function value of reflect.Value.Method or MethodByName may be
		// called with a method name the compiler cannot see; see usemethod.
		if s.Pkg.Path == "reflect" && (s.Name == "Value.Method" || s.Name == "Value.MethodByName") {
			sf.Set(obj.AttrReflectMethod, true)
		}

So even m := reflect.Value.Method; m(v, 3) — where v is not even an interface — turns on “keep every exported method” for the whole binary. A documented cost, and reflect says so out loud:

 go
 
 
// src/reflect/value.go:1895
// Calling this method will force the linker to retain all exported methods in all packages.
// This may make the executable binary larger but will not affect execution time.
func (v Value) Method(i int) Value {

“Will not affect execution time” is the important half. Pruning is a link-time decision that never adds a runtime branch: a binary with all its methods retained runs exactly as fast as one with half of them removed. It is just bigger.

What happens to the pruned methods

Pruned methods are not merely unreferenced — they are actively poisoned. A relocation to a symbol the linker considers unreachable is redirected to a runtime stub that throws:

 go
 
 
// src/cmd/link/internal/ld/data.go:353
		case objabi.R_ADDR, objabi.R_PEIMAGEOFF:
			if weak && !ldr.AttrReachable(rs) {
				// Redirect it to runtime.unreachableMethod, which will throw if called.
				rs = syms.unreachableMethod
			}

And that stub is deliberately loud:

 go
 
 
// src/runtime/iface.go:726
// unreachable to a reference to this function, so it will throw if
// ever called.
func unreachableMethod() {
	throw("unreachable method called. linker bug?")
}

“linker bug?” — because if this fires, the linker was wrong. A canary, not a feature.

The linker also checks itself. Any non-weak relocation to a symbol it believes is unreachable is a hard error:

 go
 
 
// src/cmd/link/internal/ld/data.go:260
		if rs != 0 && rst != sym.STLSBSS && !weak && rt != objabi.R_METHODOFF && !ldr.AttrReachable(rs) {
			st.err.Errorf(s, "unreachable sym in relocation: %s", ldr.SymName(rs))
		}

R_METHODOFF is excluded precisely because those relocations are supposed to point at not-yet-decided methods.

The size effect

A Go binary’s size is dominated by three things: reachable code, type metadata, and debug information. Dead code elimination takes the first. Method pruning takes a slice of the second — a bigger slice than you would think, because a method’s metadata is not just the function body. Each method carries a reflect.method entry, a method wrapper (the ABI0→ABIInternal thunk), a type descriptor for its signature, and its name string. Pruning one method can take five or six objects with it.

The most dramatic size effect is not method pruning at all — it is reflection. A program that calls reflect.Value.MethodByName(name) with a runtime string keeps every exported method of every reachable type in the program. That is the difference between a 4 MB binary and an 11 MB one, and it comes down to a single boolean.

`-w` and `-s`: the other half of the size story

Reachability pruning is about code. Debug information is a separate lever, and a much bigger one for most binaries. The linker has two flags for it:

 go
 
 
// src/cmd/link/internal/ld/main.go:64
	flag.Var(&flagW, "w", "disable DWARF generation")

 go
 
 
// src/cmd/link/internal/ld/main.go:100
	FlagS = flag.Bool("s", false, "disable symbol table")

-s implies -w, which the linker resolves at startup:

 go
 
 
// src/cmd/link/internal/ld/main.go:270
	switch flagW {
	case ternaryFlagFalse:
		*FlagW = false
	case ternaryFlagTrue:
		*FlagW = true
	case ternaryFlagUnset:
		*FlagW = *FlagS // -s implies -w if not explicitly set
		if ctxt.IsDarwin() && ctxt.BuildMode == BuildModeCShared && !*FlagSplitDWARF {

In external-linking mode the same flags are handed down to the host linker as -s or -Wl,-S.

-w short-circuits DWARF generation:

 go
 
 
// src/cmd/link/internal/ld/dwarf.go:1841
func dwarfEnabled(ctxt *Link) bool {
	if *FlagW { // disable dwarf
		return false
	}
	if ctxt.HeadType == objabi.Hplan9 || ctxt.HeadType == objabi.Hjs || ctxt.HeadType == objabi.Hwasip1 {
		return false
	}

The two flags do different things:

Flag	Removes	Kept
`-w`	DWARF debug info: types, variables, line tables, inlined frames	The symbol table — you can still `nm` the binary
`-s`	The symbol table: function and object names	Nothing extra; also implies `-w`

-w is nearly free in production: you lose the debugger and the profiler’s symbolication but keep go tool nm. -s is more aggressive — the symbol table is what objdump, pprof and most crash symbolizers read, and without it your stack traces become raw addresses. The usual production recipe is -ldflags="-s -w", or just -w if you want a profile-able binary.

Trade-offs

What pruning buys: smaller binaries, faster cold starts, less page cache pressure. On a typical service binary the difference between -ldflags="-s -w" and no flags is easily 25-30% of file size.

What it costs:

Reflection is a size cliff. One MethodByName with a runtime string keeps every exported method in the program. This is the single most common cause of “why is my Go binary 10 MB”.
The interface matching is conservative. Any reachable interface with a matching signature keeps that method on every interface-used type, whether or not that type could ever satisfy the interface.
Pruning happens at link time. You pay for the analysis on every link, and the result depends on the whole program, so it cannot be cached per-package.
Stripping symbols breaks tooling. -s removes what pprof, objdump and most error reporters need. You trade observability for bytes.

Caveats

-s and -w are not the same. -w only removes DWARF. The symbol table survives, so go tool nm still works. -s implies -w, and you can negate that with -w=0.

Pruning does not change runtime behaviour, only size. If a reachable method was removed, the linker would have redirected the call to unreachableMethod and thrown “unreachable method called. linker bug?” at runtime. Seeing that panic means the linker is wrong — most likely an unsupported //go:linkname, a plugin, or a -linkshared build.

Shared libraries and plugins disable most of this. A -buildmode=shared library marks every symbol it defines as reachable, and dynamic linking forces reflectSeen = true:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:449
	if ctxt.DynlinkingGo() {
		// Exported methods may satisfy interfaces we don't know
		// about yet when dynamically linking.
		d.reflectSeen = true
	}

The linker catches its own mistakes. Any strong relocation to an unreachable symbol is a link-time error, not a silent corruption.

The reflection escape hatch only keeps exported methods. Unexported methods are never kept by it, because reflect cannot reach them by name either.

Wrapping up

The one thing to remember: the Go linker deletes code you never call. It floods the symbol graph from main.main, follows relocations, and keeps only what it reaches. Everything else never makes it into the binary.

The part people get wrong: the linker cannot see reflection. One reflect.Value.MethodByName with a non-constant argument — or even taking the address of reflect.Value.Method — sets a flag that keeps every exported method of every reachable type in the binary. If your Go binary is inexplicably huge, look there first.

What to go do about it: build with -ldflags="-w" (or -s -w if you do not need a symbolisable binary) and measure. Then run go tool nm -size on the result and look for functions from packages you never imported by hand — net/http, crypto/x509, regexp — and ask whether something in your dependency graph is calling MethodByName.

Go's Inliner: A Budget of 80 Nodes and the Art of the Cheat Sheet

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Every Go function gets an inline budget of 80 IR nodes. Walk the body, subtract one per node, and if you go negative the function is not inlinable — that’s the “function too complex” message. defer, go and tail calls disqualify a function outright, and closures cost 15 nodes. Give the compiler a PGO profile and hot call sites get a budget of 2000 instead of 80.

The single most common question about Go performance is “why isn’t this function being inlined?”. The answer is usually a number: the function is cost 87, and the budget is 80.

That budget is not a guideline. It is a hard number in the compiler source, it has been 80 for well over a decade, and understanding how it is spent is most of what you need to write Go that inlines.

There is also a cheat sheet, and it is literally a table. When the new inliner runs, it can dump every call site in the package with the score it computed, the adjustment it applied, and whether the adjustment promoted or demoted the site. That table is how you find out why a particular call did or did not get inlined, and it is the subject of the second half of this article.

This is a walk through how it works, based on reading the Go 1.28 development tree (src/cmd/compile/internal/inline/).

Two passes, not one

The inliner is split into two halves. The header comment says it plainly:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:5
// The inlining facility makes 2 passes: first CanInline determines which
// functions are suitable for inlining, and for those that are it
// saves a copy of the body. Then InlineCalls walks each function body to
// expand calls to inlinable functions.
//
// The Debug.l flag controls the aggressiveness. Note that main() swaps level 0 and 1,
// making 1 the default and -l disable. Additional levels (beyond -l) may be buggy and
// are not supported.
// 0: disabled
// 1: 80-nodes leaf functions, oneliners, panic, lazy typechecking (default)
// 2: (unassigned)
// 3: (unassigned)
// 4: allow non-leaf functions
//
// At some point this may get another default and become switch-offable with -N.
//
// The -d typcheckinl flag enables early typechecking of all imported bodies,
// which is useful to flush out bugs.
//
// The Debug.m flag enables diagnostic output. a single -m is useful for verifying
// which calls get inlined or not, more is for debugging, and may go away at any point.

So: pass one decides whether a function is inlinable and remembers its cost. Pass two walks each function body and substitutes the bodies of inlinable callees.

The flags are declared in base/flag.go:

 go
 
 
// src/cmd/compile/internal/base/flag.go:74
	LowerL CountFlag "help:\"disable inlining\""
	LowerM CountFlag "help:\"print optimization decisions\""

-l=0 disables inlining entirely. -l=1 is the default. -l=4 allows non-leaf functions (functions that themselves contain calls) to be inlined. -m prints the decisions.

The budget

Here is the whole cost model, in one constant block:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:48
// Inlining budget parameters, gathered in one place
const (
	inlineMaxBudget = 80
	inlineExtraAppendCost = 0
	// default is to inline if there's at most one call. -l=4 overrides this by using 1 instead.
	inlineExtraCallCost = 57 // 57 was benchmarked to provided most benefit with no bad surprises; see https://github.com/golang/go/issues/19348#issuecomment-439370742
	inlineParamCallCost = 17 // calling a parameter only costs this much extra (inlining might expose a constant function)
	inlineExtraPanicCost = 1 // do not penalize inlining panics.
	inlineExtraThrowCost = inlineMaxBudget // with current (2018-05/1.11) code, inlining runtime.throw does not help.

	inlineBigFunctionNodes = 5000 // Functions with this many nodes are considered "big".
	inlineBigFunctionMaxCost = 20 // Max cost of inlinee when inlining into a "big" function.
	inlineClosureCalledOnceCost = 10 * inlineMaxBudget // if a closure is just called once, inline it.
)

The budget arithmetic, in one picture:

 text
 
 
 budget = 80
 |
 | -1 for every IR node
 | -57 for a call to a function that will not be inlined
 | -17 for a call through a function parameter
 | -15 for a closure literal
 | -1 for a panic
 | +2 for &s.f where f is at offset 0
 | +N for refunds from front-end rewrites
 v
 budget < 0 => "function too complex: cost N exceeds budget 80"

That block is worth reading closely, because the numbers encode several years of benchmark-driven decisions.

80 is the base budget. Every IR node costs 1.
57 is the cost of a call to a function the compiler cannot inline itself. The comment links to the issue where 57 was benchmarked. This is the single most important number after 80: a function containing one non-inlinable call has almost no budget left for anything else.
17 is the cheaper cost of a call to a parameter (a function value). Inlining through a parameter can expose a constant function, so it is worth more.
1 is the cost of panic. Panicking is rare and the panic path is cold, so it should not discourage inlining.
80 (the whole budget) is the cost of runtime.throw, because inlining it does not help.

Counting the nodes

The counter is hairyVisitor. It walks the IR tree, subtracting from v.budget as it goes, and returns “too hairy” the moment the budget goes negative:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:476
func (v *hairyVisitor) tooHairy(fn *ir.Func) bool {
	v.do = v.doNode // cache closure
	if ir.DoChildren(fn, v.do) {
		return true
	}
	if v.budget < 0 {
		v.reason = fmt.Sprintf("function too complex: cost %d exceeds budget %d", v.maxBudget-v.budget, v.maxBudget)
		return true
	}
	return false
}

And the per-node charge is at the bottom of doNode:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:831
	v.budget--

	// When debugging, don't stop early, to get full cost of inlining this function
	if v.budget < 0 && base.Flag.LowerM < 2 && !logopt.Enabled() && !v.debug {
		v.reason = "too expensive"
		return true
	}

	return ir.DoChildren(n, v.do)
}

The switch above the v.budget-- handles the special cases. A few examples that show how the model actually behaves:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:703
	case ir.OGO, ir.ODEFER, ir.OTAILCALL:
		v.reason = "unhandled op " + n.Op().String()
		return true

	case ir.OAPPEND:
		v.budget -= inlineExtraAppendCost

	case ir.OADDR:
		n := n.(*ir.AddrExpr)
		// Make "&s.f" cost 0 when f's offset is zero.
		if dot, ok := n.X.(*ir.SelectorExpr); ok && (dot.Op() == ir.ODOT || dot.Op() == ir.ODOTPTR) {
			if _, ok := dot.X.(*ir.Name); ok && dot.Selection.Offset == 0 {
				v.budget += 2 // undo ir.OADDR+ir.ODOT/ir.ODOTPTR
			}
		}

go, defer and tail calls are hard rejects. Not “expensive” — rejected. There is no budget that will let a function containing a defer be inlined at any level.

append is free (cost 0), because inlineExtraAppendCost is 0. Taking the address of a field at offset zero is free, because the address-of and the field access together are worth exactly one node.

There are also refunds. Some constructs get added back to the budget, because they would otherwise distort the measurement:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:771
	case ir.OAS2:
		n := n.(*ir.AssignListStmt)

		// Unified IR unconditionally rewrites:
		//
		//	a, b = f()
		//
		// into:
		//
		//	DCL tmp1
		//	DCL tmp2
		//	tmp1, tmp2 = f()
		//	a, b = tmp1, tmp2
		//
		// so that it can insert implicit conversions as necessary. To
		// minimize impact to the existing inlining heuristics (in
		// particular, to avoid breaking the existing inlinability regress
		// tests), we need to compensate for this here.
		//
		// See also identical logic in IsBigFunc.
		if len(n.Rhs) > 0 {
			if init := n.Rhs[0].Init(); len(init) == 1 {
				if _, ok := init[0].(*ir.AssignListStmt); ok {
					// 4 for each value, because each temporary variable now
					// appears 3 times (DCL, LHS, RHS), plus an extra DCL node.
					//
					// 1 for the extra "tmp1, tmp2 = f()" assignment statement.
					v.budget += 4*int32(len(n.Lhs)) + 1
				}
			}
		}

This is a nice illustration of how the cost model is a proxy. The cost is not “how much machine code will this generate”; it is “how many IR nodes did the front end hand me”, with hand-tuned corrections so that front-end rewrites do not penalise the programmer.

What disqualifies a function outright

Two separate mechanisms. The first is InlineImpossible, which returns a reason string before any costing happens at all:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:347
// InlineImpossible returns a non-empty reason string if fn is impossible to
// inline regardless of cost or contents.
func InlineImpossible(fn *ir.Func) string {
	var reason string // reason, if any, that the function can not be inlined.
	if fn.Nname == nil {
		reason = "no name"
		return reason
	}

	// If marked "go:noinline", don't inline.
	if fn.Pragma&ir.Noinline != 0 {
		reason = "marked go:noinline"
		return reason
	}

The pragma itself is defined in ir/node.go:

 go
 
 
// src/cmd/compile/internal/ir/node.go:435
const (
	// Func pragmas.
	Nointerface PragmaFlag = 1 << iota
	Noescape // func parameters don't escape
	Norace // func must not have race detector annotations
	Nosplit // func should not execute on separate stack
	Noinline // func should not be inlined
	NoCheckPtr // func should not be instrumented by checkptr
	CgoUnsafeArgs // treat a pointer to one arg as a pointer to them all
	UintptrKeepAlive // pointers converted to uintptr must be kept alive
	UintptrEscapes // pointers converted to uintptr escape

//go:noinline is the pragma you will actually use. There is no //go:inline in the compiler: the opt-in direction is handled by a different mechanism entirely (see the source-level inliner section below).

InlineImpossible also blocks functions with //go:uintptrescapes and //go:uintptrkeepalive (because inlining loses the keep-alive information), //go:yeswritebarrierrec, and functions with no body at all.

The second mechanism is the doNode switch, which rejects:

go, defer, tail calls — "unhandled op ...".
Closures, unless the debug flag InlFuncsWithClosures allows them:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:689
	case ir.OCLOSURE:
		if base.Debug.InlFuncsWithClosures == 0 {
			v.reason = "not inlining functions with closures"
			return true
		}

		// TODO(danscales): Maybe make budget proportional to number of closure
		// variables, e.g.:
		//v.budget -= int32(len(n.(*ir.ClosureExpr).Func.ClosureVars) * 3)
		// TODO(austin): However, if we're able to inline this closure into
		// v.curFunc, then we actually pay nothing for the closure captures. We
		// should try to account for that if we're going to account for captures.
		v.budget -= 15

A closure costs 15 nodes. That’s not a rejection, just a chunk of your 80.

Calls to runtime.GetCallerPC and runtime.GetCallerSP, because inlining them would change what the program sees:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:522
				case "internal/runtime/sys":
					switch fn {
					case "GetCallerPC", "GetCallerSP":
						// Functions that call GetCallerPC/SP can not be inlined
						// because users expect the PC/SP of the logical caller,
						// but GetCallerPC/SP returns the physical caller.
						v.reason = "call to " + fn
						return true
					}

deferrangefunc, the helper the compiler synthesises for defer inside a range-over-func.

Note that recover() is allowed to be inlined, but at the full non-leaf call cost of 57:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:684
	case ir.ORECOVER:
		// recover matches panics to frames via stack unwinding
		// (including inlined frames), so it is safe to inline.
		v.budget -= v.extraCallCost

So a function containing recover() has 23 nodes of budget left. That is usually enough for one or two simple statements and nothing more.

Big functions get a smaller budget

If the caller is big, the budget for the callee drops from 80 to 20:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:842
// IsBigFunc reports whether fn is a "big" function.
//
// Note: The criteria for "big" is heuristic and subject to change.
func IsBigFunc(fn *ir.Func) bool {
	budget := inlineBigFunctionNodes
	return ir.Any(fn, func(n ir.Node) bool {

“Big” means more than 5000 IR nodes. The reasoning is straightforward: a 5000-node function is already generating a lot of machine code, and inlining 80 more nodes of callee into it makes the code worse, not better. This exists because issue #26546 and #17566 both asked for it.

PGO: the budget goes to 2000

Now the interesting part. If you build with a profile, the compiler knows which call sites are hot, and hot call sites get a much larger budget.

First, the profile is turned into a set of “hot” call sites. The threshold is not a flat percentage; it is based on the cumulative distribution function of edge weights:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:75
	// Threshold in percentage for hot callsite inlining.
	inlineHotCallSiteThresholdPercent float64

	// Threshold in CDF percentage for hot callsite inlining,
	// that is, for a threshold of X the hottest callsites that
	// make up the top X% of total edge weight will be
	// considered hot for inlining candidates.
	inlineCDFHotCallSiteThresholdPercent = float64(99)

	// Budget increased due to hotness.
	inlineHotMaxBudget int32 = 2000

99% of total edge weight. So the hot set is “the smallest set of call sites that accounts for 99% of the profile’s total weight”. That is a much better rule than “top 100 call sites”, because a profile is usually dominated by a handful of genuinely hot edges.

The CDF is computed here:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:141
// hotNodesFromCDF computes an edge weight threshold and the list of hot
// nodes that make up the given percentage of the CDF. The threshold, as
// a percent, is the lower bound of weight for nodes to be considered hot
// (currently only used in debug prints) (in case of equal weights,
// comparing with the threshold may not accurately reflect which nodes are
// considered hot).
func hotNodesFromCDF(p *pgoir.Profile) (float64, []pgo.NamedCallEdge) {
	cum := int64(0)
	for i, n := range p.NamedEdgeMap.ByWeight {
		w := p.NamedEdgeMap.Weight[n]
		cum += w
		if pgo.WeightInPercentage(cum, p.TotalWeight) > inlineCDFHotCallSiteThresholdPercent {
			// nodes[:i+1] to include the very last node that makes it to go over the threshold.
			// (Say, if the CDF threshold is 50% and one hot node takes 60% of weight, we want to
			// include that node instead of excluding it.)
			return pgo.WeightInPercentage(w, p.TotalWeight), p.NamedEdgeMap.ByWeight[:i+1]
		}
	}
	return 0, p.NamedEdgeMap.ByWeight
}

Then the budget function, which is where 80 becomes 2000:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:201
// inlineBudget determines the max budget for function 'fn' prior to
// analyzing the hairiness of the body of 'fn'. We pass in the pgo
// profile if available (which can change the budget), also a
// 'relaxed' flag, which expands the budget slightly to allow for the
// possibility that a call to the function might have its score
// adjusted downwards. If 'verbose' is set, then print a remark where
// we boost the budget due to PGO.
// Note that inlineCostOK has the final say on whether an inline will
// happen; changes here merely make inlines possible.
func inlineBudget(fn *ir.Func, profile *pgoir.Profile, relaxed bool, verbose bool) int32 {
	// Update the budget for profile-guided inlining.
	budget := int32(inlineMaxBudget)

	budget *= simdCreditMultiplier(fn)

	if strings.HasPrefix(ir.FuncName(fn), "runtime_mapaccess2") &&
		fn.Sym().Pkg.Path == "internal/runtime/maps" {
		// Increase budget for mapaccess2* functions so they could be
		// inlined to mapaccess1* wrappers
		budget = inlineHotMaxBudget
		if verbose {
			fmt.Printf("mapaccess enabled increased budget=%v for func=%v\n", budget, ir.PkgFuncName(fn))
		}
	}

	if IsPgoHotFunc(fn, profile) {
		budget = inlineHotMaxBudget
		if verbose {
			fmt.Printf("hot-node enabled increased budget=%v for func=%v\n", budget, ir.PkgFuncName(fn))
		}
	}
	if relaxed {
		budget += inlheur.BudgetExpansion(inlineMaxBudget)
	}
	if fn.ClosureParent != nil {
		// be very liberal here, if the closure is only called once, the budget is large
		budget = max(budget, inlineClosureCalledOnceCost)
	}

	return budget
}

Three multipliers on top of 80:

SIMD: 3x if the function takes or returns a SIMD vector type, 16x if it captures one. SIMD code is long and the payoff for inlining is large.
Hot: 2000 if the function is a hot callee in the profile.
Closure called once: 800 (10 × 80) if this is a closure.

And crucially, this budget is only about whether a function is eligible. The final decision is per-call-site, and it is stricter:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:978
// inlineCostOK returns true if call n from caller to callee is cheap enough to
// inline. bigCaller indicates that caller is a big function.
//
// In addition to the "cost OK" boolean, it also returns
// - the "max cost" limit used to make the decision (which may differ depending on func size)
// - the score assigned to this specific callsite
// - whether the inlined function is "hot" according to PGO.
func inlineCostOK(n *ir.CallExpr, caller, callee *ir.Func, bigCaller, closureCalledOnce bool) (bool, int32, int32, bool) {
	maxCost := int32(inlineMaxBudget)

and then the hot path:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:1023
	if metric <= maxCost {
		// Simple case. Function is already cheap enough.
		return true, 0, metric, hot
	}

	// We'll also allow inlining of hot functions below inlineHotMaxBudget,
	// but only in small functions.

	if !hot {
		// Cold
		return false, maxCost, metric, false
	}

	// Hot

	if bigCaller {
		if base.Debug.PGODebug > 0 {
			fmt.Printf("hot-big check disallows inlining for call %s (cost %d) at %v in big function %s\n", ir.PkgFuncName(callee), callee.Inl.Cost, ir.Line(n), ir.PkgFuncName(caller))
		}
		return false, maxCost, metric, false
	}

	if metric > inlineHotMaxBudget {
		return false, inlineHotMaxBudget, metric, false
	}

So a hot call site in a small function can be inlined at up to cost 2000. A hot call site in a big function cannot, no matter how hot.

The new inliner: score adjustments

The GOEXPERIMENT=newinliner build changes the cost model from “count nodes” to “count nodes, then adjust the score based on the call site’s context”. It lives in src/cmd/compile/internal/inline/inlheur/.

The idea: the same function should be inlined at one call site and not another. A call in a loop benefits from inlining (the call overhead is paid every iteration). A call on a panic path does not (you are about to die anyway). A call whose argument is a constant benefits (the compiler can then fold a branch). A call passing a concrete type to an interface parameter benefits (the interface call can be devirtualised).

The adjustment table is a list of named bits:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:46
const (
	// Category 1 adjustments (see above)
	panicPathAdj scoreAdjustTyp = (1 << iota)
	initFuncAdj
	inLoopAdj

	// Category 2 adjustments (see above).
	passConstToIfAdj
	passConstToNestedIfAdj
	passConcreteToItfCallAdj
	passConcreteToNestedItfCallAdj
	passFuncToIndCallAdj
	passFuncToNestedIndCallAdj
	passInlinableFuncToIndCallAdj
	passInlinableFuncToNestedIndCallAdj

	// Category 3 adjustments.
	returnFeedsConstToIfAdj
	returnFeedsFuncToIndCallAdj
	returnFeedsInlinableFuncToIndCallAdj
	returnFeedsConcreteToInterfaceCallAdj

	sentinelScoreAdj // sentinel; not a real adjustment
)

and the values, with the compiler’s own admission about them:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:71
// This table records the specific values we use to adjust call
// site scores in a given scenario.
// NOTE: these numbers are chosen very arbitrarily; ideally
// we will go through some sort of turning process to decide
// what value for each one produces the best performance.

var adjValues = map[scoreAdjustTyp]int{
	panicPathAdj: 40,
	initFuncAdj: 20,
	inLoopAdj: -5,
	passConstToIfAdj: -20,
	passConstToNestedIfAdj: -15,
	passConcreteToItfCallAdj: -30,
	passConcreteToNestedItfCallAdj: -25,
	passFuncToIndCallAdj: -25,
	passFuncToNestedIndCallAdj: -20,
	passInlinableFuncToIndCallAdj: -45,
	passInlinableFuncToNestedIndCallAdj: -40,
	returnFeedsConstToIfAdj: -15,
	returnFeedsFuncToIndCallAdj: -25,
	returnFeedsInlinableFuncToIndCallAdj: -40,
	returnFeedsConcreteToInterfaceCallAdj: -25,
}

Negative numbers mean “promote” (inline it anyway), positive means “demote”. A call in a loop gets -5. A call on a panic path gets +40, which effectively disqualifies it.

The scoring itself starts from the raw cost and applies the adjustments:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:193
func (cs *CallSite) computeCallSiteScore(csa *callSiteAnalyzer, calleeProps *FuncProps) {
	callee := cs.Callee
	csflags := cs.Flags
	call := cs.Call

	// Start with the size-based score for the callee.
	score := int(callee.Inl.Cost)
	var tmask scoreAdjustTyp

There is a subtlety with the budget: the new inliner does not know at CanInline time whether a score will later be adjusted downwards, so it starts with a relaxed budget:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:582
// BudgetExpansion returns the amount to relax/expand the base
// inlining budget when the new inliner is turned on; the inliner
// will add the returned value to the hairiness budget.
//
// Background: with the new inliner, the score for a given callsite
// can be adjusted down by some amount due to heuristics, however we
// won't know whether this is going to happen until much later after
// the CanInline call. This function returns the amount to relax the
// budget initially (to allow for a large score adjustment); later on
// in RevisitInlinability we'll look at each individual function to
// demote it if needed.
func BudgetExpansion(maxBudget int32) int32 {
	if base.Debug.InlBudgetSlack != 0 {
		return int32(base.Debug.InlBudgetSlack)
	}
	// In the default case, return maxBudget, which will effectively
	// double the budget from 80 to 160; this should be good enough
	// for most cases.
	return maxBudget
}

80 becomes 160 under the new inliner, so that a function whose score will be knocked down by -45 still fits.

The experiment flag itself is:

 go
 
 
// src/internal/goexperiment/flags.go:99
	// NewInliner enables a new+improved version of the function
	// inlining phase within the Go compiler.
	NewInliner bool

and the inlheur package is enabled exactly when that experiment is on (or when the debug dumping flags are set):

 go
 
 
// src/cmd/compile/internal/inline/inlheur/analyze.go:217
func Enabled() bool {
	return buildcfg.Experiment.NewInliner || UnitTesting()
}

You can see the whole scoring model in action with a debug dump:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:605
// DumpInlCallSiteScores is invoked by the inliner if the debug flag
// "-d=dumpinlcallsitescores" is set; it dumps out a human-readable
// summary of all (potentially) inlinable callsites in the package,
// along with info on call site scoring and the adjustments made to a
// given score. Here profile is the PGO profile in use (may be
// nil), budgetCallback is a callback that can be invoked to find out
// the original pre-adjustment hairiness limit for the function, and
// inlineHotMaxBudget is the constant of the same name used in the
// inliner. Sample output lines:
//
// Score Adjustment Status Callee CallerPos ScoreFlags
// 115 40 DEMOTED cmd/compile/internal/abi.(*ABIParamAssignment).Offset expand_calls.go:1679:14|6 panicPathAdj
// 76 -5n PROMOTED runtime.persistentalloc mcheckmark.go:48:45|3 inLoopAdj
// 201 0 --- PGO unicode.DecodeRuneInString utf8.go:312:30|1
// 7 -5 --- PGO internal/abi.Name.DataChecked type.go:625:22|0 inLoopAdj

“PROMOTED” and “DEMOTED” are the two outcomes. A promoted site was above the budget on raw cost but the adjustment brought it under.

The source-level inliner: `//go:fix inline`

There is a second, completely separate inliner in the Go tree, and it is not part of cmd/compile at all. It lives in the vendored x/tools and is driven by the go fix tool.

The directive is //go:fix inline, and it marks a function as a candidate for source-level inlining — the compiler rewrites your source, not your machine code:

 go
 
 
// src/go/types/signature.go:57
//go:fix inline
func NewSignature(recv *Var, params, results *Tuple, variadic bool) *Signature {
	return NewSignatureType(recv, nil, nil, params, results, variadic)
}

The machinery that finds these directives is gofixdirective:

 go
 
 
// src/cmd/vendor/golang.org/x/tools/go/analysis/passes/internal/gofixdirective/gofixdirective.go:1
// Package gofixdirective searches for and validates go:fix directives. The
// go/analysis/passes/inline package uses findgofix to perform inlining.
// The go/analysis/passes/gofix package uses findgofix to check for problems
// with go:fix directives.
//
// gofixdirective is separate from gofix to avoid depending on refactor/inline,
// which is large.
package gofixdirective

And the analyzer that performs the inlining:

 go
 
 
// src/cmd/vendor/golang.org/x/tools/go/analysis/passes/inline/inline.go:36
var Analyzer = &analysis.Analyzer{
	Name: "inline",
	Doc: analyzerutil.MustExtractDoc(doc, "inline"),
	URL: "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/inline",
	Run: run,
	FactTypes: []analysis.Fact{
		(*goFixInlineFuncFact)(nil),
		(*goFixInlineConstFact)(nil),
		(*goFixInlineAliasFact)(nil),
	},
	Requires: []*analysis.Analyzer{
		inspect.Analyzer,
		typeindexanalyzer.Analyzer,
	},
}

This is a genuinely different design. cmd/compile’s inliner is a cost-budget decision made per call site during compilation, invisible in the source. The go fix inliner is a source transformation that bakes the inlined body into your file permanently, so it can inline across package boundaries and across type-parameter instantiations — things the compiler’s inliner cannot do.

The modernize analyzer adds these directives automatically when it finds a wrapper function that could be inlined:

 go
 
 
// src/cmd/vendor/golang.org/x/tools/go/analysis/passes/modernize/newexpr.go:91
								// Add a //go:fix inline annotation, if not already present.
								//
								// The inliner will not inline a newer callee body into an
								// older Go file; see https://go.dev/issue/75726.
								if !slices.ContainsFunc(astutil.Directives(decl.Doc), func(d ast.Directive) bool {
									return d.Tool == "go" && d.Name == "fix" && d.Args == "inline"
								}) {
									edits = append(edits, analysis.TextEdit{
										Pos: decl.Pos(),
										End: decl.Pos(),
										NewText: []byte("//go:fix inline\n"),
									})
								}

Note the constraint in that comment: the inliner will not inline a newer callee body into an older Go file. The source-level inliner respects the language version of the file it is rewriting.

Reading the diagnostics

go build -gcflags=-m prints the decisions:

 text
 
 
./main.go:10:6: can inline f with cost 34 as: func(i int) int { ... }
./main.go:20:6: cannot inline g: function too complex: cost 102 exceeds budget 80
./main.go:30:6: inlining call to f

The cost number is the number you are trying to reduce. A few practical notes:

The cost is per function, not per call site (except under PGO and the new inliner).
A cost just over 80 (say 85) usually means one non-inlinable call (57) plus a bit of body. Refactoring that call out usually fixes it.
Cost under 80 does not guarantee inlining. The call site must also pass the recursion check and the other canInlineCallExpr conditions.
-m=2 gives more detail, including the “cannot inline” reason.

Trade-offs

What inlining buys you: the ability to constant-fold, to propagate constants into the callee, to eliminate dead code, to devirtualise an interface call that becomes concrete after inlining the callee, and to avoid the call overhead entirely.

What it costs you: code size, and compile time. Inlining a 60-node function into 20 call sites produces 20 copies of that code. The budget exists to bound exactly this.

Why the budget is a count of IR nodes and not a count of instructions: IR nodes are what the front end produced, which is a stable quantity the compiler can compute without running the backend. It is a proxy, and the refund cases (OAS2, OADDR at offset 0) exist because the proxy drifts from reality.

Why hotness helps so much: the cost of inlining is paid at compile time and in binary size, but the benefit is paid at runtime, only on the paths that actually execute. A profile tells you which call sites are on the hot path, so you can spend code size where it pays.

Why PGO inlining is restricted to small callers: the point of PGO inlining is to remove overhead from a hot loop. A 5000-node function is not a hot loop; it is a big chunk of code where an extra copy of a callee is pure bloat.

Caveats

The budget is not a guarantee. A function with cost 40 might still not be inlined if the call site is inside a recursive cycle, or if the callee is a closure whose captured variables come from another closure frame.

//go:noinline is a blunt instrument. It blocks inlining of that function entirely, everywhere, including in the runtime and in the standard library’s hot paths. Use it when the function is genuinely large or when inlining it would change semantics (for example, a function that must keep its own stack frame for runtime.Callers).

The m output is not stable. The Go project explicitly says that -m beyond a single -m “may go away at any point”. Do not write tests that depend on the exact wording of the “cannot inline” message. The project does, however, maintain a list of functions that are intended to be inlinable, and TestIntendedInlining in src/cmd/compile/internal/test/inl_test.go checks that list by parsing the -m output.

The 128 KiB MaxStackVarSize and the inliner’s budget are unrelated. Inlining a function that allocates a big local makes the caller’s frame bigger, and there is a separate limit on frame size. The inliner does not check it; the backend does.

The new inliner’s numbers are explicitly arbitrary. The comment in adjValues says so. They are benchmark-derived but not principled, and they will change.

PGO inlining only applies to the top 99% of edge weight. If your profile is noisy, or your program has many equally-hot call sites, the hot set can be large and the code-size benefit shrinks.

Wrapping up

The one thing to remember: the inliner charges one unit per IR node against a budget of 80, and a call to a function it cannot inline costs 57 of those units. If your function is “too complex”, the culprit is almost always one non-inlinable call.

The part people get wrong: inlining is decided per function in the default build, so making a function cheaper to inline helps every call site, but it also means a function that is hot at one call site and cold at fifty others is judged entirely on its own cost. That is what PGO and the new inliner’s score adjustments exist to fix.

What to go do about it: run go build -gcflags=-m and look at the cost of the functions you expected to be inlined. If a cost is just over 80, find the call inside it that is not itself inlinable and break that dependency. If the function is genuinely hot, build with -pgo=./default.pgo and let the profile lift the ceiling from 80 to 2000.

Go's Generics: Dictionary Passing, Shape Stenciling and GC Shape

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go does not monomorphise generics. It writes one copy of a generic function per shape – the underlying type of the type argument – and passes the concrete runtime types to that copy in a flat dictionary of machine words. The shape is also the GC contract: two instantiations may share code only if their shapes agree about where the pointers are.

Generics in Go are the rare language feature whose implementation is mostly not in the runtime. The runtime does not know what a type parameter is. The compiler does all the work, and it does it in three moves: decide which instantiations can share code, emit that shared code once, and hand the remaining type-specific facts to the shared code in a side channel.

This is a walk through how it works in the Go 1.28 development tree, based on reading src/cmd/compile/internal/noder/, src/cmd/compile/internal/types/, and src/internal/abi/.

What the runtime knows about generics: nothing

Start with the runtime type descriptor. This is the structure every Go type has at runtime, and it is the first place to look for evidence of type parameters:

 go
 
 
// src/internal/abi/type.go:21
type Type struct {
	Size_ uintptr
	PtrBytes uintptr // number of (prefix) bytes in the type that can contain pointers
	Hash uint32 // hash of type; avoids computation in hash tables
	TFlag TFlag // extra type information flags
	Align_ uint8 // alignment of variable with this type
	FieldAlign_ uint8 // alignment of struct field with this type
	Kind_ Kind // what kind of type this is (string, int, ...)
	// function for comparing objects of this type
	// (ptr to object A, ptr to object B) -> ==?
	Equal func(unsafe.Pointer, unsafe.Pointer) bool
	// GCData stores the GC type data for the garbage collector.
	// Normally, GCData points to a bitmask that describes the
	// ptr/nonptr fields of the type. The bitmask will have at
	// least PtrBytes/ptrSize bits.
	// If the TFlagGCMaskOnDemand bit is set, GCData is instead a
	// **byte and the pointer to the bitmask is one dereference away.
	// The runtime will build the bitmask if needed.
	// (See runtime/type.go:getGCMask.)
	// Note: multiple types may have the same value of GCData,
	// including when TFlagGCMaskOnDemand is set. The types will, of course,
	// have the same pointer layout (but not necessarily the same size).
	GCData *byte
	Str NameOff // string form
	PtrToThis TypeOff // type for pointer to this type, may be zero
}

There is no field for type arguments. No TypeParams, no Dict, no TypeArgs. That is the single most important fact about Go’s generics implementation in this tree, and it drives everything else:

The runtime cannot recover T from a value of type T.
reflect cannot ask a type what its type arguments were.
A generic function that needs the concrete type of T at run time has to get it from the dictionary the compiler hands it.

What the runtime can do is store a pointer to a type descriptor, and a type descriptor is exactly what a dictionary entry holds.

Shapes

The compiler’s unit of code sharing is called a shape. The compiler’s type package carries two flags for it:

 go
 
 
// src/cmd/compile/internal/types/type.go:227
const (
	typeNotInHeap = 1 << iota // type cannot be heap allocated
	typeNoalg // suppress hash and eq algorithm generation
	typeDeferwidth // width computation has been deferred and type is on deferredTypeStack
	typeRecur
	typeIsShape // represents a set of closely related types, for generics
	typeHasShape // there is a shape somewhere in the type
	// typeIsFullyInstantiated reports whether a type is fully instantiated generic type; i.e.
	// an instantiated generic type where all type arguments are non-generic or fully instantiated generic types.
	typeIsFullyInstantiated
	typeIsSIMDTag // type is the SIMD marker type
	typeIsSIMD // type contains the SIMD marker type
	typeMethodsComputed
)

“Represents a set of closely related types”. That is the whole idea: a shape is a stand-in for a family of types that the generated code cannot tell apart.

Shapes are not real types. They live in a fake package that the compiler invents:

 go
 
 
// src/cmd/compile/internal/types/type.go:1995
// Fake package for shape types (see typecheck.Shapify()).
var ShapePkg = NewPkg("go.shape", "go.shape")

and a type declared in that package is a shape by definition:

 go
 
 
// src/cmd/compile/internal/types/type.go:1642
func NewNamed(obj Object) *Type {
	t := newType(TFORW)
	t.obj = obj
	sym := obj.Sym()
	if sym.Pkg == ShapePkg {
		t.SetIsShape(true)
		t.SetHasShape(true)
	}

How a shape is computed

Shapify is the function that decides which type argument becomes which shape:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:960
// Shapify returns the shape type for targ.
//
// If basic is true, then the type argument is used to instantiate a
// type parameter whose constraint is a basic interface.
func Shapify(targ *types.Type, basic bool) *types.Type {

and then the rule itself:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:987
	// When a pointer type is used to instantiate a type parameter
	// constrained by a basic interface, we know the pointer's element
	// type can't matter to the generated code. In this case, we can use
	// an arbitrary pointer type as the shape type. (To match the
	// non-unified frontend, we use `*byte`.)
	//
	// Otherwise, we simply use the type's underlying type as its shape.
	//
	// TODO(mdempsky): It should be possible to do much more aggressive
	// shaping still; e.g., collapsing all pointer-shaped types into a
	// common type, collapsing scalars of the same size/alignment into a
	// common type, recursively shaping the element types of composite
	// types, and discarding struct field names and tags. However, we'll
	// need to start tracking how type parameters are actually used to
	// implement some of these optimizations.
	under := targ.Underlying()
	if basic && targ.IsPtr() && !targ.Elem().NotInHeap() {
		under = types.NewPtr(types.Types[types.TUINT8])
	}

Read the TODO. It says out loud what the rule is not doing: it is not collapsing scalars of the same size, and it is not collapsing pointer-shaped types in general. The shape of a type argument is its underlying type, with one exception: if the type parameter’s constraint is a basic interface (an any-like constraint with no methods), then any pointer argument collapses to *byte, because in that case the compiler knows the pointee type cannot affect the generated code.

The shape then gets a name in the fake package, and that name is the shape’s identity:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1007
	// Hash long type names to bound symbol name length seen by users,
	// particularly for large protobuf structs (#65030).
	uls := under.LinkString()
	if base.Debug.MaxShapeLen != 0 &&
		len(uls) > base.Debug.MaxShapeLen {
		h := hash.Sum32([]byte(uls))
		uls = hex.EncodeToString(h[:])
	}

	sym := types.ShapePkg.Lookup(uls)
	if sym.Def == nil {
		name := ir.NewDeclNameAt(under.Pos(), ir.OTYPE, sym)
		typ := types.NewNamed(name)
		typ.SetUnderlying(under)
		sym.Def = typed(typ, name)
	}
	res := sym.Def.Type()
	assert(res.IsShape())
	assert(res.HasShape())
	return res

So f[int] and f[int64] have shapes go.shape.int and go.shape.int64: different shapes, therefore different stenciled code. f[*int] and f[*string] under an any constraint both have shape go.shape.*byte: one copy of the code, shared.

This is a real change from the design Go shipped in 1.18, where shapes were computed by a “gcshape” unification that lumped int, int32 and int64 together because they have the same size and the same GC layout. The gcshape machinery is gone from this tree; what remains is the underlying type, plus the pointer collapse.

Sharing code is only safe if the compiler can prove the two instantiations behave identically. The compiler’s type-identity check has a special case for shapes:

 go
 
 
// src/cmd/compile/internal/types/identity.go:12
// Identical reports whether t1 and t2 are identical types, following the spec rules.
// Receiver parameter types are ignored. Named (defined) types are only equal if they
// are pointer-equal - i.e. there must be a unique types.Type for each specific named
// type. Also, a type containing a shape type is considered identical to another type
// (shape or not) if their underlying types are the same, or they are both pointers.
func Identical(t1, t2 *Type) bool {
	return identical(t1, t2, 0, nil)
}

“their underlying types are the same, or they are both pointers”. That is the GC-shape rule in one sentence: two types may share code if their memory layouts agree, and pointers always agree with pointers.

And in the body:

 go
 
 
// src/cmd/compile/internal/types/identity.go:45
	if t1.obj != nil || t2.obj != nil {
		if flags&identStrict == 0 && (t1.HasShape() || t2.HasShape()) {
			switch t1.kind {
			case TINT8, TUINT8, TINT16, TUINT16, TINT32, TUINT32, TINT64, TUINT64, TINT, TUINT, TUINTPTR, TCOMPLEX64, TCOMPLEX128, TFLOAT32, TFLOAT64, TBOOL, TSTRING, TPTR, TUNSAFEPTR:
				return true
			}

Every scalar and every pointer kind is treated as identical when a shape is involved. That is what lets f[int] and f[int64] be interchangeable as far as the compiler’s shape analysis is concerned – while the dictionary keeps the concrete types straight at runtime.

The dictionary

The shape handles everything the generated code can treat as uniform. What is left – the concrete runtime type of the type argument, the itab for a conversion, a method expression on a type parameter – has to be supplied at run time. That supply is the dictionary.

The dictionary is not a runtime type. In this tree it is a compiler-defined global variable, an array of machine words, and the shaped function takes a pointer to it as an extra argument:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1626
// varType returns the type of dict's runtime dictionary variable.
func (dict *readerDict) varType() *types.Type {
	return types.NewArray(types.Types[types.TUINTPTR], dict.numWords())
}

and the shaped function’s signature gets the dictionary parameter:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:4337
// shapeSig returns a copy of fn's signature, except adding a
// dictionary parameter and promoting the receiver parameter (if any)
// to a normal parameter.
//
// The parameter types.Fields are all copied too, so their Nname
// fields can be initialized for use by the shape function.
//
// All signatures returned by shapeSig are marked as shaped.
func shapeSig(fn *ir.Func, dict *readerDict) *types.Type {
	sig := fn.Nname.Type()
	oldRecv := sig.Recv()

	var recv *types.Field
	if oldRecv != nil {
		recv = types.NewField(oldRecv.Pos, oldRecv.Sym, oldRecv.Type)
	}

	params := make([]*types.Field, 1+sig.NumParams())
	params[0] = types.NewField(fn.Pos(), fn.Sym().Pkg.Lookup(dictParamName), types.NewPtr(dict.varType()))

The parameter is a pointer, so under the register ABI it travels in a register, not on the stack. The parameter’s name is .dict, and the runtime tooling knows about it:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:4330
// dictParamName is the name of the synthetic dictionary parameter
// added to shaped functions.
//
// N.B., this variable name is known to Delve:
// https://github.com/go-delve/delve/blob/cb91509630529e6055be845688fd21eb89ae8714/pkg/proc/eval.go#L28
const dictParamName = typecheck.LocalDictName

The dictionary’s layout

The dictionary is a flat array of words with four sections:

 text
 
 
 dictionary (a global [N]uintptr)
 +--------------------------------------------------+
 | type param method exprs | func pointers |
 +--------------------------------------------------+
 | subdictionaries | pointers to other dicts|
 +--------------------------------------------------+
 | rtypes | *runtime._type pointers|
 +--------------------------------------------------+
 | itabs | *runtime.itab pointers |
 +--------------------------------------------------+

The section offsets are computed by four tiny functions:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1596
// typeParamMethodExprsOffset returns the offset of the runtime
// dictionary's type parameter method expressions section, in words.
func (dict *readerDict) typeParamMethodExprsOffset() int {
	return 0
}

// subdictsOffset returns the offset of the runtime dictionary's
// subdictionary section, in words.
func (dict *readerDict) subdictsOffset() int {
	return dict.typeParamMethodExprsOffset() + len(dict.typeParamMethodExprs)
}

// rtypesOffset returns the offset of the runtime dictionary's rtypes
// section, in words.
func (dict *readerDict) rtypesOffset() int {
	return dict.subdictsOffset() + len(dict.subdicts)
}

// itabsOffset returns the offset of the runtime dictionary's itabs
// section, in words.
func (dict *readerDict) itabsOffset() int {
	return dict.rtypesOffset() + len(dict.rtypes)
}

and the writer fills them in, in order, with an assertion that each section starts where the previous one ended:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1534
	assertOffset := func(section string, offset int) {
		base.AssertfAt(ot == offset*types.PtrSize, pos, "writing section %v at offset %v, but it should be at %v*%v", section, ot, offset, types.PtrSize)
	}

	assertOffset("type param method exprs", dict.typeParamMethodExprsOffset())
	for _, info := range dict.typeParamMethodExprs {
		typeParam := dict.targs[info.typeParamIdx]
		method := typecheck.NewMethodExpr(pos, typeParam, info.method)

		rsym := method.FuncName().Linksym()
		assert(rsym.ABI() == obj.ABIInternal) // must be ABIInternal; see ir.OCFUNC in ssagen/ssa.go

		ot = objw.SymPtr(lsym, ot, rsym, 0)
	}

	assertOffset("subdictionaries", dict.subdictsOffset())

The rtypes section is the important one. It holds *runtime._type pointers, and for a shaped function one of those entries is the runtime type of the type argument itself:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1560
	assertOffset("rtypes", dict.rtypesOffset())
	for _, info := range dict.rtypes {
		typ := pr.typIdx(info, dict, true)
		ot = objw.SymPtr(lsym, ot, reflectdata.TypeLinksym(typ), 0)

		// TODO(mdempsky): Double check this.
		reflectdata.MarkTypeUsedInInterface(typ, lsym)
	}

The itabs section is the other one. An itab is the runtime table that maps a concrete type to the code for an interface’s methods, and a generic function that converts its type argument to an interface needs one:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1569
	// For each (typ, iface) pair, we write the *runtime.itab pointer
	// for the pair. For pairs that don't actually require an itab
	// (i.e., typ is an interface, or iface is an empty interface), we
	// write a nil pointer instead. This is wasteful, but rare in
	// practice (e.g., instantiating a type parameter with an interface
	// type).
	assertOffset("itabs", dict.itabsOffset())
	for _, info := range dict.itabs {
		typ := pr.typIdx(info.typ, dict, true)
		iface := pr.typIdx(info.iface, dict, true)

		if !typ.IsInterface() && iface.IsInterface() && !iface.IsEmptyInterface() {
			ot = objw.SymPtr(lsym, ot, reflectdata.ITabLsym(typ, iface), 0)
		} else {
			ot += types.PtrSize
		}

The dictionary’s own name is a global symbol with a fixed prefix:

 go
 
 
// src/cmd/internal/objabi/util.go:17
	GlobalDictPrefix = ".dict" // prefix for names of global dictionaries

so you will see .dict.f[int] and friends in a symbol dump.

How the dictionary reaches the shaped function

A concrete instantiation of a generic function is a thin wrapper. Its body is synthesised as a tail call to the shaped function, passing the dictionary:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1441
	// If this function has type parameters and isn't shaped, then we
	// just tail call its corresponding shaped variant.
	if r.hasTypeParams() && !r.dict.shaped {
		r.callShaped(pos)
		return true
	}

and the call itself:

 go
 
 
// src/cmd/compile/internal/noder/reader.go:1470
	// Construct the arguments list: receiver (if any), then runtime
	// dictionary, and finally normal parameters.
	//
	// Note: For simplicity, shaped methods are added as normal methods
	// on their shaped types. So existing code (e.g., packages ir and
	// typecheck) expects the shaped type to appear as the receiver
	// parameter (or first parameter, as a method expression). Hence
	// putting the dictionary parameter after that is the least invasive
	// solution at the moment.
	var args ir.Nodes
	if r.methodSym != nil {
		args.Append(params[0])
		params = params[1:]
	}
	args.Append(typecheck.Expr(r.curfn, ir.NewAddrExpr(pos, r.p.dictNameOf(r.dict))))
	args.Append(params...)

	r.syntheticTailCall(pos, shapedFn, args)

So the call chain for f[int] looks like this:

 text
 
 
 caller
 | call f[int] (a wrapper)
 v
 f[int] <- tail call, dictionary in a register
 | call f[go.shape.int] with &.dict.f[int]
 v
 f[go.shape.int] <- the shared code
 | loads .dict.f[int] to find the concrete *runtime._type
 v
 work

The dictionary is a global, so it costs nothing to pass: one pointer, in a register.

Where the shape and the GC meet

Everything above is about code sharing. What makes it safe to share is that the shape determines the memory layout of the stenciled code, and therefore its GC pointer map.

The shape type is a real named type with a real underlying type, so it has a real GC bitmap. The stenciled function’s frame is laid out according to the shape, and the compiler emits the pointer map for the shape, not for the concrete type argument. That is only correct if every instantiation sharing that shape agrees on where the pointers are – and the shape rules guarantee exactly that:

Two type arguments with the same underlying type obviously have the same layout.
Two pointer type arguments both have the same layout: one word, one pointer.

The pointer collapse to *byte is the extreme case of the second rule. When the constraint is a basic interface, the compiler may not know the pointee type, but it does know the value is one pointer, so all pointer arguments collapse to one shape and therefore to one copy of the code.

The compiler’s own type-identity rule encodes the same thing, as we saw: underlying types equal, or both pointers.

Reflect and generics

Because the runtime type descriptor has no type-argument field, reflect cannot recover the type arguments of an instantiated generic type. What it can do is hand you the type descriptor of a concrete type argument, and it does that with a trick:

 go
 
 
// src/internal/abi/type.go:192
// TypeFor returns the abi.Type for a type parameter.
func TypeFor[T any]() *Type {
	return (*PtrType)(unsafe.Pointer(TypeOf((*T)(nil)))).Elem
}

TypeOf((*T)(nil)) boxes a nil *T into an any, and the compiler has statically emitted the type descriptor for that conversion. The reflect package wraps it:

 go
 
 
// src/reflect/type.go:1395
// TypeFor returns the [Type] that represents the type argument T.
func TypeFor[T any]() Type {
	// toRType is safe to use here; type is never nil as T is statically known.
	return toRType(abi.TypeFor[T]())
}

Note “T is statically known”. reflect.TypeFor is itself generic, so the compiler instantiates it once per type argument, and each instantiation has its own statically-known descriptor. There is no dictionary involved: this is the fully-instantiated path.

For an instantiated generic type – List[int] rather than a type parameter – the compiler emits a separate type descriptor per instantiation, because the layouts differ:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:1394
	case typ.IsFullyInstantiated():
		// Instantiated type; possibly instantiated with unique type arguments.
		// Need to emit to be safe (however, see TODO above).
		return true

so List[int] and List[string] are distinguishable at runtime by pointer comparison, even though the runtime cannot enumerate int and string from the descriptor.

Trade-offs

What shape stenciling buys: one copy of the code for a family of instantiations. A generic container written once serves []int and []string with the same machine code, and the binary does not grow with the number of instantiations.

What it costs: every operation that depends on the concrete type has to be deferred to run time. Converting the type argument to an interface inside a generic function needs the itab, which is a dictionary lookup; a type switch on the type argument needs the runtime type, which is another dictionary lookup; and the compiler cannot devirtualise a method call on a shape type:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:72
	// If typ is a shape type, then it was a type argument originally
	// and we'd need an indirect call through the dictionary anyway.
	// We're unable to devirtualize this call.
	if typ.IsShape() {
		return
	}

What monomorphisation would have bought instead: direct calls, direct itabs, direct type descriptors, and no dictionary at all. What it would have cost: a copy of the code per instantiation, which is exactly the explosion Go’s designers were trying to avoid.

The dictionary itself is cheap but not free. It is a global, so it costs binary size (one word per entry) and one pointer-sized argument per call. A generic function that never needs a concrete type at run time ends up with a dictionary of zero words, which is still a pointer-sized argument.

Caveats

The runtime does not know your type arguments. There is no reflect.Type.TypeArgs, and internal/abi.Type has no field for them. If your code needs the type arguments at run time, you have to carry them yourself.

Sharing depends on the shape, and the shape is the underlying type. f[int] and f[int64] do not share code in this tree. f[*int] and f[*string] share code only when the type parameter’s constraint is a basic interface; with a method-bearing constraint the pointer type is kept and the shapes differ.

A pointer collapse to *byte means the pointee type is invisible. The compiler only does this when it can prove the pointee does not affect the generated code, which is why it requires a basic constraint.

A defer in a generic function is still a defer. The shape machinery does not change how defers, panics or recovers work; the defer’s closure simply lives in a shared function.

Method calls on a type parameter are indirect. The devirtualiser gives up on shape types, so x.Method() inside a generic function is a call through a pointer, not a direct call.

The dictionary’s layout is an implementation detail. It is a flat array of words with four sections, computed by four offset functions, and the sections are filled in by the compiler. Nothing in the runtime knows about it, which means nothing in the runtime can help you debug it.

Instantiated generic types get their own type descriptors. List[int] and List[string] are different runtime types, with different descriptors and different names. That is a binary-size cost paid per instantiation.

Wrapping up

The one thing to remember: Go shares generic code per shape, and the shape of a type argument is its underlying type, with pointer arguments collapsing to *byte under a basic constraint. f[int] and f[int64] get separate code; f[*int] and f[*string] share it.

The part people get wrong: the runtime is not involved in generics at all. There is no runtime dictionary type, no type arguments in internal/abi.Type, and no way to recover T from a value at run time. Everything is a compiler decision, communicated to the shared code through a flat array of machine words.

What to go do about it: read Shapify in src/cmd/compile/internal/noder/reader.go and the four *Offset functions just below it. Together they are the entire specification of what shares code and what does not, and they are much shorter than the design document you are imagining.

Go's Experimental SIMD Package: Vector Registers Without Assembly

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go now has a SIMD package. simd.Int8s and friends are portable vector types that the compiler lowers to real VPADDD instructions in the SSA backend. A source-to-source rewrite pass called “midway” specialises your code per vector width and picks one at runtime.

Writing SIMD in Go used to mean one of three things: assembly files, cgo, or a //go:linkname into a C library. All three are unpleasant in different ways, and all three put a wall between you and the compiler’s optimiser.

The Go team’s answer has been in development for a while, and in the Go 1.28 development tree it has taken shape as a real package with real compiler support. This is a walk through how it works, based on reading that tree.

Where the code lives now

The project has moved a couple of times, and if you have been following it you may remember internal/simd with types like simd.Int8x16. In the current tree the layout is:

Path	What it is
`src/simd/`	The portable package. Length-agnostic vector types (`Int8s`, `Float32s`, `Mask8s`, …). Works on every platform.
`src/simd/archsimd/`	The platform package. Fixed-width types (`Int8x16` … `Float64x8`) plus scalable types on SVE. Contents vary by GOARCH.
`src/simd/internal/spec/`	The executable specification. Buildable Go, but not meant to be called directly.
`src/simd/internal/simdref/`	Reference implementation of the API, generated from spec.
`src/simd/internal/bridge/`	Glue between `simd` and `archsimd`. Generated, not user-visible.
`src/internal/simd/variants/`	The variant table, shared between the generator and the compiler.

Everything is behind a build tag:

 go
 
 
// src/simd/doc.go:7
/*
Package simd implements portable and vector-size-agnostic SIMD types,
and functions and methods for working with these types. SIMD types
are either implemented in hardware (for example, arm64 "Neon" or
amd64 "AVX/AVX2/AVX512") using the corresponding types in the
[simd/archsimd] package, or emulated in pure Go. In all cases, the
vector length is at least 128 bits, and within a given program
execution, all vectors have the same length.

and behind a toolchain experiment:

 go
 
 
// src/internal/goexperiment/exp_simd_on.go:7
const SIMD = true
const SIMDInt = 1

So today you would build a toolchain with GOEXPERIMENT=simd and then import "simd". The package is at the top level of the standard library rather than under internal/, which is the visible shape of the plan to make it public. The api/ directory in the tree has no simd entries yet, so it is not part of the compatibility promise.

Two layers of types

The first thing to understand is that there are two different kinds of vector type, and they exist for different reasons.

simd/archsimd types are fixed width. Int8x16 is always sixteen int8s, Float64x4 is always four float64s, and they map one-to-one onto what the hardware can do:

 go
 
 
// src/simd/archsimd/types_amd64.go:92
// Int8x16 is a 128-bit SIMD vector of 16 int8s.
//
// CPU Feature: AVX
type Int8x16 struct {
	int8x16 v128
	vals [16]int8
}

// Len returns the number of elements in an Int8x16.
func (x Int8x16) Len() int { return 16 }

// LoadInt8x16Array loads an array into a vector.
//
//go:noescape
func LoadInt8x16Array(x *[16]int8) (z Int8x16)

// StoreArray stores the elements of x to an array.
//
//go:noescape
func (x Int8x16) StoreArray(y *[16]int8)

Note the structure. v128 is a zero-sized marker whose only job is to make the struct uncomparable:

 go
 
 
// src/simd/archsimd/types_amd64.go:8
type v128 struct {
	_128 [0]func() // uncomparable
}

The real payload is vals [16]int8. The compiler’s intrinsics treat these structs as vector-register values directly; there is no copying of the array into and out of a register, because the SSA backend has a register class for them.

simd types are scalable. Int8s is “a vector of int8s, of whatever width this machine is running”. The API is the intersection of everything the architectures can do:

 go
 
 
// src/simd/simd_stubs.go:9
// LoadInt8s loads a slice into a vector. If len(s) < z.Len(), it panics.
func LoadInt8s(s []int8) (z Int8s)

// LoadInt8sPart loads n=min(len(s), z.Len()) elements from slice s as a
// vector and returns the vector and n. If len(s) < z.Len(), the
// remaining vector elements will be zero.
func LoadInt8sPart(s []int8) (z Int8s, n int)

// BroadcastInt8s returns a vector with the input x assigned to all elements of the
// result.
func BroadcastInt8s(x int8) (z Int8s)

The scalable type is a plain struct of two words:

 go
 
 
// src/simd/simd_types.go:14
// Int8s represents a vector of 8-bit signed integers.
type Int8s struct {
	_ _simd
	a, b uint64 // the actual vector size may be larger.
}

A vector is at least 128 bits, so two uint64s is the floor. On a machine with 512-bit vectors the same type carries four words’ worth.

The “one meaning” rule

The generators enforce a rule that is worth quoting, because it explains why the API looks the way it does. From the generator README:

One name means one thing. A name need not exist on every platform or in both packages, but wherever it does exist it must denote the same operation, with the same signature and the same semantics.

And the consequence:

The simd package API is the intersection of the archsimd package APIs across all architectures, after generalizing fixed-width to scalable width, plus a few methods for querying emulation behavior.

So simd.Float32s.Add and archsimd.Float32x4.Add are the same operation. The simd package is not a hand-written convenience layer over archsimd; it is computed from the intersection of the per-architecture APIs, which is why src/simd/simd_stubs.go is a generated file with no logic in it at all.

How the compiler knows an operation is a vector op

Here is the part that makes it “not assembly”. A method on a vector type is declared with no body at all:

 go
 
 
// src/simd/archsimd/ops_amd64.go:283
// Add adds x and y elementwise.
//
//	z[i] = x[i] + y[i]
//
// Asm: VPADDD, CPU Feature: AVX
func (x Int32x4) Add(y Int32x4) (z Int32x4)

The // Asm: and // CPU Feature: comments are consumed by the generator, not by the compiler. The compiler learns about the method from a table of intrinsics:

 go
 
 
// src/cmd/compile/internal/ssagen/simdAMD64intrinsics.go:40
	addF(simdPackage, "Float32x4.Add", opLen2(ssaop.OpAddFloat32x4, types.TypeVec128), sys.AMD64)

simdPackage is literally the import path:

 go
 
 
// src/cmd/compile/internal/ssagen/intrinsics.go:1875
const simdPackage = "simd/archsimd"

So the compiler hard-codes the knowledge that simd/archsimd.Float32x4.Add should become the SSA opcode AddFloat32x4, whose result type is TypeVec128.

The vector “types” in the SSA backend are new:

 go
 
 
// src/cmd/compile/internal/types/type.go:1615
	TypeVec128 = newSIMD("vec128")
	TypeVec256 = newSIMD("vec256")
	TypeVec512 = newSIMD("vec512")
	TypeMask = newSIMD("mask") // not a vector, not 100% sure what this should be.

with widths and alignments assigned at init time:

 go
 
 
// src/cmd/compile/internal/types/type.go:1626
	TypeVec128.width = 16
	TypeVec128.align = 8
	TypeVec256.width = 32
	TypeVec256.align = 8
	TypeVec512.width = 64
	TypeVec512.align = 8

And then there is a machine opcode per width, generated from the same source as the intrinsics table:

 go
 
 
// src/cmd/compile/internal/ssa/_gen/simdAMD64ops.go:315
		{name: "VPADDD128", argLength: 2, reg: v21, asm: "VPADDD", commutative: true, typ: "Vec128"},
		{name: "VPADDD256", argLength: 2, reg: v21, asm: "VPADDD", commutative: true, typ: "Vec256"},
		{name: "VPADDD512", argLength: 2, reg: w21, asm: "VPADDD", commutative: true, typ: "Vec512"},

v21 and w21 are register classes: v21 means “two vector inputs, one vector output”, w21 is the same but for the wider register file. The asm: field is the actual instruction mnemonic the assembler will emit.

The lowering rules

The link between the abstract operation and the machine instruction is a rewrite rule, and the SIMD rules are in their own file:

 go
 
 
// src/cmd/compile/internal/ssa/_gen/simdAMD64.rules:41
(AddInt32x4 ...) => (VPADDD128 ...) // pureVreg

Read that as: “an AddInt32x4 operation becomes a VPADDD128 operation, and the result lives purely in a vector register”. The ... means “all arguments pass through unchanged”. There are three thousand six hundred lines of these, one per (operation, width) pair.

The rules also encode the clever bits — load folding, mask merging, and feature gating:

 go
 
 
// src/cmd/compile/internal/ssa/_gen/simdAMD64.rules:1477
(VMOVDQU32Masked128 (VPADDD128 x y) mask) => (VPADDDMasked128 x y mask)

 go
 
 
// src/cmd/compile/internal/ssa/_gen/simdAMD64.rules:2212
(VPBLENDVB128 dst (VPADDD128 x y) mask) && v.Block.CPUfeatures.HasFeature(ssa.CPUavx512) => (VPADDDMasked128Merging dst x y (VPMOVVec32x4ToM <types.TypeMask> mask))

Note the v.Block.CPUfeatures.HasFeature(...) guard: the same Go source compiles to different instructions depending on the CPU features of the machine being compiled for. This is how Go gets AVX-512 masked operations on a machine that has AVX-512, and a different sequence on one that does not, without any assembly and without any runtime dispatch in the common case.

Now the hard part: the width is not known at compile time

A portable vector type has no fixed width. simd.Int8s might be 16 bytes on one machine and 64 bytes on another. That is fine as long as the compiler knows which one to emit — but it does not, until runtime.

Go’s solution is a source-to-source rewrite pass that runs before type checking, in the compiler’s “midway” phase. From the rewriteer’s own documentation:

Go attempts to provide a package similar to the “Highway” library for C++ (https://google.github.io/highway). The library package is “simd” and defines vector types with unspecified widths that are bound to particular machine dependent types as late as program execution. This is accomplished by rewriting code that depends on these types into code that references architecture-specific types, perhaps more than once, and if necessary dynamically choosing which version to execute based on hardware attributes.

So the pipeline is:

 text
 
 
 your source: func f(x simd.Int8s) simd.Int8s { return x.Add(y) }
 |
 v
 midway rewrite: f is specialised per width
 |
 +-------------+-------------+
 | | |
 f@simd128 f@simd256 f@simd512 (archsimd.Int8x16, etc.)
 | | |
 +-------------+-------------+
 |
 v
 f: switch simd.VectorSize() { case 128: ... case 256: ... }
 |
 v
 compiler intrinsics: f@simd128 calls archsimd.Int8x16.Add
 |
 v
 SSA: AddInt8x16 => VPADDB128

The rewrite happens after type checking but before conversion to unified IR, and then the type checker is re-run. The rewriter’s comment says why that is the chosen point:

The rewriting takes place early in the compiler, after type checking but before conversion to “unified” IR. To ensure that types are correctly set on the modified version of the code, type checking information is reset and the type checking phase is re-run. This places some limits on the shape of the rewrites, but it also ensures that the rewritten code is well-formed.

The rewriter also has to avoid rewriting the archsimd package itself, and it introduces a bridge package so that the rewritten code does not reference archsimd types directly — the compiler’s export-data naming rules would otherwise reject it:

Rewritten code does not reference “archsimd” types directly, but instead references types in a “bridge” package that filters the available methods and adds a few more.

Variants: the CPU that has most of an instruction set

Now the interesting wrinkle. Suppose your CPU has AVX2 but not AVX-512. Or, on arm64, has NEON but not the carryless-multiply instruction — which is exactly the case for Raspberry Pi.

The naive answer is “fall back to emulation”. The better answer, which Go implements, is a variant: a second implementation of the same operations that emulates only the missing instructions, keeping everything else in hardware.

The variant table is tiny and lives in a package shared between the code generator and the compiler:

 go
 
 
// src/internal/simd/variants/variants.go:28
type Key struct {
	Arch string
	Size int
}

type Variant struct {
	Suffix string // the name (suffix) for this variant.
	Emulated map[string]bool // Methods that are emulated for this variant.
	DefaultRequires string // default requires this function return true, false means variant.
}

// Name returns the variant name of type t.
// If receiver v is nil, returns t.
func (v *Variant) Name(t string) string {
	if v == nil {
		return t
	}
	return t + v.Suffix
}

var Variants map[Key]*Variant

func init() {
	Variants = make(map[Key]*Variant)
	Variants[Key{"arm64", 128}] = &Variant{
		Suffix: "nclm",
		Emulated: map[string]bool{
			"CarrylessMultiplyEven": true,
			"CarrylessMultiplyOdd": true,
		},
		DefaultRequires: "HasHardwareCarrylessMultiply",
	}

}

One variant today: arm64 at 128 bits, suffix nclm (no carryless multiply), which emulates exactly two methods, and which is used when HasHardwareCarrylessMultiply() returns false.

The rewriter uses this table to build the dispatch function. Here is the code that decides what the case 128: arm of the generated switch looks like:

 go
 
 
// src/cmd/compile/internal/midway/rewrite.go:446
		// if this architecture and size has a variant, then guard
		// the regular case call with variant.require
		// and then follow it with the variant case.
		// `if simd.<require>() { callReturnStmt }`
		if v := variants.Variants[variants.Key{Arch: buildcfg.GOARCH, Size: k}]; v != nil {
			callReturnStmt = guardCallWithCondition(v.DefaultRequires, callReturnStmt)
			caseBody = append(caseBody, callReturnStmt)
			callReturnStmt = makeCallReturnStmt(k, v.Suffix)
		}

		caseBody = append(caseBody, callReturnStmt)

So the generated dispatcher for a function on arm64 ends up roughly like:

 go
 
 
switch simd.VectorSize() {
case 128:
 if simd.HasHardwareCarrylessMultiply() {
 return f@simd128(args)
 }
 return f@simd128nclm(args)
case 256:
 return f@simd256(args)
}

The HasHardwareCarrylessMultiply predicate is a runtime value:

 go
 
 
// src/simd/midway_common.go:178
// HasHardwareCarrylessMultiply returns whether this platform
// has a hardware-implemented version of carryless multiply.
// With default GODEBUG=simd settings, if this is false,
// it is emulated and merely slow, but with non-default settings
// this can indicate the possibility of a missing instruction
// that will fail ("SIGILL") if it is executed.
func HasHardwareCarrylessMultiply() bool {
	return hwClmul && archHasHwClmul
}

Choosing the width at runtime

The width decision happens once, at package init time, based on CPU feature detection:

 go
 
 
// src/simd/midway_amd64.go:16
func archMaxVectorSize() (size, allFeatureSize int, arch string) {
	arch = "amd64"
	if archsimd.X86.AVX() {
		size = 128
		allFeatureSize = 128
	}
	if archsimd.X86.AVX2() {
		size = 256
		if cpu.X86.HasVPCLMULQDQ {
			allFeatureSize = 256
		}
	}
	if archsimd.X86.AVX512() {
		size = 512
		if cpu.X86.HasAVX512VPCLMULQDQ {
			allFeatureSize = 512
		}
	}
	return
}

Note the two returned numbers. size is the widest vector the CPU can do. allFeatureSize is the widest width at which the CPU has every feature the SIMD API needs — here, the carryless-multiply instruction that allFeatureSize keeps bumping down. If the CPU has AVX-512 but not VPCLMULQDQ, you get 512-bit vectors but you also get a variant, because some operations have to be emulated.

The feature detection itself is a plain wrapper over internal/cpu:

 go
 
 
// src/simd/archsimd/cpu.go:31
// AVX512 returns whether the CPU supports the AVX512F+CD+BW+DQ+VL features.
//
// These five CPU features are bundled together, and no use of AVX-512
// is allowed unless all of these features are supported together.
// Nearly every CPU that has shipped with any support for AVX-512 has
// supported all five of these features.
//
// If it returns true, then the CPU also supports AVX and AVX2.
//
// AVX512 is defined on all GOARCHes, but will only return true on
// GOARCH amd64.
func (X86Features) AVX512() bool {
	return cpu.X86.HasAVX512
}

The GODEBUG knob

Because the width and the emulation decision are made at runtime, they need a knob for testing. GODEBUG=simd=N requests a specific width (128, 256 or 512), GODEBUG=simd=0 requests pure emulation even on hardware that can do better, and a + prefix skips the feature check:

 go
 
 
// src/simd/midway_common.go:90
	} else if len(gosimd) > 0 && gosimd[0] == '@' {
		// For testing, allow specification of a desired variant.
		// If there is one for this architecture and size, it should work.
		// This is not, currently, intended for everyday use.
		key := variants.Key{Arch: arch, Size: maxVectorSize}
		if v, ok := variants.Variants[key]; ok {
			// there is a variant at this size, just reset hwClmul
			hwClmul = false
			if v.Name("") != gosimd[1:] {
				panic(fmt.Errorf("requested variant %s but obtained variant %s", gosimd[1:], v.Name("")))
			}
			return maxVectorSize, emulated, hwClmul
		}
		panic(fmt.Errorf("requested variant %s but no variant was available", gosimd[1:]))

GODEBUG=simd=@nclm asks for the Raspberry Pi variant explicitly. That is the kind of escape hatch you want when a new CPU turns out to be missing something the feature detection did not anticipate.

Trade-offs

What you get:

Real vector instructions from Go source. No assembly files, no cgo, no build tags per architecture.
Portable code that adapts. The same source runs on AVX, AVX2, AVX-512, NEON, SVE and wasm, and picks the best width at runtime.
Full participation in the compiler. Vector values are SSA values, so they go through the same register allocation, spilling and inlining as everything else.
Graceful degradation. Missing instructions become emulated operations, not a crash.

What it costs:

A source-to-source rewrite pass. Every function that mentions a SIMD type gets duplicated per width. Compile time and binary size both go up.
A runtime dispatch. The generated switch on the vector size is a branch on every call to a boundary function, unless the compiler can prove the size is constant.
A fragile experimental surface. The package is behind GOEXPERIMENT=simd and is not in the API promise files.
A lot of generated code. Three thousand six hundred lines of rewrite rules for amd64 alone, plus the arm64, arm64-SVE and wasm equivalents.

Caveats

This is an experiment, not a release. GOEXPERIMENT=simd is required. Without it, the package does not build. The api/ files list nothing about simd, so nothing about its shape is frozen.

There are open bugs, listed in the package doc itself:

 go
 
 
// src/simd/doc.go:89
// BUG(reflection): Calls won't work, and there may be other bugs.
// BUG(global initialization): SIMD-dependent var initializers don't work.
// BUG(modified names): Modified names may appear in stack traces and debugging.

That last one is worth understanding: because the rewriter renames functions by appending @simd128 and friends, the names in your stack traces and debug information are not the names you wrote.

Emulation is not always fast. A 512-bit vector emulated in pure Go is slower than a scalar loop written by a human, because the emulation still goes through the generic vector machinery.

The width is fixed for the lifetime of the process. The decision is made at init time. You cannot change it later, and GODEBUG=simd=256 on a machine that only has AVX will panic with a clear message rather than silently downgrading.

The simd and archsimd types are not interchangeable. ToArch() and Int8sFromArch exist for converting between them, and the latter panics if the correspondence is wrong.

The API is the intersection, which means it is the weakest common denominator. An operation that is cheap on one architecture and awkward on another may simply not be in the portable package at all.

Wrapping up

The one thing to remember: Go’s SIMD is two packages and a compiler pass. simd gives you length-agnostic types, simd/archsimd gives you the fixed-width ones that map onto real instructions, and the “midway” rewrite turns your portable code into a set of width-specialised functions plus a runtime dispatcher.

The part people get wrong: the width is not chosen by the compiler and it is not chosen by your build flags. It is chosen at program startup from CPU feature detection, and it can change between two runs of the same binary on two different machines. Code that assumes a particular vector width is wrong.

What to go do about it: build a toolchain with GOEXPERIMENT=simd and write a loop that processes eight int32s at a time, then check the generated assembly. If the numbers are not better than the scalar version, the loop was probably not the bottleneck — and you have learned that for free, without writing a single line of assembly.

Go Passes Arguments in Registers: The Register ABI and Its Transparent Wrappers

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go has two calling conventions. ABI0 is the old stack-based one that assembly code must use, and it is frozen forever. ABIInternal is the one every function written in Go actually uses: arguments and results go in machine registers, with a fixed register holding the current goroutine pointer and another fixed to zero. Because both worlds have to coexist, the compiler generates transparent wrappers that translate one convention into the other — you never write them, but they are why a hand-written assembly routine can still be called from Go without costing you a stack shuffle.

Every Go program you have ever written calls functions through an ABI you have probably never thought about. And for most of Go’s life, that ABI put every argument on the stack.

Then Go 1.17 changed the rules. The change is invisible from Go source — no syntax changed, no semantics changed — but it is one of the largest performance-relevant redesigns the language has ever done, and the source tree documents it in unusual detail.

Two ABIs, and why there are two

The distinction is baked into the object file format. From src/cmd/internal/obj/link.go:

 go
 
 
// src/cmd/internal/obj/link.go:843
// ABI is the calling convention of a text symbol.
type ABI uint8

const (
	// ABI0 is the stable stack-based ABI. It's important that the
	// value of this is "0": we can't distinguish between
	// references to data and ABI0 text symbols in assembly code,
	// and hence this doesn't distinguish between symbols without
	// an ABI and text symbols with ABI0.
	ABI0 ABI = iota

	// ABIInternal is the internal ABI that may change between Go
	// versions. All Go functions use the internal ABI and the
	// compiler generates wrappers for calls to and from other
	// ABIs.
	ABIInternal

	ABICount
)

Read that comment carefully, because it contains a whole design constraint in four lines: ABI0 must have the value zero, because the linker and the assembler need to tell “this symbol is a data symbol” apart from “this symbol is a text symbol with the default ABI”. Anything else would require an extra bit in every relocation.

So the two ABIs have asymmetric properties on purpose:

ABI0 is stable. It is the contract with hand-written assembly, with the runtime’s own assembly, with the debugger, and with anything that pokes at a Go stack frame. It will not change. Ever.
ABIInternal is unstable. It is free to change between Go releases because only the compiler and the runtime, which ship together, depend on it.

The tree says exactly this in src/cmd/compile/abi-internal.md:

This document describes Go’s internal application binary interface (ABI), known as ABIInternal. Go’s ABI defines the layout of data in memory and the conventions for calling between Go functions. This ABI is unstable and will change between Go versions. If you’re writing assembly code, please instead refer to Go’s assembly documentation, which describes Go’s stable ABI, known as ABI0.

The register assignment algorithm

ABIInternal is a common ABI across all architectures — the same algorithm runs everywhere, only the register sequences differ. The algorithm, straight out of the spec, breaks arguments and results down recursively into base values and hands them out in order:

If T is a boolean or integral type that fits in an integer register, assign V to register I and increment I.

If T is an integral type that fits in two integer registers, assign the least significant and most significant halves of V to registers I and I+1, respectively, and increment I by 2

If T is a floating-point type and can be represented without loss of precision in a floating-point register, assign V to register FP and increment FP.

If T is a complex type, recursively register-assign its real and imaginary parts.

If T is a pointer type, map type, channel type, or function type, assign V to register I and increment I.

If T is a string type, interface type, or slice type, recursively register-assign V’s components (2 for strings and interfaces, 3 for slices).

If T is a struct type, recursively register-assign each field of V.

If T is an array type of length 0, do nothing.

If T is an array type of length 1, recursively register-assign its one element.

If T is an array type of length > 1, fail.

If I > NI or FP > NFP, fail.

If any recursive assignment above fails, fail.

Two details there are worth dwelling on.

A string costs two registers. A slice costs three. Not because the pointer and the length are physically separate, but because the ABI treats them as separate base values and each gets its own register. The same is true of an interface: the itab pointer and the data pointer are two independent register assignments.

An array of more than one element fails. A [2]uintptr cannot be register-assigned at all, so it goes on the stack — the entire array, not just its second word. This is a subtle and frequently surprising rule. It also means an array is not a first-class citizen in the ABI: it is either entirely in registers (length 1) or entirely on the stack.

The failure mode is graceful. If any recursive assignment fails, the whole value is reassigned to the stack:

Try to register-assign V.

If step 3 failed, reset I and FP to the values from step 1, add T to the stack sequence S, and assign V to this field in S.

Note the “reset I and FP” — a failed attempt does not burn registers.

The stack frame layout

Arguments that could not be register-assigned live on the stack, and the layout is not the obvious one. From the spec:

The final stack sequence looks like: stack-assigned receiver, stack-assigned arguments, pointer-alignment, stack-assigned results, pointer-alignment, spill space for each register-assigned argument, pointer-alignment.

So a call frame looks like this, with the arrow pointing at lower addresses:

 text
 
 
 +------------------------------+
 | . . . |
 | 2nd reg argument spill space |
 | 1st reg argument spill space |
 | <pointer-sized alignment> |
 | . . . |
 | 2nd stack-assigned result |
 | 1st stack-assigned result |
 | <pointer-sized alignment> |
 | 2nd stack-assigned argument |
 | 1st stack-assigned argument |
 | stack-assigned receiver |
 +------------------------------+

Two things jump out.

Results are stored on the stack too, below the arguments. The caller has to reserve space for the results before making the call, because it does not know the callee’s stack frame size. So the caller reserves the result slots, and the callee writes into them.

Every register-assigned argument gets a spill slot. The caller reserves space for these but leaves them uninitialized. The callee may spill an argument to its own frame, but if it wants to spill to the caller’s frame (the classic “callee-saved register” trick) the space is already there. This is why the ABI has no callee-save registers at all:

There are no callee-save registers, so a call may overwrite any register that doesn’t have a fixed meaning, including argument registers.

That is a genuinely radical choice. It removes the entire save/restore choreography from the call sequence, at the cost of the caller having to reserve spill space it might never use. On a modern OoO core the spilled slot is usually still in L1 by the time it is needed, so the trade usually wins.

Fixed registers: the goroutine pointer and the zero register

On amd64 the integer register sequence is nine registers:

The amd64 architecture uses the following sequence of 9 registers for integer arguments and results:
RAX, RBX, RCX, RDI, RSI, R8, R9, R10, R11
It uses X0 – X14 for floating-point arguments and results.

Nine, not fifteen. On x86-64 there are fifteen usable GPRs, but RSP is the stack pointer, RBP is the frame pointer, and three more are reserved as scratch. The scratch reservation is explained in the spec:

Registers R12 and R13 are permanent scratch registers. R15 is a scratch register except in dynamically linked binaries.

Rationale: Some operations such as stack growth and reflection calls need dedicated scratch registers in order to manipulate call frames without corrupting arguments or results.

That is a real constraint, not a stylistic one: runtime.morestack has to move the whole argument area of the frame it is growing, and it has to do so without a scratch register it is allowed to clobber.

And then there are the two famous fixed registers:

Register	Call meaning	Return meaning	Body meaning
R14	Current goroutine	Same	Same
X15	Zero value (*)	Same	Scratch

R14 always holds the current goroutine pointer. This is the single most important consequence of the register ABI for everyday Go code. Before Go 1.17, every function that touched getg() had to make a TLS lookup — a memory load, potentially a function call, definitely a cache miss on the TLS block. Now g is just a register.

Look at how the runtime maintains it. When the runtime switches to a different goroutine’s stack it reloads R14:

 asm
 
 
// src/runtime/asm_amd64.s:1086
	MOVQ	SI, R14 // set the g register, as required by ABIInternal.
	XORPS	X15, X15 // clear X15, as required by ABIInternal.

Two instructions on every goroutine switch. That is the entire cost of the fixed-register convention, and it replaces a TLS lookup in every function that needs g.

X15 is always zero. The rationale is given:

Rationale: We designate X15 as a fixed zero register because functions often have to bulk zero their stack frames, and this is more efficient with a designated zero register.

Go zeroes stack frames when a function has pointer-containing locals that the GC might otherwise see as garbage. With a dedicated zero register, the zeroing becomes a MOVUPS from a known-zero source rather than a PXOR against itself plus a store — one fewer instruction on the dependency chain, and the store can be a plain vector store.

The wrappers: how two worlds coexist

Here is the interesting engineering. Assembly code in the runtime (and in third-party packages like github.com/bytedance/sonic) is written against ABI0. Go code calls it. The compiler bridges the gap automatically.

From src/cmd/compile/internal/ssagen/abi.go:

 go
 
 
// src/cmd/compile/internal/ssagen/abi.go:286
	// ABI0-to-ABIInternal wrappers will be mainly loading params from
	// stack into registers (and/or storing stack locations back to
	// registers after the wrapped call); in most cases they won't
	// need to allocate stack space, so it should be OK to mark them
	// as NOSPLIT in these cases. In addition, my assumption is that
	// functions written in assembly are NOSPLIT in most (but not all)
	// cases. In the case of an ABIInternal target that has too many
	// parameters to fit into registers, the wrapper would need to
	// allocate stack space, but this seems like an unlikely scenario.
	// Hence: mark these wrappers NOSPLIT.
	//
	// ABIInternal-to-ABI0 wrappers on the other hand will be taking
	// things in registers and pushing them onto the stack prior to
	// the ABI0 call, meaning that they will always need to allocate
	// stack space. If the compiler marks them as NOSPLIT this seems
	// as though it could lead to situations where the linker's
	// nosplit-overflow analysis would trigger a link failure. On the
	// other hand if they not tagged NOSPLIT then this could cause
	// problems when building the runtime (since there may be calls to
	// asm routine in cases where it's not safe to grow the stack). In
	// most cases the wrapper would be (in effect) inlined, but are
	// there (perhaps) indirect calls from the runtime that could run
	// into trouble here.
	// FIXME: at the moment all.bash does not pass when I leave out
	// NOSPLIT for these wrappers, so all are currently tagged with NOSPLIT.
	fn.Pragma |= ir.Nosplit

That comment is a fossil of a real debugging session, and it tells you the whole story: the wrapper-generation code has subtleties that were discovered by running the full test suite.

Then there is the tail-call optimisation, with an architecture-specific carve-out:

 go
 
 
// src/cmd/compile/internal/ssagen/abi.go:328
	if base.Ctxt.Arch.Name == "amd64" && wrapperABI == obj.ABIInternal {
		// cannot tailcall from ABIInternal to ABI0 on AMD64, as we need
		// to special registers (X15) when returning to ABIInternal.
		tailcall = false
	}

A tail call would be perfect: no frame, no return address, minimal cost. But on amd64, returning from an ABI0 function to an ABIInternal caller requires restoring X15 (the zero register) to zero, and you cannot do that after a JMP because there is no return point to execute it at. So the wrapper has to be a real call with a real frame.

The same file has a similar carve-out for ppc64 with dynamic linking, where the link register R2 must be restored.

`RegArgs`: the assembly-facing view

Assembly code that wants to participate in ABIInternal needs to know where the registers are. That is the job of internal/abi.RegArgs:

 go
 
 
// src/internal/abi/abi.go:21
type RegArgs struct {
	// Values in these slots should be precisely the bit-by-bit
	// representation of how they would appear in a register.
	//
	// This means that on big endian arches, integer values should
	// be in the top bits of the slot. Floats are usually just
	// directly represented, but some architectures treat narrow
	// width floating point values specially (e.g. they're promoted
	// first, or they need to be NaN-boxed).
	Ints [IntArgRegs]uintptr // untyped integer registers
	Floats [FloatArgRegs]uint64 // untyped float registers

	// Fields above this point are known to assembly.

	// Ptrs is a space that duplicates Ints but with pointer type,
	// used to make pointers passed or returned in registers
	// visible to the GC by making the type unsafe.Pointer.
	Ptrs [IntArgRegs]unsafe.Pointer

	// ReturnIsPtr is a bitmap that indicates which registers
	// contain or will contain pointers on the return path from
	// a reflectcall. The i'th bit indicates whether the i'th
	// register contains or will contain a valid Go pointer.
	ReturnIsPtr IntArgRegBitmap
}

The Ptrs field is a small, very clever hack. The GC scans the argument registers of a goroutine’s stack when the goroutine is scanned or when it transitions to a syscall. Those registers hold integers of unknown provenance. If the GC treated every register as an integer, it would miss pointers passed in registers and could collect live objects.

The trick: RegArgs has two copies of the integer registers — Ints as plain uintptr, and Ptrs as unsafe.Pointer. The Ptrs copy has pointer type, so the GC’s stack map sees it as pointers and scans it correctly. The Ints copy is what the code actually reads. Two arrays, one extra field per register, and the GC problem disappears.

The comment “Fields above this point are known to assembly” is the compiler-ABI contract: the assembly in src/runtime/asm_amd64.s and the RegArgs struct layout must agree, and the compiler enforces it.

How many registers, per architecture

The register counts are per-architecture constants:

 go
 
 
// src/internal/abi/abi_amd64.go:7
const (
	// See abi_generic.go.

	// RAX, RBX, RCX, RDI, RSI, R8, R9, R10, R11.
	IntArgRegs = 9

	// X0 -> X14.
	FloatArgRegs = 15

	// We use SSE2 registers which support 64-bit float operations.
	EffectiveFloatRegSize = 8
)

 go
 
 
// src/internal/abi/abi_arm64.go:7
const (
	// See abi_generic.go.

	// R0 - R15.
	IntArgRegs = 16

	// F0 - F15.
	FloatArgRegs = 16

	EffectiveFloatRegSize = 8
)

And for platforms that did not get the register ABI, there is a graceful degradation path:

 go
 
 
// src/internal/abi/abi_generic.go:5
//go:build !goexperiment.regabiargs && !amd64 && !arm64 && !loong64 && !ppc64 && !ppc64le && !riscv64 && !s390x

package abi

const (
	// ABI-related constants.
	//
	// In the generic case, these are all zero
	// which lets them gracefully degrade to ABI0.

	// IntArgRegs is the number of registers dedicated
	// to passing integer argument values. Result registers are identical
	// to argument registers, so this number is used for those too.
	IntArgRegs = 0

	// FloatArgRegs is the number of registers dedicated
	// to passing floating-point argument values. Result registers are
	// identical to argument registers, so this number is used for
	// those too.
	FloatArgRegs = 0

	// EffectiveFloatRegSize describes the width of floating point
	// registers on the current platform from the ABI's perspective.
	//
	// Since Go only supports 32-bit and 64-bit floating point primitives,
	// this number should be either 0, 4, or 8. 0 indicates no floating
	// point registers for the ABI or that floating point values will be
	// passed via the softfloat ABI.
	//
	// For platforms that support larger floating point register widths,
	// such as x87's 80-bit "registers" (not that we support x87 currently),
	// use 8.
	EffectiveFloatRegSize = 0
)

Zero registers means “everything goes on the stack” — ABI0 behaviour, with no separate code path. The whole ABI machinery collapses to a no-op on platforms that did not adopt it. That is the kind of design decision that makes a big change shippable: the fallback is not a maintenance burden, it is the absence of one.

Why the register ABI was worth doing

The register ABI is not just about saving a few stores. It removes an entire class of work from every call:

No argument shuffling through the stack. An old-style call wrote each argument to a stack slot, then the callee read it back. With registers, that round trip disappears for the first nine integer arguments.
No callee-save register discipline. Because there are no callee-save registers, there is no push/pop prologue epilogue for the compiler to emit.
g in a register. The goroutine pointer is available without a TLS lookup. This is the single biggest win: it makes runtime.getg — called by the scheduler, by the allocator, by anything that touches the heap — essentially free.
A fixed zero register. Frame zeroing gets cheaper.
Better register allocation. The SSA backend’s register allocator starts with the argument registers already live, which gives it a natural place to put incoming values.

The costs are equally real:

Assembly became harder to write. You now have to know which ABI you are targeting, and mixing them requires the wrappers.
The ABI can change. ABIInternal is explicitly unstable. A Go release can change how arguments are passed, and your assembly — if it targets ABIInternal — breaks. This is why the tree pushes assembly authors to ABI0.
Debuggers have to know about it. A stack frame in ABIInternal is not laid out like an ABI0 frame, so unwinding code has to be ABI-aware.

Trade-offs

Register ABI vs stack ABI. Registers win on the call overhead and on g access. The stack wins on ABI stability and on debuggability. Go took both: registers for Go code, stack for assembly.

Common ABI vs platform ABI. Go invented its own convention rather than using the platform’s (System V AMD64, AAPCS64). The cost is that Go assembly is not compatible with anything else, and every call crossing the Go/C boundary needs a wrapper. The benefit is uniformity: one spec, one implementation, and the same register-assignment algorithm everywhere, so a compiler change fixes all platforms at once.

No callee-save registers. This is the most counter-intuitive choice in the whole design, and the one that pays off the most on modern hardware. The cost is reserved spill space in every frame — memory that is often never touched. The benefit is a call sequence with nothing to save and nothing to restore.

Fixed registers. R14 for g and X15 for zero cost two registers out of the general pool on amd64, which is why only nine integer registers remain for arguments. The benefit is that the two most-frequently-needed values are free.

Caveats

You almost certainly should not write assembly. If you do, target ABI0, not ABIInternal. ABI0 is stable across Go releases; ABIInternal is not. The tree says so explicitly, and the //go:linkname “hall of shame” comments in src/runtime/map.go are a good illustration of how much trouble hand-written linkage causes.

Register assignment is not free of surprises. Arrays longer than one element go on the stack. Structs are flattened field-by-field, so a struct with a [2]uintptr field is stack-assigned entirely. A function with ten integer arguments spills the last one. If you are reasoning about the ABI by hand, read the algorithm in src/cmd/compile/abi-internal.md rather than guessing.

The Ptrs duplication in RegArgs exists for the GC. If you write assembly that manipulates RegArgs, you must keep the Ints and Ptrs copies consistent, or the GC will miss a live pointer.

ABI changes are visible in profiles. When Go changed the ABI, function entry costs moved. A profile captured before and after a Go upgrade is not comparable at the level of individual function entry costs, even though the code is identical.

Wrapping up

The one thing to remember: Go has two ABIs. ABI0 (stack-based, stable, for assembly) and ABIInternal (register-based, unstable, for Go code), and the compiler generates transparent wrappers between them so you never have to think about it.

The part people get wrong: the fixed registers. On amd64, R14 holds the goroutine pointer and X15 is always zero, in every function. That is why the runtime can switch goroutines with two instructions and why frame zeroing is cheap. If you are reading runtime assembly and wondering why XORPS X15, X15 shows up after every context switch, that is the answer.

What to go do about it: if you are writing assembly, read src/cmd/compile/abi-internal.md end to end and target ABI0. If you are just writing Go, the practical takeaways are that calls are cheaper than they used to be, g is free, and the only reason to care about any of this is when you are benchmarking across Go versions.

Escape Analysis in Go: Why Your Local Variable Escaped

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: The Go compiler refuses to put a stack pointer in the heap, so every variable that could outlive its frame has to be heap-allocated. Escape analysis works out which ones those are by building a weighted graph of variables and assignments, walking it looking for paths where an address outlives its owner, and stamping each variable EscNone (stack) or EscHeap (heap). A closure that captures a variable by reference is enough to do it.

Everyone has seen the message:

text

./main.go:14:14: variable x escapes to heap

It shows up when you were expecting a stack allocation and got a heap one instead. It is also, annoyingly, the first thing you check when a benchmark shows 40 nanoseconds of allocator overhead per iteration.

The interesting part is what the compiler is actually doing when it prints that. It is not “I saw a pointer, so I gave up”. The Go escape analysis is a real data-flow analysis, and understanding it tells you exactly how to write code that stays on the stack.

This is a walk through how it works, based on reading the Go 1.28 development tree (src/cmd/compile/internal/escape/).

The two invariants

Everything in the escape analyzer is in service of exactly two rules. From the top of escape.go:

 go
 
 
// src/cmd/compile/internal/escape/escape.go:23
// Escape analysis.
//
// Here we analyze functions to determine which Go variables
// (including implicit allocations such as calls to "new" or "make",
// composite literals, etc.) can be allocated on the stack. The two
// key invariants we have to ensure are: (1) pointers to stack objects
// cannot be stored in the heap, and (2) pointers to a stack object
// cannot outlive that object (e.g., because the declaring function
// returned and destroyed the object's stack frame, or its space is
// reused across loop iterations for logically distinct variables).
//
// We implement this with a static data-flow analysis of the AST.
// First, we construct a directed weighted graph where vertices
// (termed "locations") represent variables allocated by statements
// and expressions, and edges represent assignments between variables
// (with weights representing addressing/dereference counts).
//
// Next we walk the graph looking for assignment paths that might
// violate the invariants stated above. If a variable v's address is
// stored in the heap or elsewhere that may outlive it, then v is
// marked as requiring heap allocation.
//
// To support interprocedural analysis, we also record data-flow from
// each function's parameters to the heap and to its result
// parameters. This information is summarized as "parameter tags",
// which are used at static call sites to improve escape analysis of
// function arguments.

Read that third paragraph carefully, because it is the whole design. It is a directed weighted graph, where:

Vertices are locations — one per variable declaration, and one per allocating expression (new, make, a composite literal, a closure).
Edges are assignments, and the weight is a dereference count.

The weight is the trick. Every assignment in Go is one of four shapes, and the analyzer records the difference between address-of operations and dereference operations:

 text
 
 
 p = &q // -1
 p = q // 0
 p = *q // 1
 p = **q // 2

A negative weight means “an address flows along this edge”. A positive weight means “the pointed-to value flows along this edge”. The escape analysis is then a search for a path with a negative weight that reaches the heap — because a negative-weight path to the heap means “somebody stored the address of this variable into memory the GC can reach”, which is invariant (1) violated.

The whole graph, drawn:

 text
 
 
 [heap] (attrEscapes)
 ^
 | edge, derefs = -1 (the address flows here)
 |
 +-------+-------+
 | |
 [loc x] [loc y] <- locations (vertices)
 | |
 | edge derefs=0 | edge derefs=1 (the value flows here)
 v v
 [loc p] [loc *q]

 loop depth and closure nesting decide whether the root
 outlives the source location

Locations, holes, and edges

The graph has three node types. First the location, one per variable:

 go
 
 
// src/cmd/compile/internal/escape/graph.go:41
// A location represents an abstract location that stores a Go
// variable.
type location struct {
	n ir.Node // represented variable or expression, if any
	curfn *ir.Func // enclosing function
	edges []edge // incoming edges
	loopDepth int // loopDepth at declaration

	// resultIndex records the tuple index (starting at 1) for
	// PPARAMOUT variables within their function's result type.
	// For non-PPARAMOUT variables it's 0.
	resultIndex int

	// derefs and walkgen are used during walk to track the
	// minimal dereferences from the walk root.
	derefs int // >= -1
	walkgen uint32

	// queuedWalkAll is used by walkAll to track whether this location is
	// in its work queue.
	queuedWalkAll bool

	// queuedWalk is used by walk to track whether this location is
	// in its work queue. The value is the walkgen when this location was
	// last queued for walk, or 0 if it's not currently queued.
	queuedWalk uint32

	// attrs is a bitset of location attributes.
	attrs locAttr

	// paramEsc records the represented parameter's leak set.
	paramEsc leaks

	captured bool // has a closure captured this variable?
	reassigned bool // has this variable been reassigned?
	addrtaken bool // has this variable's address been taken?
	param bool // is this variable a parameter (ONAME of class ir.PPARAM)?
	paramOut bool // is this variable an out parameter (ONAME of class ir.PPARAMOUT)?
}

Three fields in there do most of the interesting work later: addrtaken, reassigned, and captured decide whether a closure can capture a variable by value; resultIndex decides whether a leak goes to “the heap” or “result number 2”.

The edge carries the weight:

 go
 
 
// src/cmd/compile/internal/escape/graph.go:107
// An edge represents an assignment edge between two Go variables.
type edge struct {
	src *location
	derefs int // >= -1
	notes *note
}

And the hole is the analyzer’s way of saying “a value is flowing into this location, N dereferences deep”:

 go
 
 
// src/cmd/compile/internal/escape/graph.go:140
// A hole represents a context for evaluation of a Go
// expression. E.g., when evaluating p in "x = **p", we'd have a hole
// with dst==x and derefs==2.
type hole struct {
	dst *location
	derefs int // >= -1
	notes *note

	// addrtaken indicates whether this context is taking the address of
	// the expression, independent of whether the address will actually
	// be stored into a variable.
	addrtaken bool
}

hole.addr() shifts the deref count down by one (an address-of), and hole.deref() shifts it up by one (a dereference). The analyzer is essentially threading a single integer through the entire program.

Where the edges come from

The analyzer walks the AST and turns every assignment into an edge. The interesting one is flow, which is where the “address escapes” decision actually gets made:

 go
 
 
// src/cmd/compile/internal/escape/graph.go:193
func (b *batch) flow(k hole, src *location) {
	if k.addrtaken {
		src.addrtaken = true
	}

	dst := k.dst
	if dst == &b.blankLoc {
		return
	}
	if dst == src && k.derefs >= 0 { // dst = dst, dst = *dst, ...
		return
	}
	if dst.hasAttr(attrEscapes) && k.derefs < 0 { // dst = &src
		if base.Flag.LowerM >= 2 || logopt.Enabled() {
			pos := base.FmtPos(src.n.Pos())
			if base.Flag.LowerM >= 2 {
				fmt.Printf("%s: %v escapes to heap in %v:\n", pos, src.n, ir.FuncName(src.curfn))
			}
			explanation := b.explainFlow(pos, dst, src, k.derefs, k.notes, []*logopt.LoggedOpt{})
			if logopt.Enabled() {
				var e_curfn *ir.Func // TODO(mdempsky): Fix.
				logopt.LogOpt(src.n.Pos(), "escapes", "escape", ir.FuncName(e_curfn), fmt.Sprintf("%v escapes to heap", src.n), explanation)
			}

		}
		src.attrs |= attrEscapes | attrPersists | attrMutates | attrCalls
		return
	}

	// TODO(mdempsky): Deduplicate edges?
	dst.edges = append(dst.edges, edge{src: src, derefs: k.derefs, notes: k.notes})
}

Read the condition dst.hasAttr(attrEscapes) && k.derefs < 0. That means: “the destination is the heap, and what is flowing into it is an address”. In that case the source variable escapes, immediately and irrevocably. Otherwise the assignment just becomes an edge and the analysis continues.

There are four synthetic locations set up at the start of every batch:

 go
 
 
// src/cmd/compile/internal/escape/escape.go:145
func Batch(fns []*ir.Func, reassignOracles map[*ir.Func]*ir.ReassignOracle) {
	var b batch
	b.heapLoc.attrs = attrEscapes | attrPersists | attrMutates | attrCalls
	b.mutatorLoc.attrs = attrMutates
	b.calleeLoc.attrs = attrCalls
	b.reassignOracles = reassignOracles

The heap location has attrEscapes, which is precisely the flag that flow above checks. The mutator and callee locations exist so the analyzer can distinguish “this pointer gets written through” (which is a mutation of the pointee, not an escape of the pointer) from “this pointer is stored somewhere long-lived”.

Solving it: the walk

Once the graph is built, walkAll solves it. The solver is a Bellman-Ford variant, because the graph has negative edges:

 go
 
 
// src/cmd/compile/internal/escape/solve.go:135
// walk computes the minimal number of dereferences from roots that were
// scheduled with state s to all other locations. A root's live attributes may
// have grown since it was scheduled; the resulting new state is walked in a
// later round.
func (b *batch) walk(s walkState, roots []*location, walkgen uint32, enqueue func(*location), todo *queue) {
	// The data flow graph has negative edges (from addressing
	// operations), so we use the Bellman-Ford algorithm. However,
	// we don't have to worry about infinite negative cycles since
	// we bound intermediate dereference counts to 0.

	diagnose := base.Flag.LowerM >= 2 || logopt.Enabled()

And the actual escape decision is inside the loop:

 go
 
 
// src/cmd/compile/internal/escape/solve.go:175
		// If l.derefs < 0, then l's address flows to root.
		addressOf := derefs < 0
		if addressOf {
			// For a flow path like "root = &l; l = x",
			// l's address flows to root, but x's does
			// not. We recognize this by lower bounding
			// derefs at 0.
			derefs = 0

			// If l's address flows somewhere that
			// outlives it, then l needs to be heap
			// allocated.
			if s.outlives(b, l) {
				if !l.hasAttr(attrEscapes) && diagnose {
					if base.Flag.LowerM >= 2 {
						fmt.Printf("%s: %v escapes to heap in %v:\n", base.FmtPos(l.n.Pos()), l.n, ir.FuncName(l.curfn))
					}
					root := walkRoot(l, paths)
					explanation := b.explainPath(root, l, paths[l])
					if logopt.Enabled() {
						var e_curfn *ir.Func // TODO(mdempsky): Fix.
						logopt.LogOpt(l.n.Pos(), "escape", "escape", ir.FuncName(e_curfn), fmt.Sprintf("%v escapes to heap", l.n), explanation)
					}
				}
				newAttrs |= attrEscapes | attrPersists | attrMutates | attrCalls
			} else
			// If l's address flows to a persistent location, then l needs
			// to persist too.
			if s.hasAttr(attrPersists) {
				newAttrs |= attrPersists
			}
		}

So the rule reduces to: if the address of l reaches a root that outlives l, then l escapes.

“Outlives” is the interesting question

What outlives what? That is the outlives function, and it is where most of the subtlety lives:

 go
 
 
// src/cmd/compile/internal/escape/solve.go:366
// outlives reports whether values stored in roots with state s may survive
// beyond other's lifetime if stack allocated.
func (s walkState) outlives(b *batch, other *location) bool {
	// The heap outlives everything.
	if s.hasAttr(attrEscapes) {
		return true
	}

	// Pseudo-locations that don't really exist.
	if s.sink == &b.mutatorLoc || s.sink == &b.calleeLoc {
		return false
	}

	// We don't know what callers do with returned values, so
	// pessimistically we need to assume they flow to the heap and
	// outlive everything too.
	if s.sink != nil && s.sink.paramOut {
		// Exception: Closures can return locations allocated outside of
		// them without forcing them to the heap, if we can statically
		// identify all call sites. For example:
		//
		//	var u int // okay to stack allocate
		//	fn := func() *int { return &u }()
		//	*fn() = 42
		if ir.ContainsClosure(other.curfn, s.curfn) && !s.curfn.ClosureResultsLost() {
			return false
		}

		return true
	}

	// If root and other are within the same function, then root
	// outlives other if it was declared outside other's loop
	// scope. For example:
	//
	//	var l *int
	//	for {
	//		l = new(int) // must heap allocate: outlives for loop
	//	}
	if s.curfn == other.curfn && s.loopDepth < other.loopDepth {
		return true
	}

	// If other is declared within a child closure of where root is
	// declared, then root outlives it. For example:
	//
	//	var l *int
	//	func() {
	//		l = new(int) // must heap allocate: outlives call frame (if not inlined)
	//	}()
	if ir.ContainsClosure(s.curfn, other.curfn) {
		return true
	}

	return false
}

Four cases:

The heap outlives everything. Obvious.
The mutator and callee sinks outlive nothing — writing through a pointer is not the same as storing the pointer.
A result parameter outlives everything, because the caller might stash the returned pointer somewhere. The one exception is a closure whose call sites the compiler can see.
Loop depth and closure nesting decide the rest. A variable declared outside a loop outlives one declared inside it (the loop’s space gets reused). A variable declared in an enclosing function outlives one declared in a closure.

That last rule is why this code allocates on the heap:

 go
 
 
var l *int
for {
 l = new(int) // must heap allocate: outlives for loop
}

The new(int) result is assigned to l, which lives outside the loop. On the second iteration, the int from the first iteration is dead, so its memory could be reused — but l still points at it. Heap allocation is the only safe answer.

The tags: `EscNone`, `EscHeap`, `EscNever`

When the analysis is done, finish stamps every node with its verdict. The flags live in ir/node.go and are deliberately tiny:

 go
 
 
// src/cmd/compile/internal/ir/node.go:573
const (
	EscUnknown = iota
	EscNone // Does not escape to heap, result, or parameters.
	EscHeap // Reachable from the heap
	EscNever // By construction will not escape.
)

EscNever is the interesting one: it means “this variable cannot possibly escape, by construction of the program, not by analysis”. The escape analyzer uses it for the defer record, which is a compiler-synthesised variable:

 go
 
 
// src/cmd/compile/internal/escape/call.go:238
func (e *escape) goDeferStmt(n *ir.GoDeferStmt) {
	k := e.heapHole()
	if n.Op() == ir.ODEFER && e.loopDepth == 1 && n.DeferAt == nil {
		// Top-level defer arguments don't escape to the heap,
		// but they do need to last until they're invoked.
		k = e.later(e.discardHole())

		// force stack allocation of defer record, unless
		// open-coded defers are used (see ssa.go)
		n.SetEsc(ir.EscNever)
	}

Note that this enum has exactly four values. There is no “escapes to result” state here — that direction is carried separately, in the leaks set described below, so that a parameter can be recorded as leaking to result 0 without being recorded as leaking to the heap.

And here is the actual stamping, with the diagnostic messages:

 go
 
 
// src/cmd/compile/internal/escape/escape.go:464
		if loc.hasAttr(attrEscapes) {
			if n.Op() == ir.ONAME {
				if base.Flag.CompilingRuntime {
					base.ErrorfAt(n.Pos(), 0, "%v escapes to heap, not allowed in runtime", n)
				}
				if base.Flag.LowerM != 0 {
					base.WarnfAt(n.Pos(), "moved to heap: %v", n)
				}
			} else {
				if base.Flag.LowerM != 0 && !goDeferWrapper {
					if n.Op() == ir.OAPPEND {
						base.WarnfAt(n.Pos(), "append escapes to heap")
					} else {
						base.WarnfAt(n.Pos(), "%v escapes to heap", n)
					}
				}
				if logopt.Enabled() {
					var e_curfn *ir.Func // TODO(mdempsky): Fix.
					logopt.LogOpt(n.Pos(), "escape", "escape", ir.FuncName(e_curfn))
				}
			}
			n.SetEsc(ir.EscHeap)
		} else {

So the compiler’s -m output distinguishes two cases that people usually conflate:

moved to heap: x — x is a variable (ONAME) that got promoted.
x escapes to heap — x is an expression (a new, a composite literal, an append) whose value lives on the heap.

Interprocedural: parameter tags

The analyzer does not stop at one function. If it can see a callee’s definition, it can compute what that callee does with its parameters, and bake that into the callee’s export data as a “leak set”:

 go
 
 
// src/cmd/compile/internal/escape/leaks.go:13
// A leaks represents a set of assignment flows from a parameter to
// the heap, mutator, callee, or to any of its function's (first
// numEscResults) result parameters.
type leaks [8]uint8

const (
	leakHeap = iota
	leakMutator
	leakCallee
	leakResult0
)

const numEscResults = len(leaks{}) - leakResult0

Eight bytes: one for the heap, one for the mutator, one for the callee, and up to five result parameters. Each entry is a minimum dereference count, stored biased by one so that zero means “no flow”. The encoding is deliberately compact because it goes into every package’s export data:

 go
 
 
// src/cmd/compile/internal/escape/leaks.go:97
// Encode converts l into a binary string for export data.
func (l leaks) Encode() string {
	if l.Heap() == 0 {
		// Space optimization: empty string encodes more
		// efficiently in export data.
		return ""
	}
	if s, ok := leakTagCache[l]; ok {
		return s
	}

	n := len(l)
	for n > 0 && l[n-1] == 0 {
		n--
	}
	s := "esc:" + string(l[:n])
	leakTagCache[l] = s
	return s
}

That "esc:" prefix plus raw bytes is what you see in export data. The compiler reads it back at call sites and uses it to decide where an argument flows:

 go
 
 
// src/cmd/compile/internal/escape/call.go:403
	// Call to previously tagged function.

	var tagKs []hole
	esc := parseLeaks(param.Note)

	if x := esc.Heap(); x >= 0 {
		tagKs = append(tagKs, e.heapHole().shift(x))
	}
	if x := esc.Mutator(); x >= 0 {
		tagKs = append(tagKs, e.mutatorHole().shift(x))
	}
	if x := esc.Callee(); x >= 0 {
		tagKs = append(tagKs, e.calleeHole().shift(x))
	}

	if ks != nil {
		for i := 0; i < numEscResults; i++ {
			if x := esc.Result(i); x >= 0 {
				tagKs = append(tagKs, ks[i].shift(x))
			}
		}
	}

	return e.teeHole(tagKs...)

So when you pass a pointer to a function whose body you cannot see (an assembly function, or one in another package compiled earlier), the compiler uses the tag. If the tag says “this parameter leaks to the heap”, your argument escapes. If it says “does not escape”, your argument can stay on the stack.

“Leaks to result” — the rule people misread

The most common source of confusion is the difference between a parameter that leaks to the heap and one that leaks to a result. They are different flows, and they are recorded separately.

 go
 
 
// src/cmd/compile/internal/escape/graph.go:118
// leak records that parameter l leaks to sink.
func (l *location) leakTo(sink *location, derefs int) {
	// If sink is a result parameter that doesn't escape (#44614)
	// and we can fit return bits into the escape analysis tag,
	// then record as a result leak.
	if !sink.hasAttr(attrEscapes) && sink.isName(ir.PPARAMOUT) && sink.curfn == l.curfn {
		ri := sink.resultIndex - 1
		if ri < numEscResults {
			// Leak to result parameter.
			l.paramEsc.AddResult(ri, derefs)
			return
		}
	}

	// Otherwise, record as heap leak.
	l.paramEsc.AddHeap(derefs)
}

A parameter that leaks only to result 0 is not a heap leak. The function returns the pointer, so the caller decides what to do with it. This is what makes the classic “identity function” free:

 go
 
func id(p *int) *int { return p }

p leaks to result 0, not to the heap. The caller’s variable stays on the stack. But:

 go
 
func keep(p *int) *int { global = p; return p }

leaks to the heap, so the caller’s variable is promoted. The -m output makes the distinction visible:

 go
 
 
// src/cmd/compile/internal/escape/escape.go:670
	for i := 0; i < numEscResults; i++ {
		if x := esc.Result(i); x >= 0 {
			res := sig.Result(i).Nname.Sym().Name
			base.WarnfAt(pos, "leaking param: %v to result %v level=%d", name, res, x)
			warned = true
		}
	}

leaking param: p to result r level=1 means “the pointer inside p (one dereference deep) comes back out as result r”. That is a much weaker statement than leaking param: p.

Closures: why capturing forces the heap

Now the case everybody hits. When a closure captures a variable, the analyzer has to decide: by value or by reference?

 go
 
 
// src/cmd/compile/internal/escape/escape.go:262
func (b *batch) flowClosure(k hole, clo *ir.ClosureExpr) {
	for _, cv := range clo.Func.ClosureVars {
		n := cv.Canonical()
		loc := b.oldLoc(cv)
		if !loc.captured {
			base.FatalfAt(cv.Pos(), "closure variable never captured: %v", cv)
		}

		// Capture by value for variables <= 128 bytes that are never reassigned.
		n.SetByval(!loc.addrtaken && !loc.reassigned && n.Type().Size() <= 128)
		if !n.Byval() {
			n.SetAddrtaken(true)
			if n.Sym().Name == typecheck.LocalDictName {
				base.FatalfAt(n.Pos(), "dictionary variable not captured by value")
			}
		}
	}

Three conditions, all of which must hold to capture by value:

The variable’s address was never taken (!loc.addrtaken).
The variable was never reassigned (!loc.reassigned).
The variable is at most 128 bytes.

If any of those fails, the variable is captured by reference. Then the address of the variable is stored in the closure record. And if the closure record itself can escape, the address of the variable has reached the heap, which is exactly invariant (1).

Note the “128 bytes” limit. That is not arbitrary — it is the size at which copying the value into the closure record becomes as expensive as heap-allocating it. Larger captures go by reference so the closure does not carry a fat copy of a big struct around.

Here is the closure case in expr.go, where the closure expression itself is spilled into the graph:

 go
 
 
// src/cmd/compile/internal/escape/expr.go:230
	case ir.OCLOSURE:
		n := n.(*ir.ClosureExpr)
		k = e.spill(k, n)
		e.closures = append(e.closures, closure{k, n})

		if fn := n.Func; fn.IsClosure() {
			for _, cv := range fn.ClosureVars {
				if loc := e.oldLoc(cv); !loc.captured {
					loc.captured = true

					// Ignore reassignments to the variable in straightline code
					// preceding the first capture by a closure.
					if loc.loopDepth == e.loopDepth {
						loc.reassigned = false
					}
				}
			}

And spill is the generic “this expression allocates storage” operation:

 go
 
 
// src/cmd/compile/internal/escape/expr.go:336
// spill allocates a new location associated with expression n, flows
// its address to k, and returns a hole that flows values to it. It's
// intended for use with most expressions that allocate storage.
func (e *escape) spill(k hole, n ir.Node) hole {
	loc := e.newLoc(n, false)
	e.flow(k.addr(n, "spill"), loc)
	return loc.asHole()
}

A spill creates a location and flows its address into the destination. If the destination is the heap, the expression escapes.

Some things cannot be stack allocated at all

Even if nothing escapes, some things are too big or too aligned. That check is separate from the graph analysis:

 go
 
 
// src/cmd/compile/internal/escape/utils.go:186
	if n.Type().Size() > ir.MaxStackVarSize {
		return "too large for stack"
	}
	if n.Type().Alignment() > int64(types.PtrSize) {
		return "too aligned for stack"
	}

	if (n.Op() == ir.ONEW || n.Op() == ir.OPTRLIT) && n.Type().Elem().Size() > ir.MaxImplicitStackVarSize {
		return "too large for stack"
	}
	if (n.Op() == ir.ONEW || n.Op() == ir.OPTRLIT) && n.Type().Elem().Alignment() > int64(types.PtrSize) {
		return "too aligned for stack"
	}

And the limits themselves:

 go
 
 
// src/cmd/compile/internal/ir/cfg.go:8
	// MaxStackVarSize is the maximum size variable which we will allocate on the stack.
	// This limit is for explicit variable declarations like "var x T" or "x := ...".
	// Note: the flag smallframes can update this value.
	MaxStackVarSize = int64(128 * 1024)

	// MaxImplicitStackVarSize is the maximum size of implicit variables that we will allocate on the stack.
	// p := new(T) allocating T on the stack
	// p := &T{} allocating T on the stack
	// s := make([]T, n) allocating [n]T on the stack
	// s := []byte("...") allocating [n]byte on the stack
	// Note: the flag smallframes can update this value.
	MaxImplicitStackVarSize = int64(64 * 1024)

128 KiB for named variables, 64 KiB for implicit ones like new(T). Go’s stacks grow by copying, and a giant stack frame makes every stack growth expensive, so the compiler draws a line.

From `EscHeap` to `runtime.newobject`

The escape verdict becomes code in the SSA backend. The SSA builder asks the IR what the verdict is, and if it is EscHeap, it allocates:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:1789
	case ir.ODCL:
		n := n.(*ir.Decl)
		if v := n.X; v.Esc() == ir.EscHeap {
			s.newHeapaddr(v)
		}

And newHeapaddr is where the actual runtime.newobject call comes from:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:724
// newHeapaddr allocates heap memory for n and sets its heap address.
func (s *state) newHeapaddr(n *ir.Name) {
	size := allocSize(n.Type())
	if n.Type().HasPointers() || size >= maxAggregatedHeapAllocation || size == 0 {
		s.setHeapaddr(n.Pos(), n, s.newObject(n.Type()))
		return
	}

And newObject is the runtime.newobject call site:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:871
// newObject returns an SSA value denoting new(typ).
func (s *state) newObject(typ *types.Type) *ssa.Value {
	if typ.Size() == 0 {
		return s.newValue1A(ssaop.OpAddr, types.NewPtr(typ), ir.Syms.Zerobase, s.sb)
	}
	rtype := s.reflectType(typ)
	if specialMallocSym := s.specializedMallocSym(typ.Size(), typ.HasPointers()); specialMallocSym != nil {
		return s.rtcall(specialMallocSym, true, []*types.Type{types.NewPtr(typ)},
			s.constInt(types.Types[types.TUINTPTR], typ.Size()),
			rtype,
			s.constBool(true),
		)[0]
	}
	return s.rtcall(ir.Syms.Newobject, true, []*types.Type{types.NewPtr(typ)}, rtype)[0]
}

If the variable does not escape, none of this runs. The variable becomes a stack slot, assigned a frame offset, and lives in the function’s frame. The decision point is the ir.Name.OnStack predicate, which is a one-liner over the escape flag:

 go
 
 
// src/cmd/compile/internal/ir/name.go:235
// OnStack reports whether variable n may reside on the stack.
func (n *Name) OnStack() bool {
	if n.Op() == ONAME {
		switch n.Class {
		case PPARAM, PPARAMOUT, PAUTO:
			return n.Esc() != EscHeap
		case PEXTERN, PAUTOHEAP:
			return false
		}
	}
	// Note: fmt.go:dumpNodeHeader calls all "func() bool"-typed
	// methods, but it can only recover from panics, not Fatalf.
	panic(fmt.Sprintf("%v: not a variable: %v", base.FmtPos(n.Pos()), n))
}

Reading the diagnostics

The tool for this is go build -gcflags=-m. Two levels matter:

-m prints the decisions: moved to heap: x, x escapes to heap, leaking param: p, p does not escape.
-m=2 prints the paths: the chain of flows that led to the decision.

text

./main.go:10:30: leaking param: p to result ~r0 level=1
./main.go:10:30: p does not escape
./main.go:14:14: moved to heap: x
./main.go:14:14: leaking param: content to result ~r0 level=1

That last pair is the interesting one: content is a field of x, and it escapes even though x itself did not need to move. That happens when the struct field is a pointer that gets stored somewhere.

For JSON logging of the same decisions, the compiler supports -json=... style optimization logs through the logopt package, which is what gopls and benchstat-style tooling read.

Trade-offs

What escape analysis buys you: a local variable that does not escape costs zero allocations. No runtime.mallocgc, no GC pressure, no cache misses on a fresh span. In a hot loop this is often the difference between 5 ns and 50 ns per iteration.

What it costs you: compile time. The analyzer is a whole-program-ish data-flow analysis over every function in the package, with a Bellman-Ford solver and interprocedural tag propagation across package boundaries. For a big package this is measurable.

Why it is conservative in specific places: several flows are deliberately pessimistic.

A pointer returned from a function is assumed to outlive the frame, because the compiler cannot see all the callers.
A pointer passed to an unknown function is assumed to leak to the heap, unless the function is annotated //go:noescape.
A pointer stored in a struct field is treated as escaping if any field of that struct escapes, because the analyzer does not distinguish fields within a compound variable.

Why the “leaks to result” distinction is worth caring about: it is the difference between a function that can be used in a zero-allocation data structure and one that cannot. If every parameter of your accessor leaked to the heap, every call site would allocate.

Caveats

Escape analysis is per-package, not per-program. When you compile a package, the escape tags of the exported functions of its dependencies are available, but functions in the same package are analyzed together and can be inlined into one another. A change in one file can move a variable in another file.

The 128-byte closure capture limit is a hard cut, not a heuristic. A 129-byte struct captured by a closure goes by reference, and therefore usually to the heap. There is no “small enough to be worth copying” tier below it.

//go:noinline and //go:nosplit do not affect escape analysis. They are separate pragmas. //go:noinline stops the inliner; //go:nosplit stops the function from being split across a stack growth. The only pragmas that influence escaping are //go:noescape (on a function declaration, meaning “my pointer parameters do not escape”) and //go:uintptrescapes (the opposite, for syscall-style functions).

The analyzer does not distinguish fields inside a struct. The header comment in escape.go says it plainly: x.f = u[0] is modelled as x = *u, without regard for which field. So a struct with one escaping pointer field can drag the whole struct to the heap.

Zero-sized and very large types behave oddly. A zero-sized type gets runtime.zerobase instead of an allocation. A type bigger than 64 KiB allocated implicitly is always heap-allocated, no matter what the analysis says.

append is a special case. The analyzer models append as possibly reallocating, so the result of append can be on the heap even when the input slice is on the stack. s = append(s, x) where s has spare capacity usually stays on the stack; s = append(s, x...) usually does not.

Wrapping up

The one thing to remember: escape analysis asks one question about every variable — “can the address of this thing reach memory that outlives my stack frame?” — and if the answer might be yes, the variable is heap allocated. It is not “pointers are slow”; it is a lifetime question.

The part people get wrong: “the function does not store the pointer anywhere” is not sufficient. A pointer that is returned, or captured by a closure that might outlive the frame, or assigned to a variable declared outside a loop, escapes. The -m output distinguishes these cases: leaking param: p to result ~r0 is much friendlier than leaking param: p.

What to go do about it: compile with -gcflags=-m=2 and read the flow paths for the variables you expected to stay on the stack. If a local escapes, the reason is almost always one of four things: it is captured by a closure, it is stored into a longer-lived variable, it is passed to a function the compiler cannot see into, or it is returned. Fix the one that applies and the allocation disappears.

Compiler on Opensource internals

range over func: The Compiler Turns a Loop Into a Coroutine

The shape of the feature

The rewrite pass

Checking that the iterator behaves

defer inside the loop body

recover inside the loop body

Where the coroutine actually is

Trade-offs

Caveats

Wrapping up

Further reading

How Go Deletes Your Bounds Checks: The Facts Table That Proves i < len(s)

What a bounds check looks like

Domains: the key insight

The facts table

Limits: knowing the range of a value

Learning from branches

The chunked-access special case

The Limit type is more than a range

The poset: transitivity for free

Proving the check itself

How do you check the compiler’s work?

Trade-offs

Caveats

Wrapping up

Further reading

How Go Allocates Registers: The SSA Backend's Linear Scan Pass

Where the code lives

The SSA form

The output of the pass: Location

The state of the allocator

Phase one: liveness

Phase two: the linear scan

Choosing a register

Spilling

Restoring

Placing the spill

Phi elimination

Merge edges: the shuffle

Stack slots: the other allocator

Looking at it yourself

Trade-offs

Caveats

Wrapping up

Further reading

Go's Linker Deletes Code You Never Call: Method Pruning and Reachability

The rule the linker follows

The flood fill

Where the method table lives

The pruning loop

The reflection escape hatch

What happens to the pruned methods

The size effect

-w and -s: the other half of the size story

Trade-offs

Caveats

Wrapping up

Further reading

Go's Inliner: A Budget of 80 Nodes and the Art of the Cheat Sheet

Two passes, not one

The budget

Counting the nodes

What disqualifies a function outright

Big functions get a smaller budget

PGO: the budget goes to 2000

The new inliner: score adjustments

The source-level inliner: //go:fix inline

Reading the diagnostics

Trade-offs

Caveats

Wrapping up

Further reading

Go's Generics: Dictionary Passing, Shape Stenciling and GC Shape

What the runtime knows about generics: nothing

Shapes

How a shape is computed

The identity rule that makes sharing legal

The dictionary

The dictionary’s layout

`defer` inside the loop body

`recover` inside the loop body

The `Limit` type is more than a range

The `poset`: transitivity for free

The output of the pass: `Location`

`-w` and `-s`: the other half of the size story

The source-level inliner: `//go:fix inline`

`RegArgs`: the assembly-facing view

The tags: `EscNone`, `EscHeap`, `EscNever`

From `EscHeap` to `runtime.newobject`