Runtime on Opensource internals

Why Go Randomizes Map Iteration: The Attack It Prevents

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

TL;DR: Every map gets a random hash seed and every range starts at a random offset, both from the runtime’s per-M ChaCha8 generator. The seed stops an attacker who controls your keys from piling them into one bucket; the random start stops an attacker who has measured your map from predicting the order you will visit keys in.

Write this loop and run it twice:

 text
 
 
for k, v := range m {
 fmt.Println(k, v)
}

You will get a different order every time. That is not a bug, it is not “undefined behaviour” in the C sense, and it is not there to make your life harder. It is the defence against a denial-of-service attack that has a name, a CVE number, and a history.

The spec’s promise

The Go specification is deliberately vague, and the vagueness is the point:

 html
 
 
<!-- doc/go_spec.html:6843 -->
The iteration order over maps is not specified
and is not guaranteed to be the same from one iteration to the next.
If a map entry that has not yet been reached is removed during iteration,
the corresponding iteration value will not be produced. If a map entry is
created during iteration, that entry may be produced during the iteration or
may be skipped. The choice may vary for each entry created and from one
iteration to the next.
If the map is <code>nil</code>, the number of iterations is 0.

“not specified” plus “not guaranteed to be the same from one iteration to the next” is a promise that the implementation will deliberately vary the order. If it did not, code that happened to depend on insertion order would silently break, and — much more importantly — code that depended on it would be a security problem in someone else’s server.

The two random mechanisms

It is easy to conflate two separate mechanisms that both come from the runtime’s random number generator. They defend against different attacks.

Mechanism	Where it lives	What it defends against
Per-map hash seed	`Map.seed`, mixed into every key hash	Hash flooding: attacker picks keys that all land in one bucket
Random iteration start	`Iter.entryOffset`, `Iter.dirOffset`	Order prediction: attacker guesses which key you will process first

The first is about performance. The second is about disclosure.

The hash seed

Every Map gets a random seed when it is created:

 go
 
 
// src/internal/runtime/maps/map.go:283
func NewMap(mt *abi.MapType, hint uintptr, m *Map, maxAlloc uintptr) *Map {
	if m == nil {
		m = new(Map)
	}

	m.seed = uintptr(rand())

	if hint <= abi.MapGroupSlots {
		// A small map can fill all 8 slots, so no need to increase
		// target capacity.
		//
		// In fact, since an 8 slot group is what the first assignment
		// to an empty map would allocate anyway, it doesn't matter if
		// we allocate here or on the first assignment.
		//
		// Thus we just return without allocating. (We'll save the
		// allocation completely if no assignment comes.)

		// Note that the compiler may have initialized m.dirPtr with a
		// pointer to a stack-allocated group, in which case we already
		// have a group. The control word is already initialized.

		return m
	}

and the seed is stored alongside the map’s contents:

 go
 
 
// src/internal/runtime/maps/map.go:214
type Map struct {
	// The number of filled slots (i.e. the number of elements in all
	// tables). Excludes deleted slots.
	// Must be first (known by the compiler, for len() builtin).
	used uint64

	// seed is the hash seed, computed as a unique random number per map.
	seed uintptr

The seed is then passed to the runtime’s hasher for every key operation:

 go
 
 
// src/internal/runtime/maps/runtime.go:106
	hash := typ.Hasher(key, m.seed)

Without the seed, the hash of a key is a pure function of the key’s bytes. An attacker who can submit keys — a username, a URL path, a product code — can compute their hashes offline and find a set that all collide into one bucket. Then a map with a thousand of those keys degrades from O(1) lookups to a thousand-element linear scan per lookup, and the server’s CPU melts. That is the algorithmic complexity attack, and it is the class of bug that Kubernetes tracked as CVE-2019-11253.

With the seed, the attacker cannot predict which bucket a key will land in, because the whole hash function’s output is shifted by a per-process, per-map random value. The collision-finding attack has to be performed against the live map, at full cost per attempt, instead of offline.

The seed is also refreshed in a couple of interesting places — Delete and Clear both roll a new one:

 go
 
 
// src/internal/runtime/maps/map.go:786
	m.seed = uintptr(rand())

so an attacker cannot accumulate knowledge of one map’s layout across a long-lived process.

The random iteration start

Now the second mechanism. The iterator is a struct that carries two random offsets:

 go
 
 
// src/internal/runtime/maps/table.go:704
type Iter struct {
	key unsafe.Pointer // Must be in first position. Write nil to indicate iteration end (see cmd/compile/internal/walk/range.go).
	elem unsafe.Pointer // Must be in second position (see cmd/compile/internal/walk/range.go).
	typ *abi.MapType
	m *Map

	// Randomize iteration order by starting iteration at a random slot
	// offset. The offset into the directory uses a separate offset, as it
	// must adjust when the directory grows.
	entryOffset uint64
	dirOffset uint64

	// Snapshot of Map.clearSeq at iteration initialization time. Used to
	// detect clear during iteration.
	clearSeq uint64

	// Value of Map.globalDepth during the last call to Next. Used to
	// detect directory grow during iteration.
	globalDepth uint8

	// dirIdx is the current directory index, prior to adjustment by
	// dirOffset.
	dirIdx int

	// tab is the table at dirIdx during the previous call to Next.
	tab *table

	// group is the group at entryIdx during the previous call to Next.
	group groupReference

	// entryIdx is the current entry index, prior to adjustment by entryOffset.
	// The lower 3 bits of the index are the slot index, and the upper bits
	// are the group index.
	entryIdx uint64
}

Two offsets, for two different index spaces. entryOffset randomises where inside the slot space you start; dirOffset randomises which table in the directory you start with. They have to be separate because the directory can grow during iteration, and a single offset would then be ambiguous.

Both are rolled once, at iterator initialisation:

 go
 
 
// src/internal/runtime/maps/table.go:740
// Init initializes Iter for iteration.
func (it *Iter) Init(typ *abi.MapType, m *Map) {
	it.typ = typ

	if m == nil || m.used == 0 {
		return
	}

	dirIdx := 0
	var groupSmall groupReference
	if m.dirLen <= 0 {
		// Use dirIdx == -1 as sentinel for small maps.
		dirIdx = -1
		groupSmall.data = m.dirPtr
	}

	it.m = m
	it.entryOffset = rand()
	it.dirOffset = rand()
	it.globalDepth = m.globalDepth
	it.dirIdx = dirIdx
	it.group = groupSmall
	it.clearSeq = m.clearSeq
}

Two rand() calls, one for each offset. Nothing else about the iteration is random: once the offsets are fixed, the walk is completely deterministic.

Where the offsets get used

The directory offset picks the first table:

 go
 
 
// src/internal/runtime/maps/table.go:979
	// Continue iteration until we find a full slot.
	for ; it.dirIdx < it.m.dirLen; it.nextDirIdx() {
		// Resolve the table.
		if it.tab == nil {
			dirIdx := int((uint64(it.dirIdx) + it.dirOffset) & uint64(it.m.dirLen-1))
			newTab := it.m.directoryAt(uintptr(dirIdx))
			if newTab.index != dirIdx {
				// Normally we skip past all duplicates of the
				// same entry in the table (see updates to
				// it.dirIdx at the end of the loop below), so
				// this case wouldn't occur.
				//
				// But on the very first call, we have a
				// completely randomized dirIdx that may refer
				// to a middle of a run of tables in the
				// directory. Do a one-time adjustment of the
				// offset to ensure we start at first index for
				// newTable.
				diff := dirIdx - newTab.index
				it.dirOffset -= uint64(diff)
				dirIdx = newTab.index
			}
			it.tab = newTab
		}

Note the & uint64(it.m.dirLen-1) — a mask, not a modulo, because dirLen is a power of two. And note the comment: the first table is chosen completely at random, and then the offset is adjusted so the walk does not visit the same logical table twice.

The entry offset picks the first slot within a table:

 go
 
 
// src/internal/runtime/maps/table.go:1025
		entryIdx := (it.entryIdx + it.entryOffset) & entryMask
		slotIdx := uintptr(entryIdx & (abi.MapGroupSlots - 1))
		if slotIdx == 0 || it.group.data == nil {
			// Only compute the group (a) when we switch
			// groups (slotIdx rolls over) and (b) on the
			// first iteration in this table (slotIdx may
			// not be zero due to entryOffset).
			groupIdx := entryIdx >> abi.MapGroupSlotsBits
			it.group = it.tab.groups.group(it.typ, groupIdx)
		}

Again a mask, because the table capacity is a power of two. And note slotIdx == 0 || it.group.data == nil — the group is only recomputed when the slot index rolls over or on the very first iteration, which is where entryOffset makes the group index start somewhere unexpected.

Small maps — those that fit in a single group — take a simpler path, but still use the offset:

 go
 
 
// src/internal/runtime/maps/table.go:886
	if it.dirIdx < 0 {
		// Map was small at Init.
		for ; it.entryIdx < abi.MapGroupSlots; it.entryIdx++ {
			k := uintptr(it.entryIdx+it.entryOffset) % abi.MapGroupSlots

			if (it.group.ctrls().get(k) & ctrlEmpty) == ctrlEmpty {
				// Empty or deleted.
				continue
			}

(entryIdx + entryOffset) % MapGroupSlots — a rotation of the eight slots of the group. So even a three-element map comes out in a random order.

The runtime’s random numbers

rand() here is the runtime’s own generator, linked in by linkname:

 go
 
 
// src/internal/runtime/maps/runtime.go:22
//go:linknamestd bootstrapRand runtime.bootstrapRand
func bootstrapRand() uint64

//go:linkname rand
func rand() uint64

and it is the per-M ChaCha8 stream, not math/rand:

 go
 
 
// src/runtime/rand.go:156
// rand returns a random uint64 from the per-m chacha8 state.
// This is called from compiler-generated code.
//
// Do not change signature: used via linkname from other packages.
//
//go:nosplit
//go:linkname rand
func rand() uint64 {
	// Note: We avoid acquirem here so that in the fast path
	// there is just a getg, an inlined c.Next, and a return.
	// The performance difference on a 16-core AMD is
	// 3.7ns/call this way versus 4.3ns/call with acquirem (+16%).
	mp := getg().m
	c := &mp.chacha8
	for {
		// Note: c.Next is marked nosplit,
		// so we don't need to use mp.locks
		// on the fast path, which is that the
		// first attempt succeeds.
		x, ok := c.Next()
		if ok {
			return x
		}
		mp.locks++ // hold m even though c.Refill may do stack split checks
		c.Refill()
		mp.locks--
	}
}

Each OS thread (m) has its own ChaCha8 state, so two goroutines on different threads never contend for a lock to get a random number, and the numbers are not correlated in a way an attacker could exploit. The runtime even keeps a separate, cheaper generator for the places where quality does not matter:

 go
 
 
// src/runtime/rand.go:212
// cheaprand is a non-cryptographic-quality 32-bit random generator
// suitable for calling at very high frequency (such as during scheduling decisions)
// and at sensitive moments in the runtime (such as during stack unwinding).
// it is "cheap" in the sense of both expense and quality.
//
// cheaprand must not be exported to other packages:
// the rule is that other packages using runtime-provided
// randomness must always use rand.
//
// cheaprand should be an internal detail,
// but widely used packages access it using linkname.
// Notable members of the hall of shame include:
// - github.com/bytedance/gopkg
//
// Do not remove or change the type signature.
// See go.dev/issue/67401.
//
//go:linkname cheaprand
//go:nosplit
func cheaprand() uint32 {

Map iteration does not use cheaprand. It uses rand, the good one.

The compiler’s entry point

The compiler-generated code for range goes through the runtime:

 go
 
 
// src/runtime/map.go:142
// mapIterStart initializes the Iter struct used for ranging over maps and
// performs the first step of iteration. The Iter struct pointed to by 'it' is
// allocated on the stack by the compilers order pass or on the heap by
// reflect. Both need to have zeroed it since the struct contains pointers.
func mapIterStart(t *abi.MapType, m *maps.Map, it *maps.Iter) {
	if raceenabled && m != nil {
		callerpc := sys.GetCallerPC()
		racereadpc(unsafe.Pointer(m), callerpc, abi.FuncPCABIInternal(mapIterStart))
	}

	it.Init(t, m)
	it.Next()
}

Init rolls the offsets, Next takes the first step. reflect uses the same entry points, so reflect.Value.MapRange is randomised too.

The `maps` package inherits it

The generic maps package does not reimplement anything — it just ranges:

 go
 
 
// src/maps/iter.go:9
// All returns an iterator over key-value pairs from m.
// The iteration order is not specified and is not guaranteed
// to be the same from one call to the next.
func All[Map ~map[K]V, K comparable, V any](m Map) iter.Seq2[K, V] {
	return func(yield func(K, V) bool) {
		for k, v := range m {
			if !yield(k, v) {
				return
			}
		}
	}
}

The doc comment states the contract; the mechanism is the runtime’s. maps.Keys, maps.Values, maps.Collect and maps.Insert all inherit the same randomisation for free.

Trade-offs

What the randomness buys:

Hash-flooding resistance. An attacker cannot precompute colliding keys, so a map keyed on untrusted input cannot be forced into O(n) behaviour.
Unpredictable ordering. Code that iterates a map to pick “the first” element, or to pick a random victim, does not accidentally become deterministic in a way an attacker can exploit. This is why map iteration order being stable was treated as a security bug every time it leaked.
No cost on the hot path. The offsets are computed once per range, not once per element. A million-element map costs two rand() calls plus two masked adds per table.

What it costs:

Tests that depend on order break. A test that asserts “the first key is a” is testing something the spec never promised. It will pass locally and fail in CI, or pass in CI and fail in production.
Snapshot-like reasoning is impossible. Two iterations of the same unmodified map give different orders, so you cannot zip them.
A tiny cost per range. Two rand() calls — a few nanoseconds — on every loop, including loops over three-element maps.

Caveats

The randomness is per iteration, not per map. Two range loops over the same map get different orders, but they are both drawn from the same per-map hash seed. The seed protects the layout; the offsets protect the order.

It is not cryptographic. The offsets come from the runtime’s ChaCha8 stream, which is a good generator but not a secrets API. If you need a cryptographically random choice of element, use crypto/rand, not map iteration order.

Small maps are randomised too. A map with one element has one order. A map with two has two. A map with three has six possible orders, all reachable.

maps.All and friends do not snapshot. An iterator over a map that is being mutated concurrently will not crash (the runtime detects concurrent map write and map iteration and throws), but a map mutated between two iterations can yield different sets.

Do not rely on “sorted-ish” behaviour. Some maps happen to iterate in a quasi-sorted order when the keys are small integers, because the hash of a small integer is roughly the integer. That is an artefact of the hasher, not a guarantee, and it disappears with strings, structs, or large integers.

The old implementation randomised differently. Before the Swiss-table rewrite, the runtime picked one random bucket and one random offset within that bucket. The current implementation picks a random directory index and a random slot offset. The guarantee is the same; the mechanism changed with the data structure.

Hash-flooding defence does not extend to your own data structures. The per-map seed protects Go maps. If you wrote your own hash table keyed by untrusted input, you have to randomise the hash yourself.

Wrapping up

The one thing to remember: two independent random mechanisms — a per-map hash seed that defeats hash flooding, and a per-iteration random offset that defeats order prediction — both fed by the runtime’s per-M ChaCha8 generator.

The part people get wrong: assuming the random order is a quirk of the old bucket implementation. It is a stated guarantee of the specification (“not guaranteed to be the same from one iteration to the next”), and it survived the complete rewrite of Go’s map internals.

What to go do about it: grep your tests for assertions that depend on map order and fix them — sort the keys first. Then, if you accept untrusted input as map keys, make sure you are on a Go version with per-map hash seeds (Go 1.14 and later), because that is the mechanism that actually stops the CPU-burning attack.

Weak Pointers in Go: The Runtime's Special Span for Non-Tracked Objects

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

TL;DR: weak.Pointer[T] is a pointer the garbage collector does not honour. It is a specialWeakHandle record on the object’s span holding an atomic.Uintptr — a raw address, not a Go pointer — so the GC never treats it as a reference. When the object dies, the sweeper zeroes the handle.

Every garbage-collected language eventually needs a way to say “I would like to point at that object, but please don’t keep it alive for me”. Caches need it. Canonicalisation tables need it. Graph algorithms with weak edges need it. Go did not have it for a very long time, and the usual workaround — runtime.SetFinalizer plus a map[uintptr]T — is a mess of resurrection semantics and race conditions.

Go 1.24 added the weak package. It is small, and the implementation is one of the more elegant pieces of runtime code in the tree, because it reuses machinery that already existed: span specials.

The API

The whole package is one type and two methods:

 go
 
 
// src/weak/pointer.go:60
type Pointer[T any] struct {
	// Mention T in the type definition to prevent conversions
	// between Pointer types, like we do for sync/atomic.Pointer.
	_ [0]*T
	u unsafe.Pointer
}

// Make creates a weak pointer from a pointer to some value of type T.
func Make[T any](ptr *T) Pointer[T] {
	// Explicitly force ptr to escape to the heap.
	ptr = abi.Escape(ptr)

	var u unsafe.Pointer
	if ptr != nil {
		u = runtime_registerWeakPointer(unsafe.Pointer(ptr))
	}
	runtime.KeepAlive(ptr)
	return Pointer[T]{u: u}
}

// Value returns the original pointer used to create the weak pointer.
// It returns nil if the value pointed to by the original pointer was reclaimed by
// the garbage collector.
// If a weak pointer points to an object with a finalizer, then Value will
// return nil as soon as the object's finalizer is queued for execution.
func (p Pointer[T]) Value() *T {
	if p.u == nil {
		return nil
	}
	return (*T)(runtime_makeStrongFromWeak(p.u))
}

Three details in twenty lines carry most of the weight.

The _ [0]*T field. It is a zero-sized array whose only job is to make the type mention T, so that Pointer[int] and Pointer[string] are distinct types and cannot be converted between each other. The same trick sync/atomic.Pointer uses.

abi.Escape(ptr). The pointed-to object must live on the heap, because the runtime stores a special record on the span that contains it, and the stack has no spans. Escape is a compiler intrinsic that forces the argument to escape:

 go
 
 
// src/internal/abi/escape.go:27
// Escape forces any pointers in x to escape to the heap.
func Escape[T any](x T) T {
	if alwaysFalse {
		escapeSink = x
	}
	return x
}

The alwaysFalse branch is never taken, but the compiler’s escape analysis sees the assignment to a global sink and therefore concludes that x escapes. It compiles down to nothing at runtime.

runtime.KeepAlive(ptr) after the call. Between the escape and the registration, the compiler could in principle prove ptr is dead. The KeepAlive makes sure the object is still alive at the moment the weak handle is installed. This is the first of the runtime’s documented weak pointer invariants:

Strong-to-weak conversions must ensure the strong pointer remains live until the weak handle is installed. This ensures that creating a weak pointer cannot fail.

What is actually stored

Pointer[T].u is an unsafe.Pointer, but it does not point at the target object. It points at a handle — a heap cell holding the target’s address as a uintptr:

 go
 
 
// src/runtime/mheap.go:2391
// specialWeakHandle is allocated from non-GC'd memory, so any heap
// pointers must be specially handled.
type specialWeakHandle struct {
	_ sys.NotInHeap
	special special
	// handle is a reference to the actual weak pointer.
	// It is always heap-allocated and must be explicitly kept
	// live so long as this special exists.
	handle *atomic.Uintptr
}

//go:linkname internal_weak_runtime_registerWeakPointer weak.runtime_registerWeakPointer
func internal_weak_runtime_registerWeakPointer(p unsafe.Pointer) unsafe.Pointer {
	return unsafe.Pointer(getOrAddWeakHandle(p))
}

//go:linkname internal_weak_runtime_makeStrongFromWeak weak.runtime_makeStrongFromWeak
func internal_weak_runtime_makeStrongFromWeak(u unsafe.Pointer) unsafe.Pointer {
	handle := (*atomic.Uintptr)(u)

The address lives inside an atomic.Uintptr, which is a uintptr — an integer. The garbage collector does not treat integers as references. That is the whole trick. The weak pointer looks like a pointer to the GC, and is not one.

The specialWeakHandle struct itself is marked sys.NotInHeap, and it is allocated out of a fixalloc arena, i.e. outside the garbage-collected heap. That means the GC will not find it by scanning, so the runtime has to scan it by hand. You will see that below.

Note also the two //go:linkname declarations: the weak package reaches into the runtime for registerWeakPointer and makeStrongFromWeak. This is the escape hatch that article four is about, and it is the sanctioned way to do it — the runtime pushes the symbols, the linker checks the pull.

Registering the handle

 go
 
 
// src/runtime/mheap.go:2508
// Retrieves or creates a weak pointer handle for the object p.
func getOrAddWeakHandle(p unsafe.Pointer) *atomic.Uintptr {
	if debug.sbrk != 0 {
		// debug.sbrk never frees memory, so it'll never go nil. However, we do still
		// need a weak handle that's specific to p. Use the immortal weak handle map.
		// Keep p alive across the call to getOrAdd defensively, though it doesn't
		// really matter in this particular case.
		handle := mheap_.immortalWeakHandles.getOrAdd(uintptr(p))
		KeepAlive(p)
		return handle
	}

	// First try to retrieve without allocating.
	if handle := getWeakHandle(p); handle != nil {
		// Keep p alive for the duration of the function to ensure
		// that it cannot die while we're trying to do this.
		KeepAlive(p)
		return handle
	}

	lock(&mheap_.speciallock)
	s := (*specialWeakHandle)(mheap_.specialWeakHandleAlloc.alloc())
	unlock(&mheap_.speciallock)

The lookup path is getWeakHandle, which searches the span’s specials list for an existing record at the right byte offset:

 go
 
 
// src/runtime/mheap.go:2594
func getWeakHandle(p unsafe.Pointer) *atomic.Uintptr {
	span := spanOfHeap(uintptr(p))
	if span == nil {
		if isGoPointerWithoutSpan(p) {
			return mheap_.immortalWeakHandles.getOrAdd(uintptr(p))
		}
		throw("getWeakHandle on invalid pointer")
	}

	// Ensure that the span is swept.
	// Sweeping accesses the specials list w/o locks, so we have
	// to synchronize with it. And it's just much safer.
	mp := acquirem()
	span.ensureSwept()

	offset := uintptr(p) - span.base()

	lock(&span.speciallock)

	// Find the existing record and return the handle if one exists.
	var handle *atomic.Uintptr
	iter, exists := span.specialFindSplicePoint(offset, _KindSpecialWeakHandle)
	if exists {
		handle = ((*specialWeakHandle)(unsafe.Pointer(*iter))).handle
	}
	unlock(&span.speciallock)
	releasem(mp)

	// Keep p alive for the duration of the function to ensure
	// that it cannot die while we're trying to do this.
	KeepAlive(p)
	return handle
}

Two very important facts fall out of this.

One. The special is attached at a byte offset into the object, not to the object as a whole. offset := uintptr(p) - span.base(). So a weak pointer to the third field of a struct gets its own handle, distinct from a weak pointer to the first field. That matches the documented behaviour:

Two Pointer values compare equal if and only if the pointers from which they were created compare equal. … If multiple weak pointers are made to different offsets within the same object (for example, pointers to different fields of the same struct), those pointers will not compare equal. In other words, weak pointers map to objects and offsets within those objects, not plain addresses.

So interior pointers are supported. What is not supported is a pointer that is not inside a heap allocation at all: spanOfHeap returns nil for a stack address or a random integer, isGoPointerWithoutSpan only rescues globals and the zero-sized zerobase, and everything else gets a throw("getWeakHandle on invalid pointer").

Two. Weak handles are canonical per (object, offset). Two calls to weak.Make(&x) return the same handle. The runtime guarantees this so that the same object does not accumulate hundreds of special records:

Weak handles are unique and canonical for each byte offset into an object that a strong pointer may point to, until an object becomes unreachable.

Now the padding comment, which is a small masterpiece of defensive engineering:

 go
 
 
// src/runtime/mheap.go:2532
	// N.B. Pad the weak handle to ensure it doesn't share a tiny
	// block with any other allocations. This can lead to leaks, such
	// as in go.dev/issue/76007. As an alternative, we could consider
	// using the currently-unused 8-byte noscan size class.
	type weakHandleBox struct {
		h atomic.Uintptr
		_ [maxTinySize - unsafe.Sizeof(atomic.Uintptr{})]byte
	}
	handle := &(new(weakHandleBox).h)
	s.special.kind = _KindSpecialWeakHandle
	s.handle = handle
	handle.Store(uintptr(p))
	if addspecial(p, &s.special, false) {

The Go runtime has a “tiny allocator” that packs several small pointer-free objects into one 16-byte block. If the weak handle were allocated with new(atomic.Uintptr), it would be 8 bytes and could be packed with other objects. Then when the handle is swept, the whole block would be freed — including unrelated objects that merely happened to share it. Worse, the handle might never be freed, because a live neighbour keeps the block alive, and the weak pointer would never become nil. The padding forces the handle into its own allocation.

This is exactly the hazard the weak package documents:

because [Pointer.Value] is not guaranteed to eventually return nil, even after an object is no longer referenced, the runtime is allowed to perform a space-saving optimization that batches objects together in a single allocation slot. The weak pointer for an unreferenced object in such an allocation may never become nil if it always exists in the same batch as a referenced object.

The special kinds

Weak pointers get their own entry in the runtime’s list of span specials:

 go
 
 
// src/runtime/mheap.go:1935
const (
	// _KindSpecialTinyBlock indicates that a given allocation is a tiny block.
	// Ordered before KindSpecialFinalizer and KindSpecialCleanup so that it
	// always appears first in the specials list.
	// Used only if debug.checkfinalizers != 0.
	_KindSpecialTinyBlock = 1
	// _KindSpecialFinalizer is for tracking finalizers.
	_KindSpecialFinalizer = 2
	// _KindSpecialWeakHandle is used for creating weak pointers.
	_KindSpecialWeakHandle = 3
	// _KindSpecialProfile is for memory profiling.
	_KindSpecialProfile = 4
	// _KindSpecialReachable is a special used for tracking
	// reachability during testing.
	_KindSpecialReachable = 5
	// _KindSpecialPinCounter is a special used for objects that are pinned
	// multiple times
	_KindSpecialPinCounter = 6
	// _KindSpecialCleanup is for tracking cleanups.
	_KindSpecialCleanup = 7
	// _KindSpecialCheckFinalizer adds additional context to a finalizer or cleanup.
	// Used only if debug.checkfinalizers != 0.
	_KindSpecialCheckFinalizer = 8
	// _KindSpecialBubble is used to associate objects with synctest bubbles.
	_KindSpecialBubble = 9
	// _KindSpecialSecret is a special used to mark an object
	// as needing zeroing immediately upon freeing.
	_KindSpecialSecret = 10
)

A “special” is a small record hanging off a span, describing something extra about one object in that span: it has a finalizer, it has a cleanup, it is being profiled, or — in our case — it has a weak handle.

 go
 
 
// src/runtime/mheap.go:1965
type special struct {
	_ sys.NotInHeap
	next *special // linked list in span
	offset uintptr // span offset of object
	kind byte // kind of special
}

Note _ sys.NotInHeap: the specials list lives outside the GC heap, in memory the collector never scans. That is why every kind of special needs its own explicit handling in the mark phase.

How the GC treats weak references

There are exactly two places the collector touches weak handles.

Marking: the handle is a root, the target is not

 go
 
 
// src/runtime/mgcmark.go:404
	// Objects with weak handles have only one invariant related
	// to this function: weak handle specials (which are not in the
	// garbage collected heap) are roots. In practice, this means
	// the handle field must be scanned. Note that the value the
	// handle pointer referenced does *not* need to be scanned. See
	// the definition of specialWeakHandle for details.

and the code that does it:

 go
 
 
// src/runtime/mgcmark.go:453
			lock(&s.speciallock)
			for sp := s.specials; sp != nil; sp = sp.next {
				switch sp.kind {
				case _KindSpecialFinalizer:
					gcScanFinalizer((*specialfinalizer)(unsafe.Pointer(sp)), s, gcw)
				case _KindSpecialWeakHandle:
					// The special itself is a root.
					spw := (*specialWeakHandle)(unsafe.Pointer(sp))
					scanblock(uintptr(unsafe.Pointer(&spw.handle)), goarch.PtrSize, &oneptrmask[0], gcw, nil)
				case _KindSpecialCleanup:
					gcScanCleanup((*specialCleanup)(unsafe.Pointer(sp)), gcw)
				}
			}
			unlock(&s.speciallock)

Read the comment carefully: “the value the handle pointer referenced does not need to be scanned”. The scanblock call marks the handle field itself — that is, the *atomic.Uintptr allocation — so that the handle cell stays alive. It does not mark the object the handle points at. The target object is free to die.

This is the difference between a weak pointer and a strong one, expressed in one line of code: the pointer to the handle is scanned; the pointer inside the handle is not.

Sweeping: the handle is zeroed

When the sweeper finds an unmarked object, it walks the object’s specials and frees them. For a weak handle, “freeing” means storing zero:

 go
 
 
// src/runtime/mheap.go:2779
func freeSpecial(s *special, p unsafe.Pointer, size uintptr) {
	switch s.kind {
	case _KindSpecialFinalizer:
		sf := (*specialfinalizer)(unsafe.Pointer(s))
		queuefinalizer(p, sf.fn, sf.nret, sf.fint, sf.ot)
		lock(&mheap_.speciallock)
		mheap_.specialfinalizeralloc.free(unsafe.Pointer(sf))
		unlock(&mheap_.speciallock)
	case _KindSpecialWeakHandle:
		sw := (*specialWeakHandle)(unsafe.Pointer(s))
		sw.handle.Store(0)
		lock(&mheap_.speciallock)
		mheap_.specialWeakHandleAlloc.free(unsafe.Pointer(s))
		unlock(&mheap_.speciallock)

sw.handle.Store(0) — the address is erased. From that moment on, every weak pointer to that object sees a zero handle.

The sweeper does this even for objects that are being finalised:

 go
 
 
// src/runtime/mgcsweep.go:593
			if hasFinAndRevived {
				// Pass 2: queue all finalizers and clear any weak handles. Weak handles are cleared
				// before finalization as specified by the weak package. See the documentation
				// for that package for more details.
				for siter.valid() && siter.s.offset < endOffset {
					// Find the exact byte for which the special was setup
					// (as opposed to object beginning).
					special := siter.s
					p := s.base() + special.offset
					if special.kind == _KindSpecialFinalizer || special.kind == _KindSpecialWeakHandle {
						siter.unlinkAndNext()
						freeSpecial(special, unsafe.Pointer(p), size)
					} else {
						// All other specials only apply when an object is freed,
						// so just keep the special record.
						siter.next()
					}
				}

So the ordering is: weak handles are cleared first, then the finalizer is queued. A weak pointer never observes a finalised-but-resurrected object. The runtime states this as an invariant:

Weak handles contain nil as soon as an object becomes unreachable the first time, before a finalizer makes it reachable again. New weak handles created after resurrection are newly unique.

Converting back to a strong pointer

Value() is not a simple dereference. It has to handle the race where the GC is running right now:

 go
 
 
// src/runtime/mheap.go:2407
//go:linkname internal_weak_runtime_makeStrongFromWeak weak.runtime_makeStrongFromWeak
func internal_weak_runtime_makeStrongFromWeak(u unsafe.Pointer) unsafe.Pointer {
	handle := (*atomic.Uintptr)(u)

	// Prevent preemption. We want to make sure that another GC cycle can't start
	// and that work.strongFromWeak.block can't change out from under us.
	mp := acquirem()

	// Yield to the GC if necessary.
	if work.strongFromWeak.block {
		releasem(mp)

		// Try to park and wait for mark termination.
		// N.B. gcParkStrongFromWeak calls acquirem before returning.
		mp = gcParkStrongFromWeak()
	}

	p := handle.Load()
	if p == 0 {
		releasem(mp)
		return nil
	}

The work.strongFromWeak.block mechanism exists because converting a weak pointer to a strong one during the mark phase could resurrect an object that the collector has already decided is garbage. If the mark phase is still running, the conversion parks the goroutine until mark termination completes, at which point the answer is unambiguous.

 go
 
 
// src/runtime/mheap.go:2446
	// Ensure the span is swept.
	span.ensureSwept()

	// Now we can trust whatever we get from handle, so make a strong pointer.
	//
	// Even if we just swept some random span that doesn't contain this object, because
	// this object is long dead and its memory has since been reused, we'll just observe nil.
	ptr := unsafe.Pointer(handle.Load())

	// This is responsible for maintaining the same GC-related
	// invariants as the Yuasa part of the write barrier. During
	// the mark phase, it's possible that we just created the only
	// valid pointer to the object pointed to by ptr. If it's only
	// ever referenced from our stack, and our stack is blackened
	// already, we could fail to mark it. So, mark it now.
	if gcphase != _GCoff {
		shade(uintptr(ptr))
	}
	releasem(mp)

That shade call is the subtle bit. By materialising a strong pointer to the object during the mark phase, we might have created the only reference to it, and if the stack frame that holds it has already been blackened, the object would never be marked and would be swept out from under us. Shading it fixes that. It is the same invariant the Yuasa write barrier maintains.

Trade-offs

What weak pointers buy you:

Caches that shrink. A map[K]weak.Pointer[V] does not pin V.
Canonicalisation tables. The unique package is built on them.
No resurrection semantics. Unlike finalizers, weak pointers never resurrect anything, so they cannot be used to resurrect objects by accident.
Cheap. A weak pointer is one word. A weak handle is one 16-byte allocation plus one special record.

What they cost:

One special record per weak-referenced object. Specials live in a per-span linked list, and a span full of weak pointers has a long list.
A handle allocation per object. The handle is padded to 16 bytes so it cannot be packed into a tiny block with unrelated objects.
Weak-to-strong conversion can block. During mark termination, a Value() call parks the goroutine.
Value() is not guaranteed to return nil. If the object was batched with a live neighbour, or the program exits first, the weak pointer may never observe the death of its target.

Caveats

Value() returning nil does not mean the object was freed. It means the object is no longer guaranteed to be alive. The runtime may keep the memory around; you simply may not use it.

Value() returning non-nil does not mean the object will stay alive. The moment Value() returns, the strong pointer it gave you is on your stack and the object is alive. But if you store that pointer somewhere and drop your last other reference, it can still die. Use runtime.KeepAlive if you need the object to survive across a call.

You cannot make a weak pointer to a stack variable. weak.Make forces the target to the heap, but if you hand it a pointer into a stack frame, the runtime throws getWeakHandle on invalid pointer.

A weak pointer to a global works, but via a different path. Globals have no span, so they go into the immortalWeakHandleMap, a lock-free append-only hash trie, and never become nil.

Weak pointers and finalizers interact in a specific order. The weak handle is cleared before the finalizer runs. If you were expecting to read a finalised object’s contents through a weak pointer, you will get nil.

Do not confuse weak.Pointer with runtime.SetFinalizer. Finalizers keep the object alive for one extra GC cycle and then resurrect it. Weak pointers do neither.

Wrapping up

The one thing to remember: a weak pointer stores the target’s address in an atomic.Uintptr — an integer, not a pointer — so the garbage collector never treats it as a reference. The GC scans the handle, not the target.

The part people get wrong: weak.Pointer.Value() is allowed to return non-nil forever. The runtime batches tiny pointer-free objects together to save space, and a batch containing a live object keeps its dead neighbours weakly reachable. unique copes with this; hand-rolled weak-map code usually does not.

What to go do about it: if you are building a cache with map[K]V and worrying that it grows without bound, that is exactly the shape weak pointers were made for. Store weak.Pointer[V] in the map, check Value() on lookup, and delete the entry when it comes back nil.

runtime.AddCleanup: How Go Replaced Finalizers With a Queue of Specials

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

TL;DR: runtime.SetFinalizer was the only way to run code when an object became unreachable, and it was full of sharp edges: cleanups ran on a single goroutine, could not be removed reliably, could not carry an argument, and could keep an entire object alive forever. runtime.AddCleanup replaces all of that. It attaches a special record to the object’s span, hands the closure to a lock-free queue of 512-byte blocks, and wakes a small pool of dedicated goroutines to run them. Cleanups run in parallel, they can be cancelled, and they take an arbitrary typed argument that the GC does not have to scan.

runtime.SetFinalizer is one of those Go features that everybody has used once, everybody has been bitten by, and nobody has a good answer for. The documentation warns you:

If a cyclic structure includes a block with a finalizer, that cycle is not guaranteed to be garbage collected and the finalizer is not guaranteed to run, because there is no ordering that respects the dependencies.

That is the kind of sentence that only exists because the implementation cannot do better. Go 1.24 added runtime.AddCleanup, a redesigned replacement. The interesting part is how it works.

The problem with finalizers

A finalizer has to satisfy two conflicting requirements:

It must not run while the object is still reachable.
It must run after the object becomes unreachable — otherwise resources leak.

The classic solution is to resurrect the object one more time: when the GC finds an unreachable object with a finalizer, it queues the finalizer and marks the object as live (so it survives this cycle), then runs the finalizer at the end of the cycle. The object becomes garbage again after that, and is collected in the next cycle.

The consequence is well known: finalizers are delayed by at least one GC cycle, and by an unbounded amount of time if the GC is not running. In a program that allocates a lot and rarely triggers a GC, finalizers pile up.

Worse, the finalizer mechanism requires the runtime to keep the finalizer function alive, and — in the old design — to keep the whole object alive too, since the finalizer might want to inspect it.

And then there is the killer: SetFinalizer associates a finalizer with an object by pointer. If you set a finalizer on an interior pointer, the runtime has to find the containing object. If you set two finalizers on the same object, the second replaces the first. And if the object is part of a cycle with other finalized objects, the cycle is never collected.

The new design: cleanups

runtime.AddCleanup splits the problem in two. The cleanup function and its argument live in a separate object, and only a pointer to that separate object is attached to the object being cleaned up.

 go
 
 
// src/runtime/mcleanup.go:75
//go:nocheckptr
func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup {
	// This is marked nocheckptr because checkptr doesn't understand the
	// pointer manipulation done when looking at closure pointers.
	// Similar code in mbitmap.go works because the functions are
	// go:nosplit, which implies go:nocheckptr (CL 202158).

	// Explicitly force ptr and cleanup to escape to the heap.
	ptr = abi.Escape(ptr)
	cleanup = abi.Escape(cleanup)

Forcing the escape is a subtle but essential step. ptr and cleanup must be heap-allocated, because the runtime is going to hold raw pointers to them in structures that the compiler’s escape analysis cannot see.

The documentation makes the ordering contract explicit:

A cleanup may run as soon as an object becomes unreachable. In order to use cleanups correctly, the program must ensure that the object is reachable until it is safe to run its cleanup. Objects stored in global variables, or that can be found by tracing pointers from a global variable, are reachable. A function argument or receiver may become unreachable at the last point where the function mentions it. To ensure a cleanup does not get called prematurely, pass the object to the [KeepAlive] function after the last point where the object must remain reachable.

runtime.KeepAlive is the tool. It is a compiler intrinsic that keeps its argument reachable until the point of the call — not “until the end of the function”, which is what people usually assume.

The argument is boxed on purpose

Here is a genuinely clever piece of the implementation. The cleanup’s argument arg must be stored somewhere so that the closure can be called later. But if you store it in the same heap block as the object being cleaned up, you create a reference cycle and the object never dies.

So the argument gets its own allocation:

 go
 
 
// src/runtime/mcleanup.go:112
	// Create new storage for the argument.
	var argv *S
	if size := unsafe.Sizeof(arg); size < maxTinySize && argType.PtrBytes == 0 {
		// Side-step the tiny allocator to avoid liveness issues, since this box
		// will be treated like a root by the GC. We model the box as an array of
		// uintptrs to guarantee maximum allocator alignment.
		//
		// TODO(mknyszek): Consider just making space in cleanupFn for this. The
		// unfortunate part of this is it would grow specialCleanup by 16 bytes, so
		// while there wouldn't be an allocation, *every* cleanup would take the
		// memory overhead hit.
		box := new([maxTinySize / goarch.PtrSize]uintptr)
		argv = (*S)(unsafe.Pointer(box))
	} else {
		argv = new(S)
	}
	*argv = arg

Two things to note.

The tiny allocator is deliberately side-stepped. Go’s tiny allocator packs several small, pointer-free objects into one 16-byte allocation. That is a wonderful optimisation for throughput, but here it is a correctness hazard: the “box” holding the cleanup argument would be treated by the GC as a root for the whole tiny block, which means every other object packed alongside it would also be kept alive. The code allocates an array of uintptrs instead — same size class, but a distinct allocation, and alignment guaranteed.

The comment explains the rejected alternative. Putting the argument inline in cleanupFn would avoid the allocation entirely, but it would grow specialCleanup by 16 bytes — and every cleanup pays that, even ones with a pointer argument that does not need the space. The authors chose one allocation per cleanup over a permanent 16-byte tax on all of them. That is a good example of the runtime optimising for the common case.

The special record

Now the interesting part. The cleanup is not attached to the object as a normal Go field — it is attached as a special, a side table that hangs off the object’s span.

 go
 
 
// src/runtime/mheap.go:2153
type specialCleanup struct {
	_ sys.NotInHeap
	special special
	cleanup cleanupFn
	// Globally unique ID for the cleanup, obtained from mheap_.cleanupID.
	id uint64
}

The _ sys.NotInHeap marker is the first field, and it is a promise to the GC: this structure lives in memory the GC does not scan, so the runtime has to scan it by hand.

Attaching it takes a global lock:

 go
 
 
// src/runtime/mheap.go:2165
func addCleanup(p unsafe.Pointer, c cleanupFn) uint64 {
	// TODO(mknyszek): Consider pooling specialCleanups on the P
	// so we don't have to take the lock every time. Just locking
	// is a considerable part of the cost of AddCleanup. This
	// would also require reserving some cleanup IDs on the P.
	lock(&mheap_.speciallock)
	s := (*specialCleanup)(mheap_.specialCleanupAlloc.alloc())
	mheap_.cleanupID++ // Increment first. ID 0 is reserved.
	id := mheap_.cleanupID
	unlock(&mheap_.speciallock)
	s.special.kind = _KindSpecialCleanup
	s.cleanup = c
	s.id = id

The TODO is honest: AddCleanup takes a global mutex. That is not free. The authors note that pooling the special records per-P would avoid it, at the cost of having to reserve cleanup IDs per-P as well. This is a known rough edge, and it is the price of the design.

After attaching the special, the runtime makes sure the cleanup stays reachable — and does it correctly, which took a bug fix:

 go
 
 
// src/runtime/mheap.go:2179
	mp := acquirem()
	addspecial(p, &s.special, true)
	// This is responsible for maintaining the same
	// GC-related invariants as markrootSpans in any
	// situation where it's possible that markrootSpans
	// has already run but mark termination hasn't yet.
	if gcphase != _GCoff {
		// Mark the cleanup itself, since the
		// special isn't part of the GC'd heap.
		gcScanCleanup(s, &mp.p.ptr().gcw)
	}
	releasem(mp)
	// Keep c and its referents alive. There's a window in this function
	// where it's only reachable via the special while the special hasn't
	// been added to the specials list yet. This is similar to a bug
	// discovered for weak handles, see #70455.
	KeepAlive(c)
	return id

The gcphase != _GCoff check is subtle. If the GC is mid-cycle, the span-root scanning phase may already have passed this span. Adding a special that the GC has not seen would mean the cleanup function (and everything it references) could be collected while still reachable from the special. So the runtime marks it explicitly.

And KeepAlive(c) at the end closes the window the comment describes: between allocating the special and adding it to the span’s list, the only reference to the cleanup function is a local variable. KeepAlive tells the compiler not to shorten the function’s argument liveness past that point.

How the GC finds cleanups

The GC scans spans that have the “specials” bit set. From src/runtime/mgcmark.go:

 go
 
 
// src/runtime/mgcmark.go:451
			// Lock the specials to prevent a special from being
			// removed from the list while we're traversing it.
			lock(&s.speciallock)
			for sp := s.specials; sp != nil; sp = sp.next {
				switch sp.kind {
				case _KindSpecialFinalizer:
					gcScanFinalizer((*specialfinalizer)(unsafe.Pointer(sp)), s, gcw)
				case _KindSpecialWeakHandle:
					// The special itself is a root.
					spw := (*specialWeakHandle)(unsafe.Pointer(sp))
					scanblock(uintptr(unsafe.Pointer(&spw.handle)), goarch.PtrSize, &oneptrmask[0], gcw, nil)
				case _KindSpecialCleanup:
					gcScanCleanup((*specialCleanup)(unsafe.Pointer(sp)), gcw)
				}
			}
			unlock(&s.speciallock)

And gcScanCleanup is startlingly short:

 go
 
 
// src/runtime/mgcmark.go:490
func gcScanCleanup(spc *specialCleanup, gcw *gcWork) {
	// The special itself is a root.
	scanblock(uintptr(unsafe.Pointer(&spc.cleanup)), unsafe.Sizeof(cleanupFn{}), &cleanupFnPtrMask[0], gcw, nil)
}

Compare with the finalizer version right above it:

 go
 
 
// src/runtime/mgcmark.go:472
func gcScanFinalizer(spf *specialfinalizer, s *mspan, gcw *gcWork) {
	// Don't mark finalized object, but scan it so we retain everything it points to.

	// A finalizer can be set for an inner byte of an object, find object beginning.
	p := s.base() + spf.special.offset/s.elemsize*s.elemsize

	// Mark everything that can be reached from
	// the object (but *not* the object itself or
	// we'll never collect it).
	if !s.spanclass.noscan() {
		scanObject(p, gcw)
	}

	// The special itself is also a root.
	scanblock(uintptr(unsafe.Pointer(&spf.fn)), goarch.PtrSize, &oneptrmask[0], gcw, nil)
}

The finalizer scans the object. The cleanup does not.

That is the whole design difference in five lines. A finalizer must keep the object alive (so it can be resurrected and so its fields stay valid), so the GC scans the object and marks everything reachable from it — which is exactly why finalizers create cycles that are never collected.

A cleanup never touches the object. It only holds the cleanup function and its separately-boxed argument. So the object can be collected immediately, and the cleanup can run on an object whose memory has already been reclaimed.

The pointer mask cleanupFnPtrMask is [...]uint8{0b111} — three pointer-sized words, all of which are pointers:

 go
 
 
// src/runtime/mcleanup.go:299
type cleanupFn struct {
	// call is an adapter function that understands how to safely call fn(*arg).
	call func(*funcval, unsafe.Pointer)
	fn *funcval // cleanup function passed to AddCleanup.
	arg unsafe.Pointer // pointer to argument to pass to cleanup function.
}

Three words, three pointer bits, one scanblock call. Very cheap compared to scanning a whole object graph.

The queue: 512-byte blocks and a lock-free stack

When the sweeper decides an object with a cleanup is dead, the cleanup is enqueued. The queue is not a channel, not a mutex-protected slice — it is a lock-free stack of fixed-size blocks:

 go
 
 
// src/runtime/mcleanup.go:284
const cleanupBlockSize = 512

// cleanupBlock is an block of cleanups to be executed.
//
// cleanupBlock is allocated from non-GC'd memory, so any heap pointers
// must be specially handled. The GC and cleanup queue currently assume
// that the cleanup queue does not grow during marking (but it can shrink).
type cleanupBlock struct {
	cleanupBlockHeader
	cleanups [(cleanupBlockSize - unsafe.Sizeof(cleanupBlockHeader{})) / unsafe.Sizeof(cleanupFn{})]cleanupFn
}

A 512-byte block holds a few dozen cleanupFn values. The block is allocated from non-GC’d memory — persistentalloc — so the GC never scans it, which is why the cleanupFnPtrMask scanning above is essential for correctness rather than merely an optimisation.

The header carries the bookkeeping:

 go
 
 
// src/runtime/mcleanup.go:308
type cleanupBlockHeader struct {
	_ sys.NotInHeap
	lfnode
	alllink *cleanupBlock

	// n is sometimes accessed atomically.
	//
	// The invariant depends on what phase the garbage collector is in.
	// During the sweep phase (gcphase == _GCoff), each block has exactly
	// one owner, so it's always safe to update this without atomics.
	// But if this *could* be updated during the mark phase, it must be
	// updated atomically to synchronize with the garbage collector
	// scanning the block as a root.
	n uint32
}

That comment is a whole concurrency protocol in prose. During the sweep phase the block has exactly one owner, so n can be a plain increment. But if the block could be modified during the mark phase, n would have to be atomic, because the GC might be scanning the block as a root at the same time.

The queue itself separates “full” blocks from “free” blocks into two lock-free stacks, with the work counter carefully isolated on its own cache line:

 go
 
 
// src/runtime/mcleanup.go:366
type cleanupQueue struct {
	// Stack of full cleanup blocks.
	full lfstack
	workUnits atomic.Uint64 // length of full; decrement before pop from full, increment after push to full
	_ [cpu.CacheLinePadSize - unsafe.Sizeof(lfstack(0)) - unsafe.Sizeof(atomic.Uint64{})]byte

	// Stack of free cleanup blocks.
	free lfstack

	// flushed indicates whether all local cleanupBlocks have been
	// flushed, and we're in a period of time where this condition is
	// stable (after the last sweeper, before the next sweep phase
	// begins).
	flushed atomic.Bool // Next to free because frequently accessed together.
	...
	// Goroutine block state.
	lock mutex

	// sleeping is the list of sleeping cleanup goroutines.
	//
	// Protected by lock.
	sleeping gList

The cpu.CacheLinePadSize padding between workUnits and free is the classic false-sharing avoidance: workUnits is hammered by the sweeper (producer) and by the cleanup goroutines (consumers), while free is only touched by producers.

The sweeper enqueues, per-P

Enqueueing happens on the P that is doing the sweeping, and the block is cached on that P:

 go
 
 
// src/runtime/mcleanup.go:459
// enqueue queues a single cleanup for execution.
//
// Called by the sweeper, and only the sweeper.
func (q *cleanupQueue) enqueue(c cleanupFn) {
	mp := acquirem()
	pp := mp.p.ptr()
	b := pp.cleanups
	if b == nil {
		if q.flushed.Load() {
			q.flushed.Store(false)
		}
		b = (*cleanupBlock)(q.free.pop())
		if b == nil {
			b = (*cleanupBlock)(persistentalloc(cleanupBlockSize, tagAlign, &memstats.gcMiscSys))
			for {
				next := (*cleanupBlock)(q.all.Load())
				b.alllink = next
				if q.all.CompareAndSwap(unsafe.Pointer(next), unsafe.Pointer(b)) {
					break
				}
			}
		}
		pp.cleanups = b
	}
	if full := b.enqueue(c); full {
		q.full.push(&b.lfnode)
		pp.cleanups = nil
		q.addWork(1)
	}
	pp.cleanupsQueued++
	releasem(mp)
}

The per-P caching means the common case (a few cleanups on this P) never touches a shared structure at all. Only when a block fills up does it go on the global full stack, and the block is recycled from the global free stack.

Blocks are allocated from persistentalloc — non-GC’d, never returned to the OS — and recycled through the free stack, so the steady-state allocation rate of the cleanup system is essentially zero.

Flushing and waking the workers

At the end of the sweep phase, all the partially-filled per-P blocks are coalesced and pushed to the global stack:

 go
 
 
// src/runtime/mcleanup.go:528
func (q *cleanupQueue) flush() {
	mp := acquirem()
	flushed := 0
	emptied := 0
	missing := 0

	// Coalesce the partially-filled blocks to present a more accurate picture of demand.
	// We use the number of coalesced blocks to process as a signal for demand to create
	// new cleanup goroutines.
	var cb *cleanupBlock
	for _, pp := range allp {
		...
	}

The comment explains why coalescing matters: it is not about correctness but about demand estimation. The number of coalesced blocks is used as a proxy for “how many cleanup goroutines do we need”.

The wake-up logic is where the parallelism comes from:

 go
 
 
// src/runtime/mcleanup.go:588
// needsWake returns true if cleanup goroutines may need to be awoken or created to handle cleanup load.
func (q *cleanupQueue) needsWake() bool {
	return q.workUnits.Load() > 0 && (q.asleep.Load() > 0 || q.ng.Load() < maxCleanupGs())
}

So there is a maximum number of cleanup goroutines, and the runtime creates them on demand up to that limit:

 go
 
 
// src/runtime/mcleanup.go:708
func maxCleanupGs() uint32 {
	// N.B. Left as a function to make changing the policy easier.
	return uint32(max(gomaxprocs/4, 1))
}

A quarter of GOMAXPROCS, at least one. That is the direct answer to the biggest complaint about SetFinalizer: cleanups used to run one at a time on the sweeper’s goroutine, so a slow cleanup blocked all the others. Now they run in parallel on a small pool, and the pool scales with the machine.

The sleeping protocol

The dequeue path has to handle the “no work right now” case without spinning:

 go
 
 
// src/runtime/mcleanup.go:490
func (q *cleanupQueue) dequeue() *cleanupBlock {
	for {
		if q.tryTakeWork() {
			// Guaranteed to be non-nil.
			return (*cleanupBlock)(q.full.pop())
		}
		lock(&q.lock)
		// Increment asleep first. We may have to undo this if we abort the sleep.
		// We must update asleep first because the scheduler might not try to wake
		// us up when work comes in between the last check of workUnits and when we
		// go to sleep. (It may see asleep as 0.) By incrementing it here, we guarantee
		// after this point that if new work comes in, someone will try to grab the
		// lock and wake us. However, this also means that if we back out, we may cause
		// someone to spuriously grab the lock and try to wake us up, only to fail.
		// This should be very rare because the window here is incredibly small: the
		// window between now and when we decrement q.asleep below.
		q.asleep.Add(1)
		...
		q.sleeping.push(getg())
		goparkunlock(&q.lock, waitReasonCleanupWait, traceBlockSystemGoroutine, 1)
	}
}

This is the classic lost-wakeup problem, and the comment walks through it step by step: increment asleep before re-checking workUnits, so that a producer that races with the sleep is guaranteed to see asleep > 0 and wake somebody up. The cost of the conservative ordering is a rare spurious wakeup — and the comment says so, and explains why it is acceptable.

The “take work” itself is a CAS on the counter, done before the lock:

 go
 
 
// src/runtime/mcleanup.go:446
func (q *cleanupQueue) tryTakeWork() bool {
	for {
		wu := q.workUnits.Load()
		if wu == 0 {
			return false
		}
		// CAS to prevent us from going negative.
		if q.workUnits.CompareAndSwap(wu, wu-1) {
			return true
		}
	}
}

The CAS loop is there to stop the counter from going negative if two workers race. A plain Add(-1) would allow workUnits to wrap below zero and the wake logic would then never fire again — a permanent hang of the cleanup system. The comment “CAS to prevent us from going negative” is one of those one-line comments that hides a catastrophic bug.

Trade-offs

Finalizer vs cleanup. The finalizer keeps the object alive and scans it; the cleanup does not. That single difference removes the cycle-collection problem, removes the “finalizer delays the object by a GC cycle” problem, and removes the need for the object to be alive when the cleanup runs. In exchange, a cleanup cannot inspect the object it is attached to.

Latency vs throughput. Old finalizers ran on the sweeper goroutine, one at a time. New cleanups run on a pool of dedicated goroutines, in parallel. A single slow cleanup no longer stalls the others.

Cancellation. AddCleanup returns a Cleanup value that can be Stop()ped, and Stop does the real work: it finds the span, ensures it has been swept, removes the special record and frees it. You can also call runtime.SetFinalizer(obj, nil) to clear a finalizer.

One global lock per AddCleanup. addCleanup takes mheap_.speciallock. The TODO in the source says it plainly: “Just locking is a considerable part of the cost of AddCleanup.” If you are registering a cleanup per object in a hot path, this is the bottleneck.

The argument is boxed. For pointer-free arguments smaller than 16 bytes you pay one allocation. That is a deliberate trade of a per-cleanup allocation against a per-cleanup 16-byte tax on every special record.

Cleanups are not guaranteed to run. The documentation is blunt:

The cleanup(arg) call is not always guaranteed to run; in particular it is not guaranteed to run before program exit.

And:

It is not guaranteed that a cleanup will run for objects allocated in initializers for package-level variables. Such objects may be linker-allocated, not heap-allocated.

Do not use cleanups to release OS resources that must be released. Use them to break reference cycles, close loggers, or flush buffers — things where “usually runs” is good enough.

Caveats

The tiny-allocator interaction is subtle. If you pass a small, pointer-free argument, the runtime deliberately avoids the tiny allocator. If you are copying cleanup code from elsewhere, do not “optimise” that allocation.

Zero-sized objects cannot have cleanups. The docs explain why:

Cleanups are not guaranteed to run if the size of T is zero bytes, because it may share same address with other zero-size objects in memory.

arg must not be ptr. AddCleanup panics if the argument is the same pointer as the object, because the cleanup would never run — the argument keeps the object alive forever.

Arena-allocated objects are not eligible. The runtime panics with “runtime.AddCleanup: ptr is arena-allocated”. Arena memory is freed in bulk; per-object cleanup semantics do not make sense there.

The specialCleanup record is not scanned automatically. It lives in non-GC’d memory. If you write code that manipulates these structures (you should not), you must scan them by hand as gcScanCleanup does.

Ordering is not guaranteed. If you register cleanups on several objects that become unreachable together, the order in which they run is unspecified.

Wrapping up

The one thing to remember: runtime.AddCleanup does not resurrect the object. It attaches a special record to the object’s span holding a closure and a separately-boxed argument, and the GC scans only that record — never the object itself. That is why cleanups have no cycle problem and no one-GC-cycle delay.

The part people get wrong: the cleanup system’s parallelism is the whole point of the rewrite, and it comes from a lock-free queue of 512-byte non-GC’d blocks plus a pool of on-demand cleanup goroutines — not from the GC. If your cleanup is slow, it now only delays other cleanups by the pool size, not all of them.

What to go do about it: if you are using runtime.SetFinalizer today, read the AddCleanup documentation and the Cleanup type’s Stop method. The migration is usually mechanical: move the closure’s captured state into the arg parameter, and add a runtime.KeepAlive at the last point where the object must stay reachable.

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's reflect Package Reads Types: The rtype and the Method Table

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

TL;DR: reflect does not have its own type system. It reads the exact abi.Type descriptors the compiler emits into the binary — the same ones the garbage collector and the runtime use. A reflect.Value is a three-word triple: a type pointer, a data pointer, and a flag word where ten bits carry the kind, whether the data is behind a pointer, whether it is addressable, and whether it is read-only.

Reflection in Go has a reputation for being slow and imprecise. Both accusations are half right, and the reasons are worth understanding, because the implementation is not what most people assume.

The usual assumption is that reflect maintains a parallel, richer description of every type — a “runtime type” distinct from the “compile-time type”. It doesn’t. There is exactly one type description in a Go binary: the compiler emits it, it is linked into read-only data, and both the runtime and reflect read it.

This is how it all works, based on reading the Go source tree (Go 1.28 development tree, commit c0be4674).

One type description, two readers

The canonical structure lives in src/internal/abi/type.go, because the runtime and the compiler must agree on its layout byte for byte:

 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

Twenty-odd lines that describe every type in the program: how big it is, how much of it contains pointers (what the GC cares about), a hash for map keys, an equality function, the GC’s pointer bitmask, and two offsets into the module’s name and type tables.

reflect does not have its own copy. It aliases it:

 go
 
 
// src/reflect/type.go:345
// Embed this type to get common/uncommon
type common struct {
	abi.Type
}

// rtype is the common implementation of most values.

So reflect.rtype is a one-field wrapper around abi.Type. The Type interface is implemented by *rtype and its friends (structType, ptrType, sliceType, …), each a larger struct whose first field is the same abi.Type header. That is why the conversion is a single cast:

 go
 
 
// src/reflect/type.go:780
func toRType(t *abi.Type) *rtype {
	return (*rtype)(unsafe.Pointer(t))
}

A slice’s type descriptor is a sliceType whose first bytes happen to be a Type header. Cast to *rtype and you get the header; cast to *sliceType and you get the whole thing. One representation, many views.

The bridge from the runtime’s world to reflect’s world is one linknamed function:

 go
 
 
// src/reflect/type.go:2845
//go:linkname toType
func toType(t *abi.Type) Type {
	if t == nil {
		return nil
	}
	return toRType(t)
}

The runtime version returns a *rtype; the reflect version returns the public Type interface. Same memory, different static type.

The flag bitfield

abi.Type carries a TFlag byte:

 go
 
 
// src/internal/abi/type.go:110
	// TFlagNamed means the type has a name.
	TFlagNamed TFlag = 1 << 2

	// TFlagRegularMemory means that equal and hash functions can treat
	// this type as a single region of t.size bytes.
	TFlagRegularMemory TFlag = 1 << 3

	// TFlagGCMaskOnDemand means that the GC pointer bitmask will be

The design idea here is worth stealing: the common part of a type descriptor is fixed-size and shared by every type of that kind; the variable parts sit immediately after it, with a bit in TFlag telling you whether they are there at all.

TFlagUncommon is the important one: it says “the optional UncommonType struct follows the common header”. TFlagExtraStar is a binary-size optimisation — the name stored for *T may be the name of T with a * glued on, and the flag tells you to strip it. TFlagRegularMemory lets reflect.DeepEqual and the runtime’s map code take a shortcut: a type with no internal structure compares as raw bytes. TFlagDirectIface is the answer to “does this value fit in an interface word?”.

The method table

Where do methods live? Not in the Type header — that is shared by every type of that kind, including ones with no methods at all. Methods live in an optional trailer:

 go
 
 
// src/internal/abi/type.go:230
type UncommonType struct {
	PkgPath NameOff // import path; empty for built-in types like int, string
	Mcount uint16 // number of methods
	Xcount uint16 // number of exported methods
	Moff uint32 // offset from this uncommontype to [mcount]Method
	_ uint32 // unused
}

Moff is an offset, not a pointer, because the method array sits right after the UncommonType struct. Methods() reads it with unchecked arithmetic:

 go
 
 
// src/internal/abi/type.go:238
func (t *UncommonType) Methods() []Method {
	if t.Mcount == 0 {
		return nil
	}
	return (*[1 << 16]Method)(addChecked(unsafe.Pointer(t), uintptr(t.Moff), "t.mcount > 0"))[:t.Mcount:t.Mcount]
}

addChecked looks like a bounds check but isn’t — the string argument is documentation only, and the function exists so the compiler can still inline p+x.

Note the two text offsets. Tfn is the function you would call directly, receiver first. Ifn is the interface version — the wrapper an itab points at.

reflect reads this table to build its Method values:

 go
 
 
// src/reflect/type.go:645
func (t *rtype) Method(i int) (m Method) {
	if t.Kind() == Interface {
		tt := (*interfaceType)(unsafe.Pointer(t))
		return tt.Method(i)
	}
	methods := t.exportedMethods()
	if i < 0 || i >= len(methods) {
		panic("reflect: Method index out of range")
	}
	p := methods[i]
	pname := t.nameOff(p.Name)
	m.Name = pname.Name()

That is a lot of work per call: a new funcType with a receiver prepended, allocated slices, a fresh Value. The “reflection is slow” story in miniature — and it is only slow because it is general.

reflect.Value: a triple with a bitfield

reflect.Value is the most over- and under-appreciated struct in the standard library. Here is the whole thing:

 go
 
 
// src/reflect/value.go:40
type Value struct {
	// typ_ holds the type of the value represented by a Value.
	// Access using the typ method to avoid escape of v.
	typ_ *abi.Type

	// Pointer-valued data or, if flagIndir is set, pointer to data.
	// Valid when either flagIndir is set or typ.pointers() is true.
	ptr unsafe.Pointer

Three words: type, data pointer, flags. The flags word packs everything reflect needs to know about a value without dereferencing the type:

Bit	Meaning
0–4	The `Kind` of the value, cached so `v.Kind()` is a mask, not a load
5	`flagStickyRO` — came from an unexported non-embedded field
6	`flagEmbedRO` — came from an unexported embedded field
7	`flagIndir` — `ptr` points at the data rather than being the data
8	`flagAddr` — the value is addressable (`CanAddr`)
9	`flagMethod` — the value is a bound method value

flagIndir is the subtle one. A reflect.Value holding an int stores the integer in the ptr word, because an int fits in a pointer-sized word. A reflect.Value holding a string — two words — cannot, so it stores a pointer to the string header and sets flagIndir.

The read-only flags prevent a whole class of bugs: unsafe can read unexported fields, but reflect refuses to hand them back through Interface():

 go
 
 
// src/reflect/value.go:1486
func (v Value) Interface() (i any) {
	return valueInterface(v, true)
}

func valueInterface(v Value, safe bool) any {
	if v.flag == 0 {
		panic(&ValueError{"reflect.Value.Interface", Invalid})
	}

CanSet is the same idea in miniature: v.flag&(flagAddr|flagRO) == flagAddr — addressable and not read-only, both conditions in one expression.

packEface: turning a Value back into an `any`

Value.Interface() has to produce an any, which is a two-word structure: a type pointer and a data pointer. packEface constructs the header directly:

 go
 
 
// src/reflect/value.go:118
// packEface converts v to the empty interface.
func packEface(v Value) any {
	return *(*any)(unsafe.Pointer(&abi.EmptyInterface{
		Type: v.typ(),
		Data: packEfaceData(v),
	}))
}

Three cases, and the middle one is the interesting one. If the type is “direct interface” (fits in a word, no pointers — int, bool, a pointer, a chan) but the Value was obtained indirectly, the data has to be loaded out of the pointed-to location. If the type is not direct but the Value is addressable, the data has to be copied into a fresh allocation: the interface owns that word and the original might move.

And going the other way, unpackEface is the whole of ValueOf:

 go
 
 
// src/reflect/value.go:153
// unpackEface converts the empty interface i to a Value.
func unpackEface(i any) Value {
	e := (*abi.EmptyInterface)(unsafe.Pointer(&i))
	t := e.Type
	if t == nil {
		return Value{}
	}
	f := flag(t.Kind())

That is the whole trick: read the type pointer out of the interface header, read the kind out of the type descriptor, set flagIndir if the type does not fit directly, and you are done.

reflect.TypeOf is an interface conversion

Here is the part that surprises people. reflect.TypeOf does no work at runtime beyond what the language already did for you:

 go
 
 
// src/reflect/type.go:1389
// TypeOf returns the reflection [Type] that represents the dynamic type of i.
// If i is a nil interface value, TypeOf returns nil.
func TypeOf(i any) Type {
	return toType(abi.TypeOf(i))
}

and abi.TypeOf is a reinterpretation of the interface header:

 go
 
 
// src/internal/abi/type.go:181
// TypeOf returns the abi.Type of some value.
func TypeOf(a any) *Type {
	eface := *(*EmptyInterface)(unsafe.Pointer(&a))
	// Types are either static (for compiler-created types) or
	// heap-allocated but always reachable (for reflection-created
	// types, held in the central map). So there is no need to
	// escape types. noescape here help avoid unnecessary escape
	// of v.
	return (*Type)(NoEscape(unsafe.Pointer(eface.Type)))
}

Passing a value to reflect.TypeOf(i any) boxes it into an interface, and the interface header already contains a pointer to the type descriptor. TypeOf hands that pointer back. No lookup, no map, no allocation. reflect.ValueOf is slightly more work: it constructs the flag word, which means inspecting IsDirectIface.

And reflect.TypeOf(nil) returns nil, because a nil interface has a nil type pointer. There is no “nil type”.

The itab: interface dispatch, for contrast

The other half of type identity is the itab, the table that makes err.(someInterface) work. It’s defined in src/internal/abi/iface.go:

 go
 
 
// src/internal/abi/iface.go:17
type ITab struct {
	Inter *InterfaceType
	Type *Type
	Hash uint32 // copy of Type.Hash. Used for type switches.
	Fun [1]uintptr // variable sized. fun[0]==0 means Type does not implement Inter.
}

A non-empty interface value is a pair: an *ITab and a data pointer. The ITab says which concrete type is inside, which interface it matched against, and — in the variable-length Fun array — the function pointers for each method.

 go
 
 
// src/runtime/iface.go:44
func getitab(inter *interfacetype, typ *_type, canfail bool) *itab {
	if len(inter.Methods) == 0 {
		throw("internal error - misuse of itab")
	}

	// easy case
	if typ.TFlag&abi.TFlagUncommon == 0 {
		if canfail {
			return nil

Note the first check: if the concrete type has no methods, the TFlagUncommon bit is clear, and the type cannot implement any non-empty interface. The flag doing real work.

Type switches never consult the runtime hash table. The compiler statically generates an itab for every (interface, concrete type) pair in a type switch, so the switch is a hash comparison and a lookup in a compiler-built table — no locks, no allocation, no runtime call.

Reflection versus a type switch

The performance difference is not “reflection is slow and type switches are fast” in the abstract. It’s concrete and measurable:

Operation	What actually happens
`switch v.(type) { case T: }`	Compiler-generated hash comparison, then a table lookup. No allocation, no interface call.
`reflect.TypeOf(v) == reflect.TypeOf(x)`	Read the type pointer out of the interface header, compare two pointers. Essentially free.
`reflect.ValueOf(v).Field(i)`	Build a `Value`, compute offsets, check bounds, construct a new `Value` with new flags.
`reflect.ValueOf(v).Interface()`	`packEface` — possibly a heap allocation and a `typedmemmove`.
`reflect.ValueOf(v).Call(args)`	Allocate an argument frame, translate each argument through the ABI description, call through a function pointer, translate results back.
`reflect.TypeOf(v).Method(i)`	Rebuild a `funcType`, allocate slices, allocate a `Value`.

So the “reflection is slow” complaint is really two complaints: reflection forces allocation (the boxed any, the reconstructed Method.Type), and reflection loses static knowledge (the compiler knows your struct’s field offsets; reflect has to look them up).

Use reflection at API boundaries, in tests, in serializers, in dependency injection glue — places where the types genuinely aren’t known at compile time.

Trade-offs

What the shared descriptor buys:

One copy of the truth. The runtime and reflect cannot disagree about a type’s size, alignment, or pointer layout, because there is only one description of it.
Small binaries. Every type is one descriptor in read-only data. reflect adds no parallel metadata.
The GC gets what it needs for free. GCData is in the same structure.

What it costs:

The descriptor serves everybody. Equal is a function pointer so == works for non-comparable types; GCData has a mode flag for types whose pointer mask is computed on demand.
Layout access is unsafe. Everything past the simple accessors is unsafe.Pointer casts and offsets.
The flag word is a compromise. Caching the Kind makes v.Kind() a single instruction, but a Value can be constructed wrong. reflect guards with mustBe, mustBeExported, and a pile of panics.
Method lookup rebuilds signatures. There is no pre-built signature to point at.

Caveats

The Type interface is not the runtime’s Type. reflect.Type is an interface with about forty methods; abi.Type is a struct. They are related by an unsafe.Pointer cast, not by Go’s type system.

reflect.TypeOf and reflect.ValueOf are not symmetric. TypeOf returns nil for a nil interface; ValueOf returns the zero Value, which panics if you call most methods on it.

The Kind cache in the flag word can go stale in principle. It can’t in practice, because a Value’s type never changes — but a hand-constructed Value with a wrong flag word misbehaves in confusing ways.

Unexported fields behave oddly. v.Field(i) on an unexported field returns a Value with flagStickyRO set: readable with Int(), String() and friends, but Interface() and Set() panic.

Method(i) only returns exported methods for non-interface types, and NumMethod reports the exported count.

reflect.Type values are comparable but reflect.Value values are not. == on two Values compares the struct fields, not the values they represent.

Wrapping up

The one thing to remember: reflect is not a parallel type system. It is a set of accessors over the compiler-emitted abi.Type descriptors, and reflect.Value is a (typ, ptr, flag) triple whose flag word carries the kind, the indirection, the addressability and the read-only state in ten bits. Once you see that, “reflection is slow” becomes a specific claim: reflection allocates, and it looks things up at runtime.

The part people get wrong: they assume reflect.TypeOf has to look anything up. It doesn’t. Boxing a value into an any already put a pointer to the type descriptor in the interface header; TypeOf reads it back out. The expensive parts of reflection are the ones that have to build something — a Method’s signature, an argument frame, a boxed result.

What to go do about it: next time you reach for reflect in a hot path, check whether you actually need it. reflect.TypeOf(x) == reflect.TypeOf(y) is a pointer comparison and costs nothing. A type switch is cheaper still. Reserve reflect.Value.Call and reflect.Type.Method for boundaries where the types are dynamic.

How cgo Works in Go: The Two Compilers and a Bit of Magic

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

TL;DR: cgo is two compilers and a translation layer. The cgo tool runs your C compiler over the preamble, parses the DWARF debug info to discover every C type and constant, rewrites C.foo into _Cfunc_foo, and generates a matching C function that packs the arguments into a struct and calls the real C function. Every call then goes through runtime.cgocall, which switches the goroutine onto the system stack before the C code runs.

The import "C" line is the most magical-looking thing in Go. It is not a real import: there is no package called C on disk.

What actually happens is that cgo — a standalone program at src/cmd/cgo — is invoked as a build step. It reads your .go file, finds the import "C" and the comment above it (the preamble), and does something no other part of the Go toolchain does: it runs your C compiler.

This is how it all works, based on reading the Go 1.28 development tree (commit c0be4674).

The preamble is the source of truth

The rule is short: the comment immediately preceding import "C" is the preamble. Anything you declare in it becomes visible to Go as C.name. cgo compiles it and parses the DWARF:

 go
 
 
// src/cmd/cgo/gcc.go:1805
func (p *Package) gccCmd(ofile string) []string {
	c := append(gccBaseCmd,
		"-w", // no warnings
		"-Wno-error", // warnings are not errors
		"-o"+ofile, // write object to tmp
		"-gdwarf-2", // generate DWARF v2 debugging symbols
		"-c", // do not link
		"-xc", // input language is C
	)
	if p.GccIsClang {
		c = append(c,

Note -gdwarf-2. cgo is not parsing the C source; it is asking the compiler for the meaning of every identifier, machine-readably.

Constants are handled separately: cgo compiles them into the object file and reads their values back out of the data segment. So C.O_RDONLY is not a magic number baked into Go: it is the value the C compiler put in the object file.

The file pipeline

Once cgo knows what C.foo means, it generates a family of files:

 go
 
 
// src/cmd/cgo/doc.go:723

Given the input Go files x.go and y.go, cgo generates these source
files:

	x.cgo1.go # for gc (cmd/compile)
	y.cgo1.go # for gc
	_cgo_gotypes.go # for gc
	_cgo_import.go # for gc (if -dynout _cgo_import.go)
	x.cgo2.c # for gcc
	y.cgo2.c # for gcc
	_cgo_defun.c # for gcc (if -gccgo)

Two compilers, two sets of outputs:

File	Compiled by	What it holds
`.cgo1.go`	`cmd/compile`	Your file with `import "C"` removed and every `C.xxx` rewritten to `_Cfunc_xxx` or `_Ctype_xxx`
`_cgo_gotypes.go`	`cmd/compile`	Go definitions of every C type, plus the Go wrapper functions
`.cgo2.c`	`gcc`/`clang`	The C-side glue that unpacks the frame
`_cgo_export.c` / `_cgo_export.h`	`gcc`/`clang`	C-callable wrappers for Go functions marked `//export`

The Go compiler never sees the C source; the C compiler never sees your Go code. They meet at the boundary of a struct.

The symbol rewriting

The name mangling has two halves. In your source C.puts becomes _Cfunc_puts:

 go
 
 
// src/cmd/cgo/gcc.go:806
func (p *Package) mangleName(n *Name) {
	// When using gccgo variables have to be
	// exported so that they become global symbols
	// that the C code can refer to.
	prefix := "_C"
	if *gccgo && n.IsVar() {
		prefix = "C"
	}
	n.Mangle = prefix + n.Kind + "_" + n.Go
}

In the C world the wrapper needs a symbol name that cannot collide with anything else, so cgo prefixes it with a hash of the package:

 go
 
 
// src/cmd/cgo/main.go:395
	// We already put _cgo_ at the beginning, so the main
	// concern is other cgo wrappers for the same functions.
	// Use the beginning of the 16 bytes hash of the input to disambiguate.
	h := hash.New32()

and

 go
 
 
// src/cmd/cgo/out.go:563
	cname := fmt.Sprintf("_cgo%s%s", cPrefix, n.Mangle)

The cPrefix is the first six bytes of that hash, formatted as hex:

 go
 
 
// src/cmd/cgo/main.go:451
	cPrefix = fmt.Sprintf("_%x", h.Sum(nil)[0:6])

So the C symbol for C.puts ends up as _cgo_be59f0f25121_Cfunc_puts — deterministic across builds but unique per package.

The Go side declares that symbol with a //go:cgo_import_static directive, telling the linker “this is a C symbol that lives in the gcc-compiled object file”:

 go
 
 
// src/cmd/cgo/out.go:632
	// Wrapper calls into gcc, passing a pointer to the argument frame.
	fmt.Fprintf(fgo2, "//go:cgo_import_static %s\n", cname)
	fmt.Fprintf(fgo2, "//go:linkname __cgofn_%s %s\n", cname, cname)
	fmt.Fprintf(fgo2, "var __cgofn_%s byte\n", cname)
	fmt.Fprintf(fgo2, "var %s = unsafe.Pointer(&__cgofn_%s)\n", cname, cname)

The Go side of a call

The generated Go wrapper does one thing: build a frame and hand it to runtime.cgocall.

 go
 
 
// src/cmd/cgo/out.go:647
	fmt.Fprint(fgo2, "\n")
	fmt.Fprint(fgo2, "//go:cgo_unsafe_args\n")
	conf.Fprint(fgo2, fset, d)
	fmt.Fprint(fgo2, " {\n")

	// NOTE: Using uintptr to hide from escape analysis.
	arg := "0"
	if len(paramnames) > 0 {
		arg = "uintptr(unsafe.Pointer(&p0))"
	} else if !void {
		arg = "uintptr(unsafe.Pointer(&r1))"
	}

Three things to notice:

The uintptr trick. The frame address is converted to uintptr so escape analysis and the GC don’t think the frame escapes to the heap — a lie told to the compiler for the sake of the GC’s stack scanning.
//go:cgo_unsafe_args. This pragma tells the compiler that a pointer to one argument is a pointer to all of them, so it must disable the write barrier’s per-argument checks. The lexer turns it into a flag:

 go
 
 
// src/cmd/compile/internal/noder/lex.go:67
	case "go:cgo_unsafe_args":
		return ir.CgoUnsafeArgs | ir.NoCheckPtr // implies NoCheckPtr (see #34968)

and the inliner refuses to inline such functions:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:374
	// If marked "go:cgo_unsafe_args", don't inline, since the function
	// makes assumptions about its argument frame layout.
	if fn.Pragma&ir.CgoUnsafeArgs != 0 {
		reason = "marked go:cgo_unsafe_args"

_Cgo_no_callback. With #cgo nocallback, the wrapper tells the runtime in advance that the C code will not call back into Go.

The C side of a call

The other half is generated C:

 go
 
 
// src/cmd/cgo/doc.go:767
The hexadecimal number is a hash of cgo's input, chosen to be
deterministic yet unlikely to collide with other uses. The actual
function _cgo_be59f0f25121_Cfunc_puts is implemented in a C source
file compiled by gcc, the file x.cgo2.c:

	void
	_cgo_be59f0f25121_Cfunc_puts(void *v)
	{
		struct {
			char* p0;
			int r;
			char __pad12[4];

There it is: the arguments cross the boundary in a struct, by pointer. Not in registers, not on a stack — in a struct both sides agree on the layout of. It is __attribute__((packed)) with explicit padding (char __pad12[4]), because the two compilers must agree on the byte offsets exactly:

 go
 
 
// src/cmd/cgo/out.go:995
		argField := func(typ ast.Expr, namePat string, args ...any) {
			name := fmt.Sprintf(namePat, args...)
			t := p.cgoType(typ)
			if off%t.Align != 0 {
				pad := t.Align - off%t.Align
				fmt.Fprintf(&ctype, "\t\tchar __pad%d[%d];\n", npad, pad)
				off += pad
				npad++
			}
			fmt.Fprintf(&ctype, "\t\t%s %s;\n", t.C, name)

//export: C calling Go

The other direction works the same way, mirrored. A Go function marked //export gets a C-callable wrapper:

 go
 
 
// src/cmd/cgo/doc.go:311
# C references to Go

Go functions can be exported for use by C code in the following way:

	//export MyFunction
	func MyFunction(arg1, arg2 int, arg3 string) int64 {...}

	//export MyFunction2
	func MyFunction2(arg1, arg2 int, arg3 string) (int64, *C.char) {...}

Note the struct return type for multiple return values. Note also the preamble restriction: because it is copied into two C output files, it must contain only declarations, never definitions, or the link fails on duplicate symbols.

The generated C wrapper for an exported function builds the same kind of frame struct and calls crosscall2:

 go
 
 
// src/cmd/cgo/out.go:1112
		if gccResult != "void" && (len(fntype.Results.List) > 1 || len(fntype.Results.List[0].Names) > 1) {
			fmt.Fprintf(fgcc, "\t%s r;\n", gccResult)
		}
		if fn.Recv != nil {
			fmt.Fprintf(fgcc, "\t_cgo_a.recv = recv;\n")
		}
		forFieldList(fntype.Params,
			func(i int, aname string, atype ast.Expr) {
				fmt.Fprintf(fgcc, "\t_cgo_a.p%d = %s;\n", i, genParamName(aname, i))
			})
		fmt.Fprintf(fgcc, "\t_cgo_tsan_release();\n")
		fmt.Fprintf(fgcc, "\tcrosscall2(_cgoexp%s_%s, &_cgo_a, %d, _cgo_ctxt);\n", cPrefix, exp.ExpName, off)

crosscall2 is the adapter from the C calling convention to the Go one — hand-written assembly on amd64, saving the registers the two conventions disagree about.

The cost of a call

Now the part that matters for performance. The runtime’s own header comment describes the dance:

 go
 
 
// src/runtime/cgocall.go:5
// Cgo call and callback support.
//
// To call into the C function f from Go, the cgo-generated code calls
// runtime.cgocall(_cgo_Cfunc_f, frame), where _cgo_Cfunc_f is a
// gcc-compiled function written by cgo.
//
// runtime.cgocall (below) calls entersyscall so as not to block
// other goroutines or the garbage collector, and then calls
// runtime.asmcgocall(_cgo_Cfunc_f, frame).
//
// runtime.asmcgocall (in asm_$GOARCH.s) switches to the m->g0 stack

So a cgo call is not a function call. It is:

entersyscall() — tell the scheduler this thread is in foreign code and may block. The P is released so other goroutines run.
asmcgocall — switch from the goroutine’s stack to the system stack (m->g0), because Go’s goroutine stacks are small and movable when they grow, and C code holds pointers to its own stack frames. The system stack never moves.
Call the C wrapper, which calls the actual C function.
Switch back, exitsyscall() — possibly blocking until the runtime can give this goroutine a P again.

The shape of one call, end to end:

 text
 
 
 Go goroutine (stack S) Go runtime C world
 ------------------------ ----------- --------
 _Cfunc_puts(p0)
 -> runtime.cgocall(fn, &frame)
 entersyscall() -------> release the P, other
 goroutines run
 asmcgocall() -------> switch to m->g0
 (system stack)
 call fn(frame)
 -> _cgo_..._Cfunc_puts
 a->r = puts(a->p0)
 asmcgocall() <------- switch back to stack S
 exitsyscall() <------- wait for a P again
 <- returns

The Go half:

 go
 
 
// src/runtime/cgocall.go:132
//go:linkname cgocall
//go:nosplit
func cgocall(fn, arg unsafe.Pointer) int32 {
	if !iscgo && GOOS != "solaris" && GOOS != "illumos" && GOOS != "windows" {
		throw("cgocall unavailable")
	}

	if fn == nil {
		throw("cgocall nil")
	}

And the assembly that does the stack switch, on amd64:

 asm
 
 
// src/runtime/asm_amd64.s:904
// func asmcgocall(fn, arg unsafe.Pointer) int32
// Call fn(arg) on the scheduler stack,
// aligned appropriately for the gcc ABI.
// See cgocall.go for more details.
TEXT ·asmcgocall(SB),NOSPLIT,$0-20
	// Figure out if we need to switch to m->g0 stack.
	// We get called to create new OS threads too, and those
	// come in on the m->g0 stack already. Or we might already
	// be on the m->gsignal stack.
	get_tls(CX)
	MOVQ	g(CX), DI
	CMPQ	DI, $0
	JEQ	nosave
	MOVQ	g_m(DI), R8
	MOVQ	m_gsignal(R8), SI
	CMPQ	DI, SI
	JEQ	nosave

So the cost of a cgo call is a scheduler hand-off, a stack switch, and a scheduler hand-back — a few hundred nanoseconds, versus a couple of nanoseconds for a direct Go call.

The reverse direction is more involved: the runtime switches back onto the goroutine stack, runs Go code that may grow and move the stack, then switches back again — runtime.cgocallbackg is where that starts.

The pointer rules, and how they’re enforced

The rules themselves are short and absolute:

 go
 
 
// src/cmd/cgo/doc.go:383
Go code may pass a Go pointer to C provided the memory to which it
points does not contain any Go pointers to memory that is unpinned. When
passing a pointer to a field in a struct, the Go memory in question is
the memory occupied by the field, not the entire struct. When passing a
pointer to an element in an array or slice, the Go memory in question is
the entire array or the entire backing array of the slice.

C code may keep a copy of a Go pointer only as long as the memory it
points to is pinned.

C code may not keep a copy of a Go pointer after the call returns,
unless the memory it points to is pinned with [runtime.Pinner] and the
Pinner is not unpinned while the Go pointer is stored in C memory.
This implies that C code may not keep a copy of a string, slice,
channel, and so forth, because they cannot be pinned with
[runtime.Pinner].

You cannot store a Go pointer in C memory. The reason is the garbage collector: it moves objects and frees them, and if C memory holds a pointer to Go memory the GC does not know about, it will eventually free memory C is still using. Unless the memory is pinned.

The rules are enforced at runtime. The default is GODEBUG=cgocheck=1, a cheap check; the thorough one is a build-time experiment:

 go
 
 
// src/internal/goexperiment/flags.go:90
	// CgoCheck2 enables an expensive cgo rule checker.
	// When this experiment is enabled, cgo rule checks occur regardless
	// of the GODEBUG=cgocheck setting provided at runtime.
	CgoCheck2 bool

The cgocheck2 implementation is in src/runtime/cgocheck.go, and hooks every pointer write:

 go
 
 
// src/runtime/cgocheck.go:17
// cgoCheckPtrWrite is called whenever a pointer is stored into memory.
// It throws if the program is storing an unpinned Go pointer into non-Go
// memory.
//
// This is called from generated code when GOEXPERIMENT=cgocheck2 is enabled.
//
//go:nosplit
//go:nowritebarrier

The rule encoded there is the rule in the docs: a Go pointer may be written to C memory only if it is pinned.

Trade-offs

What cgo buys you:

Access to everything. Any C library, any version, any ABI — the wrapper comes from the DWARF.
Zero-copy interop. A *C.struct in C memory can be read from Go without copying, if it holds no Go pointers.
Incremental adoption. Call an existing C codebase as-is.

What it costs:

Two compilers, two ABIs, two linkers. The build is slower, the binary is bigger, and you need a C toolchain installed.
Crossing the boundary is expensive. A cgo call is two orders of magnitude more expensive than a direct Go call. Batch your calls.
The pointer rules are a real constraint. You cannot hand C a GoString and keep it, or let C hold a []byte. You must copy.
Static analysis stops at the boundary. go vet and escape analysis give up at a C call.

Caveats

A cgo call is not cheap. If the C function is trivial — say, strlen on a short string — the cgo overhead can dominate by two orders of magnitude. Batch the calls.

//exported functions must be in a file that imports “C”, and the exported name must match the function name exactly: //export Foo on a function called foo is an error.

C code cannot keep a Go pointer. Use runtime/cgo.Handle or copy.

cgocheck=0 turns the checks off, and the runtime will not save you: you get a crash that looks like random memory corruption in native code.

GOEXPERIMENT=cgocheck2 is a build-time experiment, not a GODEBUG. It instruments every pointer write, so it costs real time. Worth one build in CI.

Callbacks from C into Go are the most fragile part. A C library that calls back on a thread the runtime did not create needs runtime/cgo.Handle or an //exported function that makes its own goroutine.

C.malloc returns memory the GC does not scan. Use C.CBytes.

Wrapping up

The one thing to remember: cgo is a source-to-source translator, not an FFI layer. cmd/cgo uses gcc to discover the C types, then writes a Go wrapper (which marshals into a frame and calls runtime.cgocall) and a C wrapper (which unpacks the frame and calls your function).

The part people get wrong: they think the expensive part is the C call. It is the goroutine leaving its stack.

What to go do about it: count the crossings. Calling C once per network packet is fine; calling C once per struct field is a design problem, and the fix isn’t unsafe, it’s runtime.Pinner.

GODEBUG: The Knobs Go Gives You to Turn Up the Volume

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

TL;DR: GODEBUG is two mechanisms wearing one name: a table of compatibility settings (panicnil, httplaxcontentlength) whose defaults change every release, and the runtime’s own debug knobs (efence, gccheckmark). Both read the same environment variable, mid-run.

Go has a reputation for never breaking your code. That reputation is mostly true, and the mechanism behind it is not subtle: when a change would break existing programs, Go ships a switch that turns the new behaviour off, flips the default in a later release, and eventually deletes the switch. That switch is a GODEBUG setting.

The other thing GODEBUG does is give you debug knobs for the runtime and the standard library — GODEBUG=efence=1 to find memory corruption, GODEBUG=gctrace=1 to watch the garbage collector, GODEBUG=asyncpreemptoff=1 to make the scheduler behave.

This is a walk through how that actually works in the Go 1.28 tree.

Two mechanisms, one variable

The runtime’s own documentation starts with the debug-knob flavour:

 go
 
 
// src/runtime/extern.go:35
The GODEBUG variable controls debugging variables within the runtime.
It is a comma-separated list of name=val pairs setting these named variables:

	clobberfree: setting clobberfree=1 causes the garbage collector to
	clobber the memory content of an object with bad content when it frees
	the object.

and the knobs are documented inline, right next to the code that reads them:

 go
 
 
// src/runtime/extern.go:94
	efence: setting efence=1 causes the allocator to run in a mode
	where each object is allocated on a unique page and addresses are
	never recycled.

	gccheckmark: setting gccheckmark=1 enables verification of the
	garbage collector's concurrent mark phase by performing a
	second mark pass while the world is stopped. If the second
	pass finds a reachable object that was not found by concurrent
	mark, the garbage collector will panic.

	gcpacertrace: setting gcpacertrace=1 causes the garbage collector to
	print information about the internal state of the concurrent pacer.

These are internal to the runtime. They are parsed into a table of plain int32 fields:

 go
 
 
// src/runtime/runtime1.go:358
var dbgvars = []*dbgVar{
	{name: "adaptivestackstart", value: &debug.adaptivestackstart},
	{name: "asyncpreemptoff", value: &debug.asyncpreemptoff},
	{name: "cgocheck", value: &debug.cgocheck},
	{name: "clobberfree", value: &debug.clobberfree},
	{name: "containermaxprocs", value: &debug.containermaxprocs, def: 1},
	{name: "dataindependenttiming", value: &debug.dataindependenttiming},
	{name: "decoratemappings", value: &debug.decoratemappings, def: 1},
	{name: "disablethp", value: &debug.disablethp},
	{name: "dontfreezetheworld", value: &debug.dontfreezetheworld},
	{name: "checkfinalizers", value: &debug.checkfinalizers},
	{name: "efence", value: &debug.efence},
	{name: "gccheckmark", value: &debug.gccheckmark},
	{name: "gcpacertrace", value: &debug.gcpacertrace},
	{name: "gcshrinkstackoff", value: &debug.gcshrinkstackoff},
	{name: "gcstoptheworld", value: &debug.gcstoptheworld},
	{name: "gctrace", value: &debug.gctrace},
	{name: "harddecommit", value: &debug.harddecommit},
	{name: "inittrace", value: &debug.inittrace},
	{name: "invalidptr", value: &debug.invalidptr},
	{name: "madvdontneed", value: &debug.madvdontneed},
	{name: "panicnil", atomic: &debug.panicnil},
	{name: "profstackdepth", value: &debug.profstackdepth, def: 128},
	{name: "sbrk", value: &debug.sbrk},
	{name: "scavtrace", value: &debug.scavtrace},
	{name: "scheddetail", value: &debug.scheddetail},
	{name: "schedtrace", value: &debug.schedtrace},
	{name: "traceadvanceperiod", value: &debug.traceadvanceperiod},
	{name: "traceallocfree", atomic: &debug.traceallocfree},
	{name: "tracecheckstackownership", value: &debug.traceCheckStackOwnership},
	{name: "tracebackancestors", value: &debug.tracebackancestors},
	{name: "tracebackcrash", value: &debug.tracebackcrash},
	{name: "tracebacklabels", atomic: &debug.tracebacklabels, def: 1},
	{name: "tracefpunwindoff", value: &debug.tracefpunwindoff},
	{name: "updatemaxprocs", value: &debug.updatemaxprocs, def: 1},
}

Notice the def: field on a few of them. Those are the settings whose default is not zero, and the default is applied before the environment is parsed:

 go
 
 
// src/runtime/runtime1.go:395
func parseRuntimeDebugVars(godebug string) {
	// defaults
	debug.cgocheck = 1
	debug.invalidptr = 1
	debug.adaptivestackstart = 1 // set this to 0 to turn larger initial goroutine stacks off
	if GOOS == "linux" {
		// On Linux, MADV_FREE is faster than MADV_DONTNEED,
		// but doesn't affect many of the statistics that
		// MADV_DONTNEED does until the memory is actually
		// reclaimed. This generally leads to poor user
		// experience, like confusing stats in top and other
		// monitoring tools; and bad integration with
		// management systems that respond to memory usage.
		// Hence, default to MADV_DONTNEED.
		debug.madvdontneed = 1
	}

The madvdontneed story is a nice illustration of a knob that is genuinely two-sided: on Linux the default is MADV_DONTNEED (memory is returned to the OS immediately, RSS drops, but it costs more); setting madvdontneed=0 uses MADV_FREE, which is cheaper but means RSS numbers stay high until the kernel is under pressure. On the BSDs the default is the other way round. The setting exists so the same binary can be tuned per platform.

Then the environment is parsed on top:

 go
 
 
// src/runtime/runtime1.go:413
	// apply runtime defaults, if any
	for _, v := range dbgvars {
		if v.def != 0 {
			// Every var should have either v.value or v.atomic set.
			if v.value != nil {
				*v.value = v.def
			} else if v.atomic != nil {
				v.atomic.Store(v.def)
			}
		}
	}
	// apply compile-time GODEBUG settings
	parsegodebug(godebugDefault, nil)

	// apply environment settings
	parsegodebug(godebug, nil)

The compatibility table

The other half of GODEBUG is the compatibility mechanism, and it has its own package: internal/godebugs. The whole thing is one slice of structs.

 go
 
 
// src/internal/godebugs/table.go:10
// An Info describes a single known GODEBUG setting.
type Info struct {
	Name string // name of the setting ("panicnil")
	Package string // package that uses the setting ("runtime")
	Changed int // minor version when default changed, if any; 21 means Go 1.21
	Old string // value that restores behavior prior to Changed
	Opaque bool // setting does not export information to runtime/metrics using [internal/godebug.Setting.IncNonDefault]
	Immutable bool // setting cannot be changed after program start
}

Six fields, and they are the whole story of Go’s compatibility policy.

Name is the key in the environment variable. Package says who owns it. Changed is the Go minor version in which the default flipped — 21 means Go 1.21. Old is the value that restores the old behaviour. Opaque means the setting cannot report itself to runtime/metrics. Immutable means it cannot be changed after the program starts.

Here is the actual table:

 go
 
 
// src/internal/godebugs/table.go:43
	{Name: "http2client", Package: "net/http"},
	{Name: "http2debug", Package: "net/http", Opaque: true},
	{Name: "http2server", Package: "net/http"},
	{Name: "httpcookiemaxnum", Package: "net/http", Changed: 24, Old: "0"},
	{Name: "httplaxcontentlength", Package: "net/http", Changed: 22, Old: "1"},
	{Name: "httpmuxgo121", Package: "net/http", Changed: 22, Old: "1"},
	{Name: "httpservecontentkeepheaders", Package: "net/http", Changed: 23, Old: "1"},
	{Name: "httpservecontentmaxranges", Package: "net/http", Changed: 26, Old: "1"},
	{Name: "installgoroot", Package: "go/build"},
	{Name: "jstmpllitinterp", Package: "html/template", Opaque: true}, // bug #66217: remove Opaque
	//{Name: "multipartfiles", Package: "mime/multipart"},
	{Name: "multipartmaxheaders", Package: "mime/multipart"},
	{Name: "multipartmaxparts", Package: "mime/multipart"},
	{Name: "multipathtcp", Package: "net", Changed: 24, Old: "0"},
	{Name: "netdns", Package: "net", Opaque: true},
	{Name: "netedns0", Package: "net", Changed: 19, Old: "0"},
	{Name: "netmarshal", Package: "net", Changed: 30, Old: "0"},
	{Name: "panicnil", Package: "runtime", Changed: 21, Old: "1"},
	{Name: "randautoseed", Package: "math/rand"},
	{Name: "randseednop", Package: "math/rand", Changed: 24, Old: "0"},
	{Name: "rsa1024min", Package: "crypto/rsa", Changed: 24, Old: "0"},
	{Name: "tarinsecurepath", Package: "archive/tar"},
	{Name: "tlsmaxrsasize", Package: "crypto/tls"},
	{Name: "tlsmlkem", Package: "crypto/tls", Changed: 24, Old: "0", Opaque: true},

httplaxcontentlength is a good one to understand. Go 1.22 changed how net/http handles a Content-Length on a request whose body is empty or whose length disagrees with the body. If your program depended on the old lenient behaviour, you set httplaxcontentlength=1 and nothing changes. When you are ready, you delete it. The Changed: 22, Old: "1" fields say exactly that: the default changed in Go 1.22, and "1" is the value that gets you back to Go 1.21 behaviour.

netmarshal is the interesting one because it points the other way. Changed: 30 means the default does not change until Go 1.30 — Go 1.28 and 1.29 both ship netmarshal=0, and only in 1.30 does it flip to 1. The documentation in doc/godebug.md explains why: Go 1.28 and 1.29 want their JSON output to remain readable by older versions of Go.

Registering a setting

Any package can add a setting, but it has to do it by the book. The rule is that you declare a global and call godebug.New:

 go
 
 
// src/internal/godebug/godebug.go:79
// New returns a new Setting for the $GODEBUG setting with the given name.
//
// GODEBUGs meant for use by end users must be listed in ../godebugs/table.go,
// which is used for generating and checking various documentation.
// If the name is not listed in that table, New will succeed but calling Value
// on the returned Setting will panic.
// To disable that panic for access to an undocumented setting,
// prefix the name with a #, as in godebug.New("#gofsystrace").
// The # is a signal to New but not part of the key used in $GODEBUG.
//
// Note that almost all settings should arrange to call [IncNonDefault] precisely
// when program behavior is changing from the default due to the setting
// (not just when the setting is different, but when program behavior changes).
// See the [internal/godebug] package comment for more.
func New(name string) *Setting {
	return &Setting{name: name}
}

The panic on an unknown name is deliberate and is what keeps the table honest:

 go
 
 
// src/internal/godebug/godebug.go:157
func (s *Setting) Value() string {
	s.once.Do(func() {
		s.setting = lookup(s.Name())
		if s.info == nil && !s.Undocumented() {
			panic("godebug: Value of name not listed in godebugs.All: " + s.name)
		}
	})
	v := *s.value.Load()
	if v.bisect != nil && !v.bisect.Stack(&stderr) {
		return ""
	}
	return v.text
}

If you add a setting and forget to add it to internal/godebugs/table.go, the program panics the first time anybody reads the setting. There is a test in internal/godebugs that enforces the convention that the global variable is named after the setting.

The Value method is designed to be called on a hot path. The cache is a sync.Map of *atomic.Pointer[value], so all settings with the same name share one atomic pointer, and updating GODEBUG at runtime is a single atomic store per changed setting.

Parsing, and re-parsing

The parser is small and a little clever. It scans the string backwards, so later settings win and earlier ones are ignored without ever briefly taking effect:

 go
 
 
// src/internal/godebug/godebug.go:260
// parse parses the GODEBUG setting string s,
// which has the form k=v,k2=v2,k3=v3.
// Later settings override earlier ones.
// Parse only updates settings k=v for which did[k] = false.
// It also sets did[k] = true for settings that it updates.
// Each value v can also have the form v#pattern,
// in which case the GODEBUG is only enabled for call stacks
// matching pattern, for use with golang.org/x/tools/cmd/bisect.
func parse(did map[string]bool, s string) {
	// Scan the string backward so that later settings are used
	// and earlier settings are ignored.
	// Note that a forward scan would cause cached values
	// to temporarily use the ignored value before being
	// updated to the "correct" one.
	end := len(s)
	eq := -1
	for i := end - 1; i >= -1; i-- {

That #pattern suffix is a nice touch: it lets a setting apply only on certain call stacks, which is what golang.org/x/tools/cmd/bisect uses to narrow down which of your dependencies is responsible for a behaviour change.

The update function decides which of the two sources wins:

 go
 
 
// src/internal/godebug/godebug.go:230
// update records an updated GODEBUG setting.
// def is the default GODEBUG setting for the running binary,
// and env is the current value of the $GODEBUG environment variable.
func update(def, env string) {
	updateMu.Lock()
	defer updateMu.Unlock()

	// Update all the cached values, creating new ones as needed.
	// We parse the environment variable first, so that any settings it has
	// are already locked in place (did[name] = true) before we consider
	// the defaults. Existing immutable settings are always locked.
	did := make(map[string]bool)
	cache.Range(func(name, s any) bool {
		if info := s.(*setting).info; info != nil && info.Immutable {
			did[name.(string)] = true
		}
		return true
	})
	parse(did, env)
	parse(did, def)

The environment wins over the compiled-in defaults, always. And because the runtime keeps a pointer to the environment string, os.Setenv("GODEBUG", ...) at runtime works:

 go
 
 
// src/runtime/runtime.go:199
//go:linkname syscall_runtimeSetenv syscall.runtimeSetenv
func syscall_runtimeSetenv(key, value string) {
	setenv_c(key, value)
	if key == "GODEBUG" {
		p := new(string)
		*p = value
		godebugEnv.Store(p)
		godebugNotify(true)
	}
}

That is a genuinely unusual capability: you can flip a compatibility setting in a running process. It is why the godebug package has to be careful about re-entrancy, and why IncNonDefault uses a sync.Once to register its metric exactly once.

`//go:debug` and the `go.mod` block

Environment variables are awkward for deployed software. Go 1.21 gave main packages a source-level directive:

 go
 
 
//go:debug default=go1.21
//go:debug panicnil=1
//go:debug asynctimerchan=0

The toolchain parses these out of the source and bakes them into the binary as the default GODEBUG string, which is what godebugDefault is in the runtime. The parsing lives in cmd/go:

 go
 
 
// src/cmd/go/internal/load/godebug.go:24
func ParseGoDebug(text string) (key, value string, err error) {
	if !strings.HasPrefix(text, "//go:debug") {
		return "", "", ErrNotGoDebug
	}
	i := strings.IndexAny(text, " \t")
	if i < 0 {
		if strings.TrimSpace(text) == "//go:debug" {
			return "", "", fmt.Errorf("missing key=value")
		}
		return "", "", ErrNotGoDebug
	}
	k, v, ok := strings.Cut(strings.TrimSpace(text[i:]), "=")
	if !ok {
		return "", "", fmt.Errorf("missing key=value")
	}
	if err := modload.CheckGodebug("//go:debug setting", k, v); err != nil {
		return "", "", err
	}
	return k, v, nil
}

and the assembled default is computed from the module’s Go version:

 go
 
 
// src/cmd/go/internal/load/godebug.go:134
func godebugForGoVersion(v string) map[string]string {
	if strings.Count(v, ".") >= 2 {
		i := strings.Index(v, ".")
		j := i + 1 + strings.Index(v[i+1:], ".")
		v = v[:j]
	}

	if !strings.HasPrefix(v, "1.") {
		return nil
	}
	n, err := strconv.Atoi(v[len("1."):])
	if err != nil {
		return nil
	}

	def := make(map[string]string)
	for _, info := range godebugs.All {
		if n < info.Changed {
			def[info.Name] = info.Old
		}
	}
	return def
}

This is the whole backwards-compatibility story in one function. If your go.mod says go 1.21, every setting whose default changed in Go 1.22 or later is set to its Old value. Your 2021 code keeps getting 2021 behaviour even when you build it with a Go 1.28 toolchain.

Since Go 1.23 you can also do it from go.mod directly:

 go
 
 
// src/cmd/go/internal/load/godebug.go:81
	// Add directives from main module go.mod.
	for _, g := range ld.MainModules.Godebugs(ld) {
		if m == nil {
			m = make(map[string]string)
		}
		m[g.Key] = g.Value
	}

and the default=go1.21 key lets you decouple “which Go version’s defaults do I want” from “which Go language version am I using”.

The toolchain also enforces that you do not contradict yourself:

 go
 
 
// src/cmd/go/internal/work/exec.go:1078
func (b *Builder) checkDirectives(a *Action) error {
	var msg []byte
	p := a.Package
	var seen map[string]token.Position
	for _, d := range p.Internal.Build.Directives {
		if strings.HasPrefix(d.Text, "//go:debug") {
			key, _, err := load.ParseGoDebug(d.Text)
			if err != nil && err != load.ErrNotGoDebug {
				msg = fmt.Appendf(msg, "%s: invalid //go:debug: %v\n", d.Pos, err)
				continue
			}
			if pos, ok := seen[key]; ok {
				msg = fmt.Appendf(msg, "%s: repeated //go:debug for %v\n\t%s: previous //go:debug\n", d.Pos, key, pos)
				continue
			}

Two //go:debug panicnil=1 lines in the same package is a build error.

Counting non-default behaviour

The final piece is observability. If you set a GODEBUG in production, how do you know it is actually changing behaviour? The answer is a metric per setting.

Every setting gets a /godebug/non-default-behavior/<name>:events metric, generated from the same table:

 go
 
 
// src/runtime/metrics/description.go:514
func init() {
	// Insert all the non-default-reporting GODEBUGs into the table,
	// preserving the overall sort order.
	i := 0
	for i < len(allDesc) && allDesc[i].Name < "/godebug/" {
		i++
	}
	more := make([]Description, i, len(allDesc)+len(godebugs.All))
	copy(more, allDesc)
	for _, info := range godebugs.All {
		if !info.Opaque {
			more = append(more, Description{
				Name: "/godebug/non-default-behavior/" + info.Name + ":events",
				Description: "The number of non-default behaviors executed by the " +
					info.Package + " package " + "due to a non-default " +
					"GODEBUG=" + info.Name + "=... setting.",
				Kind: KindUint64,
				Cumulative: true,
			})
		}
	}
	allDesc = append(more, allDesc[i:]...)
}

The counter is only incremented when the behaviour actually changes, not merely when the setting is set — that is why the godebug package’s documentation is so insistent about it:

 go
 
 
// src/internal/godebug/godebug.go:115
// IncNonDefault increments the non-default behavior counter
// associated with the given setting.
// This counter is exposed in the runtime/metrics value
// /godebug/non-default-behavior/<name>:events.
//
// Note that Value must be called at least once before IncNonDefault.
func (s *Setting) IncNonDefault() {
	s.nonDefaultOnce.Do(s.register)
	s.nonDefault.Add(1)
}

The runtime cannot import internal/godebug (circular dependency), so it shims it:

 go
 
 
// src/runtime/runtime.go:155
// A godebugInc provides access to internal/godebug's IncNonDefault function
// for a given GODEBUG setting.
// Calls before internal/godebug registers itself are dropped on the floor.
type godebugInc struct {
	name string
	inc atomic.Pointer[func()]
}

and the metric registration is a go:linkname hop into the runtime:

 go
 
 
// src/runtime/metrics.go:571
//go:linkname godebug_registerMetric internal/godebug.registerMetric
func godebug_registerMetric(name string, read func() uint64) {
	metricsLock()
	initMetrics()
	d, ok := metrics[name]
	if !ok {
		throw("runtime: unexpected metric registration for " + name)
	}
	d.compute = metricReader(read).compute
	metrics[name] = d
	metricsUnlock()
}

Removing a setting

Eventually a setting is no longer needed. The table has a second list for that:

 go
 
 
// src/internal/godebugs/table.go:87
// A RemovedInfo describes a GODEBUG setting that has been removed.
//
// Per the policy for removing GODEBUG settings (go.dev/issue/76163), using any non-"old"
// value for the removed setting is permissible. Using an old value, indicating a non-final
// default value for that setting, leads to a build or vet error.
// To support multiple "old" values (see asynctimerchan), the Old field is a predicate.
type RemovedInfo struct {
	Name string // name of the removed GODEBUG setting.
	Removed int // minor version of Go, when the removal happened
	Old func(string) bool // reports whether the GODEBUG value (argument) is an old (invalid) value
}

// Removed contains all GODEBUGs that we have removed.
//
// Every removed GODEBUG must have a corresponding section in doc/godebug.md,
// since cmd/go links to that document when a removed GODEBUG is used.
var Removed = []RemovedInfo{
	{Name: "x509sha1", Removed: 24, Old: one}, // Old: "1"
	{Name: "tlskyber", Removed: 24, Old: zero}, // Old: "0"
	{Name: "gotypesalias", Removed: 27, Old: zero}, // Old: "0"
	{Name: "tlsunsafeekm", Removed: 27, Old: one}, // Old: "1"
	{Name: "tlsrsakex", Removed: 27, Old: one}, // Old: "1"
	{Name: "tls3des", Removed: 27, Old: one}, // Old: "1"
	{Name: "tls10server", Removed: 27, Old: one}, // Old: "1"
	{Name: "x509keypairleaf", Removed: 27, Old: zero}, // Old: "0"
	{Name: "asynctimerchan", Removed: 27, Old: func(s string) bool { return s == "1" || s == "2" }}, // Old: "1" or "2"
}

This is the endgame of the compatibility cycle. tls10server was the switch that let you re-enable TLS 1.0 on the server; it was removed in Go 1.27 because TLS 1.0 is dead. asynctimerchan was the switch that kept the old unbuffered time.Timer channel behaviour; it was removed in Go 1.27, and it needed a predicate rather than a single value because it had two old values (“1” and “2”).

Crucially, setting a removed GODEBUG to a non-old value is fine — only asking for the behaviour that no longer exists is an error. And that error is raised at startup:

 go
 
 
// src/runtime/proc.go:219
	// If we encountered a removed GODEBUG during startup we can panic now.
	if k := invalidGODEBUG.key; k != "" {
		v := invalidGODEBUG.value
		r := strconv.Itoa(invalidGODEBUG.removed)
		fatal(`removed GODEBUG "` + k + `" set to old value "` + v + `" in environment (https://go.dev/doc/godebug#go-1` + r + `)`)
	}

with a link to the history section of doc/godebug.md so you know which version changed it.

Trade-offs

What GODEBUG buys you. A language can change behaviour without breaking anyone, as long as it tells you how to get the old behaviour back. It also gives operators a set of runtime knobs that would otherwise require a rebuild — efence=1 to find a use-after-free, gcpacertrace=1 to understand why the GC is pacing badly, madvdontneed=0 to trade RSS reporting accuracy for scavenger throughput.

What it costs. Every setting is permanent API surface. The table is append-only in practice, the documentation has to track it, the go.mod version logic has to stay consistent with it, and the metrics have to be generated from it. Go has been stuck with http2server and http2client for years precisely because removing a GODEBUG is a breaking change of a different kind.

Why the environment is not the only interface. //go:debug and the go.mod block exist because a deployment often cannot set environment variables, and because a setting that has been vetted in source should not depend on the environment of the machine it happens to run on.

Why the metrics matter. Without /godebug/non-default-behavior/...:events you have no idea whether a setting you set in production is doing anything at all. The counter turns “I set a flag” into “the flag fired 4 million times”, which is the difference between a real hypothesis and a guess.

Caveats

Unrecognised GODEBUGs are silently ignored. GODEBUG=typo=1 does nothing and does not warn you. There is no “unknown GODEBUG” diagnostic.

A setting that is not in the table panics. If you call godebug.New("something") for a name that is not in internal/godebugs.All, New succeeds but Value() panics. That is the mechanism that keeps the table honest, and it also means a package that adds a setting without adding it to the table crashes at first use, not at build time.

Opaque: true means no metric. A handful of settings — netdns, http2debug, dataindependenttiming — are marked opaque because it is infeasible to count their non-default behaviour. The table comment says why for one of them:

 go
 
 
// src/internal/godebugs/table.go:69
	// Mark tracebacklabels as Opaque so we don't generate a metric that we can't increment.
	// IncNonDefault uses a sync.Once, which involves sync.Mutex, and is not safe from a signal handler.
	// (Tracebacks are generated in signal-handlers.)
	{Name: "tracebacklabels", Package: "runtime", Changed: 27, Old: "0", Opaque: true},

Immutable: true settings cannot be changed at runtime. fips140 is one. It is read once at startup and the rest of the program relies on that.

GODEBUG is not a configuration system. There are no typed values, no validation beyond “is this an integer that parses”, and no way to enumerate what is currently set — except by reading runtime/metrics for the non-default counters.

Runtime debug knobs are for debugging, not for tuning. efence=1 will make your program allocate a page per object. sbrk=1 replaces the entire allocator with one that never reclaims memory. These are diagnostic tools.

The go.mod godebug block requires Go 1.23 or later. Older toolchains reject it outright, and the default=goX.Y key does nothing before Go 1.21.

Wrapping up

The one thing to remember: GODEBUG is the mechanism that makes Go’s backwards-compatibility promise actionable. When a behaviour changes, Go ships a switch, records the old value in internal/godebugs/table.go, and the toolchain computes your defaults from the Go version in your go.mod.

The part people get wrong: a GODEBUG set in the environment overrides the compiled-in default, but the compiled-in default already reflects your go.mod version. Setting GODEBUG=panicnil=1 on a program whose go.mod says go 1.21 is redundant; setting it on one that says go 1.22 is not.

What to go do about it: when a dependency or a Go upgrade changes behaviour, read doc/godebug.md — it has a section per release listing every setting that changed and the exact value that restores the old behaviour. Then add the //go:debug line to your main package so the fix travels with the source.

Go's Interfaces Are Two Words and a Cached itab

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

TL;DR: A non-empty interface value is two words: a pointer to an itab and a pointer to the data. The empty interface swaps the itab for a plain type descriptor. The itab itself is a small table of method pointers, and for a concrete type the compiler emits it as a static symbol, so the conversion costs nothing at run time. When the type is not known statically – an interface-to-interface conversion, a type switch on a value of unknown type – the runtime builds the itab and caches it in a global hash table.

Go’s interfaces are famous for being two words. That part is easy. The part that catches people out is where the first word points, and what happens when the compiler cannot know the concrete type.

This is a walk through the layout and the lookup paths, based on reading the Go 1.28 development tree: src/runtime/iface.go, src/internal/abi/iface.go, and the compiler’s walk/convert.go and reflectdata/reflect.go.

The two layouts

The runtime keeps two interface representations. The first word of an empty interface is a type descriptor; the first word of a non-empty interface is an itab:

 go
 
 
// src/runtime/runtime2.go:184
type iface struct {
	tab *itab
	data unsafe.Pointer
}

type eface struct {
	_type *_type
	data unsafe.Pointer
}

The internal/abi package gives the same thing a name and documents the difference:

 go
 
 
// src/internal/abi/iface.go:12
// The first word of every non-empty interface type contains an *ITab.
// It records the underlying concrete type (Type), the interface type it
// is implementing (Inter), and some ancillary information.
//
// allocated in non-garbage-collected memory
type ITab struct {
	Inter *InterfaceType
	Type *Type
	Hash uint32 // copy of Type.Hash. Used for type switches.
	Fun [1]uintptr // variable sized. fun[0]==0 means Type does not implement Inter.
}

and:

 go
 
 
// src/internal/abi/iface.go:33
// EmptyInterface describes the layout of a "interface{}" or a "any."
// These are represented differently than non-empty interface, as the first
// word always points to an abi.Type.
type EmptyInterface struct {
	Type *Type
	Data unsafe.Pointer
}

// NonEmptyInterface describes the layout of an interface that contains any methods.
type NonEmptyInterface struct {
	ITab *ITab
	Data unsafe.Pointer
}

// CommonInterface describes the layout of both [EmptyInterface] and [NonEmptyInterface].
type CommonInterface struct {
	// Either an *ITab or a *Type, unexported to avoid accidental use.
	_ unsafe.Pointer

	Data unsafe.Pointer
}

CommonInterface is the interesting one: it is the common part of the two layouts, and it is what a generic function or an unsafe cast sees. The first word is deliberately untyped, because at that level you cannot know which of the two you have.

So, in memory:

 text
 
 
 var x error = myError{} // non-empty interface
 +-----------------------+
 | *itab ---------------> { Inter, Type, Hash, Fun[0], Fun[1], ... }
 +-----------------------+
 | data ---------------> the myError value (or a pointer to it)
 +-----------------------+

 var y any = 42 // empty interface
 +-----------------------+
 | *_type ---------------> the runtime type descriptor for int
 +-----------------------+
 | data ---------------> pointer to a copy of 42
 +-----------------------+

The data word: direct or boxed

The data word is a pointer, but not always to a separate object. If the concrete type is pointer-shaped, the value is the pointer and is stored directly. The runtime caches that decision in a flag on the type descriptor:

 go
 
 
// src/internal/abi/type.go:124
	// TFlagDirectIface means that a value of this type is stored directly
	// in the data field of an interface, instead of indirectly.
	// This flag is just a cached computation of Size_ == PtrBytes == goarch.PtrSize.
	TFlagDirectIface TFlag = 1 << 5

So boxing a *T, a map, a channel, or a func into an interface costs nothing: no allocation, no copy. Boxing an int costs an allocation, unless the compiler can find a cheaper home for it.

The compiler’s dataWord function is where all of that is decided, and it is worth reading because the list of special cases is long:

 go
 
 
// src/cmd/compile/internal/walk/convert.go:153
	// Try a bunch of cases to avoid an allocation.
	var value ir.Node
	byteVal, isConst := smallIntConst(n)
	switch {
	case fromType.Size() == 0:
		// n is zero-sized. Use zerobase.
		diagnose("using global for zero-sized interface value", n)
		w.cheapExpr(n, init) // Evaluate n for side-effects. See issue 19246.
		value = ir.NewLinksymExpr(base.Pos, ir.Syms.Zerobase, types.Types[types.TUINTPTR])
	case isBool || isInteger && (fromType.Size() == 1 || isConst):
		// n is a bool, a single-byte integer, or a compile-time constant in [0, 255].
		// Use staticuint64s[n * 8] on little-endian and staticuint64s[n * 8 + 7] on big-endian.
		diagnose("using global for small integer/boolean interface value", n)

The staticuint64s global is a 2 KiB table of pre-boxed small values. An int constant between 0 and 255 is boxed by pointing into that table, with no allocation at all.

If none of the special cases apply, the compiler calls into the runtime to box the value:

 go
 
 
// src/cmd/compile/internal/walk/convert.go:207
	// Time to do an allocation. We'll call into the runtime for that.
	fnname, argType, needsaddr := dataWordFuncName(fromType)
	var fn *ir.Name

and the runtime’s boxing helpers are small and specialised – one per shape of value:

 go
 
 
// src/runtime/iface.go:409
// convT64 should be an internal detail,
// but widely used packages access it using linkname.
// Notable members of the hall of shame include:
// - github.com/bytedance/sonic
//
// Do not remove or change the type signature.
// See go.dev/issue/67401.
//
//go:linkname convT64
func convT64(val uint64) (x unsafe.Pointer) {
	if val < uint64(len(staticuint64s)) {
		x = unsafe.Pointer(&staticuint64s[val])
	} else {
		x = mallocgc(8, uint64Type, false)
		*(*uint64)(x) = val
	}
	return
}

So convT64 has its own small-value cache, convTstring has a zero-value special case, convTslice avoids allocating a nil slice. These are the “conversion” routines that older Go versions called convT2E. In this tree they have been renamed and specialised, but the shape of the idea is the same: the data word is a pointer to a copy, and the runtime tries hard to avoid the copy.

Where the first word comes from

Now the interesting part. The compiler decides, for each conversion, what the first word should be:

 go
 
 
// src/cmd/compile/internal/reflectdata/helpers.go:95
// ConvIfaceTypeWord asserts that n is conversion to interface type,
// and returns an expression that yields the *runtime._type or
// *runtime.itab value necessary for implementing the conversion.
//
// - *runtime._type for the destination type, for I2I conversions
// - *runtime.itab, for T2I conversions
// - *runtime._type for the source type, for T2E conversions
func ConvIfaceTypeWord(curfunc *ir.Func, pos src.XPos, n *ir.ConvExpr) ir.Node {
	assertOp(n, ir.OCONVIFACE)
	src, dst := n.X.Type(), n.Type()
	base.AssertfAt(dst.IsInterface(), n.Pos(), "want interface type, have %L", n)
	if hasRType(n, n.TypeWord, "TypeWord") {
		return n.TypeWord
	}
	if dst.IsEmptyInterface() {
		return concreteRType(curfunc, pos, src) // direct eface construction
	}
	if !src.IsInterface() {
		return ITabAddrAt(curfunc, pos, src, dst) // direct iface construction
	}
	return TypePtrAt(curfunc, pos, dst) // convI2I
}

Three cases:

Concrete type to empty interface. The first word is a static pointer to the concrete type’s descriptor. No run-time work at all.
Concrete type to non-empty interface. The first word is a static pointer to an itab. No run-time work at all – but the itab has to exist in the binary first.
Interface to interface. The first word is the destination interface’s descriptor, and the conversion happens at run time, because the compiler does not know whether the source’s dynamic type implements the destination.

That third case is the one people remember as “every interface conversion costs a runtime call”. It is still true. But the first two cases, which is most of them, do not.

The static itab

The compiler emits the itab for a statically-known pair as an ordinary read-only global, and the runtime never sees it:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:1077
	// dump empty itab symbol into i.sym
	// type itab struct {
	// inter *interfacetype
	// _type *_type
	// hash uint32 // copy of _type.hash. Used for type switches.
	// _ [4]byte
	// fun [1]uintptr // variable sized. fun[0]==0 means _type does not implement inter.
	// }
	c := rttype.NewCursor(lsym, 0, rttype.ITab)
	c.Field("Inter").WritePtr(writeType(iface))
	c.Field("Type").WritePtr(writeType(typ))
	c.Field("Hash").WriteUint32(types.TypeHash(typ)) // copy of type hash

	var delta int64
	c = c.Field("Fun")
	if !completeItab {
		// If typ doesn't implement iface, make method entries be zero.
		c.Elem(0).WriteUintptr(0)
	} else {
		var a rttype.ArrayCursor
		a, delta = c.ModifyArray(len(entries))
		for i, fn := range entries {
			a.Elem(i).WritePtrWeak(fn) // method pointer for each method
		}
	}
	// Nothing writes static itabs, so they are read only.
	objw.Global(lsym, int32(rttype.ITab.Size()+delta), int16(obj.DUPOK|obj.RODATA))

That comment block is the canonical description of the itab layout, and it matches the ITab struct in internal/abi exactly: Inter, Type, Hash, then a variable-length array of function pointers, one per interface method, in the interface’s sorted method order.

The itab is written into the read-only data section, so it is shared across the whole binary and costs one pointer load at run time.

The dynamic itab: `getitab`

When the compiler does not know the concrete type – an interface-to-interface conversion, or a type switch on a value whose type is not known – the runtime has to find or build the itab. That is getitab:

 go
 
 
// src/runtime/iface.go:44
func getitab(inter *interfacetype, typ *_type, canfail bool) *itab {
	if len(inter.Methods) == 0 {
		throw("internal error - misuse of itab")
	}

	// easy case
	if typ.TFlag&abi.TFlagUncommon == 0 {
		if canfail {
			return nil
		}
		name := toRType(&inter.Type).nameOff(inter.Methods[0].Name)
		panic(&TypeAssertionError{nil, typ, &inter.Type, name.Name()})
	}

	var m *itab

	// First, look in the existing table to see if we can find the itab we need.
	// This is by far the most common case, so do it without locks.
	// Use atomic to ensure we see any previous writes done by the thread
	// that updates the itabTable field (with atomic.Storep in itabAdd).
	t := (*itabTableType)(atomic.Loadp(unsafe.Pointer(&itabTable)))
	if m = t.find(inter, typ); m != nil {
		goto finish
	}

	// Not found. Grab the lock and try again.
	lock(&itabLock)
	if m = itabTable.find(inter, typ); m != nil {
		unlock(&itabLock)
		goto finish
	}

	// Entry doesn't exist yet. Make a new entry & add it.
	m = (*itab)(persistentalloc(unsafe.Sizeof(itab{})+uintptr(len(inter.Methods)-1)*goarch.PtrSize, 0, &memstats.other_sys))
	m.Inter = inter
	m.Type = typ

The structure is the classic “read without a lock, take the lock only to mutate” pattern. The fast path is a lock-free hash-table probe.

The table itself is a single global, swapped out when it grows:

 go
 
 
// src/runtime/iface.go:15
const itabInitSize = 512

var (
	itabLock mutex // lock for accessing itab table
	itabTable = &itabTableInit // pointer to current table
	itabTableInit = itabTableType{size: itabInitSize} // starter table
)

// Note: change the formula in the mallocgc call in itabAdd if you change these fields.
type itabTableType struct {
	size uintptr // length of entries array. Always a power of 2.
	count uintptr // current number of filled entries.
	entries [itabInitSize]*itab // really [size] large
}

The hash is the xor of the two type hashes:

 go
 
 
// src/runtime/iface.go:30
func itabHashFunc(inter *interfacetype, typ *_type) uintptr {
	// compiler has provided some good hash codes for us.
	return uintptr(inter.Type.Hash ^ typ.Hash)
}

and the probe sequence is quadratic:

 go
 
 
// src/runtime/iface.go:105
// find finds the given interface/type pair in t.
// Returns nil if the given interface/type pair isn't present.
func (t *itabTableType) find(inter *interfacetype, typ *_type) *itab {
	// Implemented using quadratic probing.
	// Probe sequence is h(i) = h0 + i*(i+1)/2 mod 2^k.
	// We're guaranteed to hit all table entries using this probe sequence.
	mask := t.size - 1
	h := itabHashFunc(inter, typ) & mask
	for i := uintptr(1); ; i++ {
		p := (**itab)(add(unsafe.Pointer(&t.entries), h*goarch.PtrSize))
		// Use atomic read here so if we see m != nil, we also see
		// the initializations of the fields of m.
		// m := *p
		m := (*itab)(atomic.Loadp(unsafe.Pointer(p)))
		if m == nil {
			return nil
		}
		if m.Inter == inter && m.Type == typ {
			return m
		}
		h += i
		h &= mask
	}
}

Growth happens under the lock, at a 75% load factor, and the whole table is replaced rather than rehashed in place:

 go
 
 
// src/runtime/iface.go:130
// itabAdd adds the given itab to the itab hash table.
// itabLock must be held.
func itabAdd(m *itab) {
	// Bugs can lead to calling this while mallocing is set,
	// typically because this is called while panicking.
	// Crash reliably, rather than only when we need to grow
	// the hash table.
	if getg().m.mallocing != 0 {
		throw("malloc deadlock")
	}

	t := itabTable
	if t.count >= 3*(t.size/4) { // 75% load factor
		// Grow hash table.
		// t2 = new(itabTableType) + some additional entries
		// We lie and tell malloc we want pointer-free memory because
		// all the pointed-to values are not in the heap.
		t2 := (*itabTableType)(mallocgc((2+2*t.size)*goarch.PtrSize, nil, true))
		t2.size = t.size * 2

Note the persistentalloc in getitab: itabs live outside the garbage collected heap, because a program can create them at any time and they must never be collected.

Filling in the itab

Building an itab means matching the interface’s methods against the concrete type’s methods, in name order:

 go
 
 
// src/runtime/iface.go:209
func itabInit(m *itab, firstTime bool) string {
	inter := m.Inter
	typ := m.Type
	x := typ.Uncommon()

	// both inter and typ have method sorted by name,
	// and interface names are unique,
	// so can iterate over both in lock step;
	// the loop is O(ni+nt) not O(ni*nt).
	ni := len(inter.Methods)
	nt := int(x.Mcount)

The O(ni+nt) not O(ni*nt) comment is a nice piece of runtime engineering: both sides are sorted by method name, so a single merge pass suffices.

Type assertions

A type assertion to a concrete type does not call the runtime either. The compiler inlines it as a pointer comparison:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:6585
	// Converting to a concrete type.
	direct := types.IsDirectIface(dst)
	itab := s.newValue1(ssaop.OpITab, byteptr, iface) // type word of interface
	if base.Debug.TypeAssert > 0 {
		base.WarnfAt(pos, "type assertion inlined")
	}
	var wantedFirstWord *ssa.Value
	if src.IsEmptyInterface() {
		// Looking for pointer to target type.
		wantedFirstWord = target
	} else {
		// Looking for pointer to itab for target type and source interface.
		wantedFirstWord = targetItab
	}

For an empty interface, the comparison is against the type descriptor; for a non-empty one, against the itab. Either way it is a single pointer compare, and on failure the runtime is only consulted to produce the panic.

An assertion to another interface does need the runtime, because the runtime has to find the itab for the dynamic type and the destination interface:

 go
 
 
// src/runtime/iface.go:482
// typeAssert builds an itab for the concrete type t and the
// interface type s.Inter. If the conversion is not possible it
// panics if s.CanFail is false and returns nil if s.CanFail is true.
func typeAssert(s *abi.TypeAssert, t *_type) *itab {
	var tab *itab
	if t == nil {
		if !s.CanFail {
			panic(&TypeAssertionError{nil, nil, &s.Inter.Type, ""})
		}
	} else {
		tab = getitab(s.Inter, t, s.CanFail)
	}

and because that is a hot path, the runtime caches the answers in a small per-site hash table:

 go
 
 
// src/runtime/iface.go:495
	if !abi.UseInterfaceSwitchCache(goarch.ArchFamily) {
		return tab
	}

	// Maybe update the cache, so the next time the generated code
	// doesn't need to call into the runtime.
	if cheaprand()&1023 != 0 {
		// Only bother updating the cache ~1 in 1000 times.
		return tab
	}

One call in a thousand rebuilds the cache; the rest of the time the generated code hits the cache directly. Type switches work the same way, via interfaceSwitch, which walks the cases calling getitab for each.

The special case of `error`

error is not special to the runtime. It is an ordinary interface with one method:

 go
 
 
// src/builtin/builtin.go:315
// The error built-in interface type is the conventional interface for
// representing an error condition, with the nil value representing no error.
type error interface {
	Error() string
}

What is special is that the compiler and the runtime both have a canonical descriptor for it, so that every error in the program shares one itab layout and one type descriptor. The runtime’s own errors use a tiny predeclared type:

 go
 
 
// src/runtime/error.go:86
// An errorString represents a runtime error described by a single string.
type errorString string

func (e errorString) RuntimeError() {}

func (e errorString) Error() string {
	return "runtime error: " + string(e)
}

The RuntimeError() method is a marker: runtime.Error is an interface with that method, and it is how code distinguishes a runtime error from an ordinary one.

The famous footgun with error is not about the interface at all. It is about the data word. Take any concrete error type with a pointer receiver, such as the one errors.New hands back:

 go
 
 
// src/errors/errors.go:68
// errorString is a trivial implementation of error.
type errorString struct {
	s string
}

func (e *errorString) Error() string {
	return e.s
}

Storing a nil *errorString in an error gives you an interface whose itab word is non-nil (it points at the *errorString itab) and whose data word is a nil *errorString. The interface as a whole is non-nil, and err != nil is true. Only the data word is nil.

That is the direct-iface rule in action: a pointer-shaped concrete type is stored directly in the data word, so a nil pointer becomes a nil data word inside a non-nil interface.

errors.Is and errors.As navigate this world for you, and they are careful about it:

 go
 
 
// src/errors/wrap.go:45
func Is(err, target error) bool {
	if err == nil || target == nil {
		return err == target
	}

	isComparable := reflectlite.TypeOf(target).Comparable()
	return is(err, target, isComparable)
}

errors.As refuses to assign to a target that is not a pointer to an error type, and it walks the Unwrap chain, so it is the tool to reach for rather than a hand-written type switch.

Trade-offs

What the two-word layout buys: an interface value is the same size as a pointer, it can be passed in a register, and assigning one is a two-word copy with no allocation.

What it costs: the first word is a pointer to shared, read-only data that has to be found somehow. For statically-known pairs the compiler finds it for free. For dynamic ones the runtime has to look it up, and that lookup is a hash-table probe.

The data word’s polymorphism costs too. Boxing a non-pointer value means an allocation, and the compiler works hard to avoid it – the staticuint64s table, the zerobase global, the “stack temporary if it does not escape” case. Each of those is a special case in dataWord.

The itab table is a global mutable structure, which means it needs a lock and careful publication. The runtime solves that with an atomic pointer to the table, so readers never take the lock; only the rare insert does.

Caching is the other lever. The runtime keeps a per-site cache for type assertions and type switches, updated only about once in a thousand misses, so the steady-state cost of an interface-to-interface assertion is a hash lookup in a small table rather than a trip through getitab.

Caveats

Converting a concrete type to an interface is not free in general. It is free if the value is pointer-shaped, or a small integer constant, or zero-sized. Otherwise it allocates.

Converting an interface to another interface is a runtime call. The compiler cannot know whether the dynamic type implements the destination.

The itab lookup happens once per pair, then forever. The first interface-to-interface conversion of a given pair builds an itab; every later one finds it in the table.

getitab takes a global lock on a miss. Two goroutines converting the same unknown type at the same time will contend. The lock is not held for lookups that hit.

The itab table grows forever. Every distinct (interface, concrete type) pair that is converted dynamically at run time adds an entry. A program that generates types dynamically can grow this table without bound.

A nil pointer in an interface is not a nil interface. This is the single most common interface bug in Go, and it is a consequence of the direct-iface rule.

The data word of an interface holding a non-pointer points to a copy. If you mutate the original value after boxing it, the interface still sees the old copy.

Comparing two interface values compares the type words first. Two interfaces holding equal values of different dynamic types are not equal, and the comparison does not panic.

reflect on an interface value gives you the dynamic type. That is the type descriptor in the first word, and it is why fmt.Printf("%T", x) works without any cooperation from the value.

Wrapping up

The one thing to remember: an interface value is two words, and the first word is a pointer to a table that says what the concrete type is and where its methods live. For a statically-known concrete type, that table is a read-only symbol in the binary; for a dynamic one, it is looked up in a global hash table and cached forever.

The part people get wrong: interfaces are not “free” in the sense of “never cost anything”, but the expensive case is not the one people think. Converting a concrete type to an interface is a static pointer load; converting an interface to another interface is the one that calls into the runtime.

What to go do about it: if a hot path is spending time in getitab or runtime.typeAssert, look for interface-to-interface conversions and type switches over values of unknown type. If a hot path is allocating on interface conversion, look for non-pointer values being boxed, and consider passing a pointer instead.

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 defer and panic: Open-Coded Defers and the Runtime's Unwind Loop

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

TL;DR: A defer in Go is one of three things: a bit in a byte-sized mask on the stack plus a function pointer in a slot (“open-coded”), a _defer record in the goroutine’s defer chain (“stack-allocated”), or a _defer record on the heap (“heap-allocated”). Which one you get depends on where the defer statement sits. panic then walks the stack looking for those three shapes in order, running deferred calls as it goes.

Go’s defer looks like a language feature. It is really three different mechanisms wearing the same syntax, and the runtime keeps them apart.

The distinction matters for two reasons. First, it is the difference between a defer that costs about a nanosecond and one that costs seventy. Second, it is the reason a defer inside a loop behaves differently from a defer outside one, even though the source looks identical.

This is a walk through all of it, based on reading the Go 1.28 development tree (src/runtime/panic.go, src/runtime/runtime2.go, and the compiler passes in src/cmd/compile/internal/).

The runtime’s own summary

The runtime opens with a comment that is worth reading in full, because it is the design in prose:

 go
 
 
// src/runtime/panic.go:38
// We have two different ways of doing defers. The older way involves creating a
// defer record at the time that a defer statement is executing and adding it to a
// defer chain. This chain is inspected by the deferreturn call at all function
// exits in order to run the appropriate defer calls. A cheaper way (which we call
// open-coded defers) is used for functions in which no defer statements occur in
// loops. In that case, we simply store the defer function/arg information into
// specific stack slots at the point of each defer statement, as well as setting a
// bit in a bitmask. At each function exit, we add inline code to directly make
// the appropriate defer calls based on the bitmask and fn/arg information stored
// on the stack. During panic/Goexit processing, the appropriate defer calls are
// made using extra funcdata info that indicates the exact stack slots that
// contain the bitmask and defer fn/args.

Note the constraint in the middle: open-coded defers are used “for functions in which no defer statements occur in loops”. That single clause is the source of almost every surprise people have about defer performance.

The three kinds of defer

Kind	Where the state lives	Allocated when	Cost
Open-coded	a bit in a `uint8` mask + a function value in a stack slot	compile time	roughly 1 ns
Stack-allocated	a `_defer` record in the goroutine’s defer chain	the `defer` statement executes	roughly 35 ns
Heap-allocated	a `_defer` record allocated on the heap	the `defer` statement executes	roughly 50-70 ns

The rough nanosecond figures are the numbers the Go wiki has published for years; they are not stated anywhere in the source tree, so treat them as orders of magnitude rather than measurements. The tree’s own benchmarks are BenchmarkDefer (open-coded), BenchmarkDefer10 (a defer in a loop) and BenchmarkDeferMany, all in src/runtime/runtime_test.go. BenchmarkDefer10 is the interesting one: the ten defers in the loop are all live at once, and the loop is exactly what knocks the function off the open-coded path.

The `_defer` record

The non-open-coded kinds share one record type. The runtime defines it, and the compiler mirrors the layout exactly:

 go
 
 
// src/runtime/runtime2.go:1150
// A _defer holds an entry on the list of deferred calls.
// If you add a field here, add code to clear it in deferProcStack.
// This struct must match the code in cmd/compile/internal/ssagen/ssa.go:deferstruct
// and cmd/compile/internal/ssagen/ssa.go:(*state).call.
// Some defers will be allocated on the stack and some on the heap.
// All defers are logically part of the stack, so write barriers to
// initialize them are not required. All defers must be manually scanned,
// and for heap defers, marked.
type _defer struct {
	heap bool
	rangefunc bool // true for rangefunc list
	sp uintptr // sp at time of defer
	pc uintptr // pc at time of defer
	fn func() // can be nil for open-coded defers
	link *_defer // next defer on G; can point to either heap or stack!

	// If rangefunc is true, *head is the head of the atomic linked list
	// during a range-over-func execution.
	head *atomic.Pointer[_defer]
}

The sp and pc fields are the whole trick for unwinding: they record where the defer statement was, so the runtime can tell which deferred calls belong to the frame it is currently unwinding. The link field makes the chain a singly-linked list hanging off g._defer.

The compiler builds a byte-for-byte identical struct for the stack-allocated case, in cmd/compile/internal/ssagen/ssa.go:deferstruct, with one instruction worth noting: the pointer-carrying fields are declared as uintptr, because defer records are scanned explicitly during stack copying and by the GC rather than through the type’s pointer map.

Open-coded defers: one bit each

The fast path is entirely compile-time. The compiler reserves a one-byte variable, deferBits, in the function’s frame:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:449
	if s.hasOpenDefers {
		// Create the deferBits variable and stack slot. deferBits is a
		// bitmask showing which of the open-coded defers in this function
		// have been activated.
		deferBitsTemp := typecheck.TempAt(src.NoXPos, s.curfn, types.Types[types.TUINT8])
		deferBitsTemp.SetAddrtaken(true)
		s.deferBitsTemp = deferBitsTemp
		// For this value, AuxInt is initialized to zero by default
		startDeferBits := s.entryNewValue0(ssaop.OpConst8, types.Types[types.TUINT8])
		s.vars[deferBitsVar] = startDeferBits
		s.deferBitsAddr = s.addr(deferBitsTemp)
		s.store(types.Types[types.TUINT8], s.deferBitsAddr, startDeferBits)

One byte, so eight defers maximum. That limit is enforced in the walker, and the reason is stated plainly:

 go
 
 
// src/cmd/compile/internal/walk/walk.go:306
// The max number of defers in a function using open-coded defers. We enforce this
// limit because the deferBits bitmask is currently a single byte (to minimize code size)
const maxOpenDefers = 8

When the defer statement executes, the compiler stores the function value into a dedicated stack slot and sets one bit:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:4868
	// Update deferBits only after evaluation and storage to stack of
	// the function is successful.
	bitvalue := s.constInt8(types.Types[types.TUINT8], 1<<uint(index))
	newDeferBits := s.newValue2(ssaop.OpOr8, types.Types[types.TUINT8], s.variable(deferBitsVar, types.Types[types.TUINT8]), bitvalue)
	s.vars[deferBitsVar] = newDeferBits
	s.store(types.Types[types.TUINT8], s.deferBitsAddr, newDeferBits)

So the runtime data structure for a function with four defers is:

 text
 
 
 frame of f()
 +----------------------+
 | deferBits: uint8 | bit 0 = defer #1 armed
 | | bit 1 = defer #2 armed
 | | ...
 +----------------------+
 | slot 0: func() | closure for defer #1
 | slot 1: func() | closure for defer #2
 | slot 2: func() | closure for defer #3
 | slot 3: func() | closure for defer #4
 +----------------------+

At every return site the compiler emits inline code that loads the byte, tests each bit in reverse order, and calls the matching slot. No call to the runtime at all, no allocation, no list.

The `deferreturn` trampoline

Functions that use the non-open-coded kinds end their body with a call to a runtime trampoline:

 go
 
 
// src/runtime/panic.go:655
// deferreturn runs deferred functions for the caller's frame.
// The compiler inserts a call to this at the end of any
// function which calls defer.
func deferreturn() {
	var p _panic
	p.deferreturn = true

	p.start(sys.GetCallerPC(), unsafe.Pointer(sys.GetCallerSP()))
	for {
		fn, ok := p.nextDefer()
		if !ok {
			break
		}
		fn()
	}
}

Notice that deferreturn reuses the panic machinery. It builds a _panic value with deferreturn set, and then runs the same nextDefer loop that gopanic runs. That is not an accident of implementation; it is how the runtime keeps one implementation of “run the deferred calls for this frame”.

The trampoline’s address is recorded by the linker, per function, so that the panic unwinder can find it later. src/cmd/link/internal/ld/pcln.go computes it in computeDeferReturn, and the runtime reads it back out of the function metadata.

Open-coded functions get a deferreturn call too, but a disconnected one: the compiler emits a call to the trampoline and a return that are never executed on the normal path, purely so that a deferred function which recovers a panic has somewhere to return to:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:7282
	if openDeferInfo != nil {
		// When doing open-coded defers, generate a disconnected call to
		// deferreturn and a return. This will be used to during panic
		// recovery to unwind the stack and return back to the runtime.

That is why initOpenCodedDefers can insist on a non-zero deferreturn offset: it is the address the runtime jumps back to when a recover happens inside an open-coded defer.

Stack-allocated and heap-allocated defers

When open-coding is off, the compiler emits a call to one of two runtime helpers. The stack variant is used when the compiler can prove the defer’s arguments do not escape:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:1738
		if s.hasOpenDefers {
			s.openDeferRecord(n.Call.(*ir.CallExpr))
		} else {
			d := callDefer
			if n.Esc() == ir.EscNever && n.DeferAt == nil {
				d = callDeferStack
			}
			s.call(n.Call.(*ir.CallExpr), d, false, n.DeferAt)
		}

callDeferStack builds a _defer record in the function’s own frame and hands its address to the runtime:

 go
 
 
// src/runtime/panic.go:538
// deferprocStack queues a new deferred function with a defer record on the stack.
// The defer record must have its fn field initialized.
// All other fields can contain junk.
// Nosplit because of the uninitialized pointer fields on the stack.
//
//go:nosplit
func deferprocStack(d *_defer) {
	gp := getg()
	if gp.m.curg != gp {
		// go code on the system stack can't defer
		throw("defer on system stack")
	}

	// fn is already set.
	// The other fields are junk on entry to deferprocStack and
	// are initialized here.
	d.heap = false
	d.rangefunc = false
	d.sp = sys.GetCallerSP()
	d.pc = sys.GetCallerPC()
	// The lines below implement:
	// d.link = gp._defer
	// d.head = nil
	// gp._defer = d
	// But without write barriers. The first two are writes to
	// the stack so they don't need a write barrier, and furthermore
	// are to uninitialized memory, so they must not use a write barrier.
	// The third write does not require a write barrier because we
	// explicitly mark all the defer structures, so we don't need to
	// keep track of pointers to them with a write barrier.
	*(*uintptr)(unsafe.Pointer(&d.link)) = uintptr(unsafe.Pointer(gp._defer))
	*(*uintptr)(unsafe.Pointer(&d.head)) = 0
	*(*uintptr)(unsafe.Pointer(&gp._defer)) = uintptr(unsafe.Pointer(d))
}

The heap variant is deferproc, which allocates the record from a per-P pool and links it onto the goroutine’s chain:

 go
 
 
// src/runtime/panic.go:351
// Create a new deferred function fn, which has no arguments and results.
// The compiler turns a defer statement into a call to this.
func deferproc(fn func()) {
	gp := getg()
	if gp.m.curg != gp {
		// go code on the system stack can't defer
		throw("defer on system stack")
	}

	d := newdefer()
	d.link = gp._defer
	gp._defer = d
	d.fn = fn
	d.pc = sys.GetCallerPC()
	// We must not be preempted between calling GetCallerSP and
	// storing it to d.sp because GetCallerSP's result is a
	// uintptr stack pointer.
	d.sp = sys.GetCallerSP()
}

and the allocation comes from a pool, not from mallocgc. newdefer in src/runtime/panic.go:578 takes a _defer from the current P’s deferpool, refilling it from the central sched.deferpool under sched.deferlock when it runs dry, and only falls back to new(_defer) – the actual heap allocation – when both pools are empty. The records are returned to the pool by popDefer when the defer runs.

Why a `defer` in a loop kills open-coding

This is the rule people trip over. The escape analysis pass is what decides, and it uses loopDepth to detect the loop:

 go
 
 
// src/cmd/compile/internal/escape/call.go:237
// goDeferStmt analyzes a "go" or "defer" statement.
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)
	}

loopDepth == 1 means “directly in the function body”. Inside a loop the depth is greater, the EscNever marking never happens, and the defer ends up on the heap path.

There are three more ways to lose open-coding, all in one place in the walker:

 go
 
 
// src/cmd/compile/internal/walk/stmt.go:106
	case ir.ODEFER:
		n := n.(*ir.GoDeferStmt)
		w.curfunc.SetHasDefer(true)
		w.curfunc.NumDefers++
		if w.curfunc.NumDefers > maxOpenDefers || n.DeferAt != nil {
			// Don't allow open-coded defers if there are more than
			// 8 defers in the function, since we use a single
			// byte to record active defers.
			// Also don't allow if we need to use deferprocat.
			w.curfunc.SetOpenCodedDeferDisallowed(true)
		}
		if n.Esc() != ir.EscNever {
			// If n.Esc is not EscNever, then this defer occurs in a loop,
			// so open-coded defers cannot be used in this function.
			w.curfunc.SetOpenCodedDeferDisallowed(true)
		}

So open-coding is off when: there are more than eight defers, the defer is in a loop, the defer needs the range-over-func mechanism, or the function is too complicated for the inline exit code (the SSA pass also bails out when NumReturns*NumDefers > 15, or when the function has heap-allocated results, or when race instrumentation is on).

Panic: the unwind loop

panic is not a special control flow mechanism. It is a loop that runs deferred calls, frame by frame, until it runs out of them or somebody recovers.

 go
 
 
// src/runtime/panic.go:799
// The implementation of the predeclared function panic.
// The compiler emits calls to this function.
//
// gopanic should be an internal detail,
// but historically, widely used packages access it using linkname.
//
// Do not remove or change the type signature.
// See go.dev/issue/67401.
//
//go:linkname gopanic
func gopanic(e any) {
	if e == nil {
		if debug.panicnil.Load() != 1 {
			e = new(PanicNilError)
		} else {
			panicnil.IncNonDefault()
		}
	}

and then the loop:

 go
 
 
// src/runtime/panic.go:848
	var p _panic
	p.arg = e

	runningPanicDefers.Add(1)

	p.start(sys.GetCallerPC(), unsafe.Pointer(sys.GetCallerSP()))
	for {
		fn, ok := p.nextDefer()
		if !ok {
			break
		}
		fn()
	}

The interesting part is nextDefer, because it is where the three defer kinds come together. It checks the open-coded mask first, then the defer chain:

 go
 
 
// src/runtime/panic.go:944
	for {
		for p.deferBitsPtr != nil {
			bits := *p.deferBitsPtr

			// Check whether any open-coded defers are still pending.
			//
			// Note: We need to check this upfront (rather than after
			// clearing the top bit) because it's possible that Goexit
			// invokes a deferred call, and there were still more pending
			// open-coded defers in the frame; but then the deferred call
			// panic and invoked the remaining defers in the frame, before
			// recovering and restarting the Goexit loop.
			if bits == 0 {
				p.deferBitsPtr = nil
				break
			}

			// Find index of top bit set.
			i := 7 - uintptr(sys.LeadingZeros8(bits))

			// Clear bit and store it back.
			bits &^= 1 << i
			*p.deferBitsPtr = bits

			return *(*func())(add(p.slotsPtr, i*goarch.PtrSize)), true
		}

	Recheck:
		if d := gp._defer; d != nil && d.sp == uintptr(p.sp) {
			if d.rangefunc {
				deferconvert(d)
				popDefer(gp)
				goto Recheck
			}

			fn := d.fn

			p.retpc = d.pc

			// Unlink and free.
			popDefer(gp)

			return fn, true
		}

		if !p.nextFrame() {
			return nil, false
		}
	}

Read the open-coded branch carefully. sys.LeadingZeros8 finds the highest set bit, which is the last defer to run, because defers run in reverse order. The bit is cleared before the call so that if the deferred function panics, this defer is not run a second time.

The chain branch checks d.sp == uintptr(p.sp): the deferred call belongs to the frame currently being unwound. If the top of the chain belongs to a different frame, nextFrame walks the stack up one frame and tries again.

Finding the open-coded mask during a panic

During a panic, the runtime is not running the function’s exit code, so it cannot read deferBits from a known place. Instead it uses funcdata recorded by the compiler:

 go
 
 
// src/runtime/panic.go:1059
func (p *_panic) initOpenCodedDefers(fn funcInfo, varp unsafe.Pointer) bool {
	fd := funcdata(fn, abi.FUNCDATA_OpenCodedDeferInfo)
	if fd == nil {
		return false
	}

	if fn.deferreturn == 0 {
		throw("missing deferreturn")
	}

	deferBitsOffset, fd := readvarintUnsafe(fd)
	deferBitsPtr := (*uint8)(add(varp, -uintptr(deferBitsOffset)))
	if *deferBitsPtr == 0 {
		return false // has open-coded defers, but none pending
	}

	slotsOffset, fd := readvarintUnsafe(fd)

	p.retpc = fn.entry() + uintptr(fn.deferreturn)
	p.deferBitsPtr = deferBitsPtr
	p.slotsPtr = add(varp, -uintptr(slotsOffset))

	return true
}

The funcdata itself is two varints – the offset of the deferBits byte and the offset of the first closure slot – as documented in cmd/compile/internal/ssagen/ssa.go:emitOpenDeferInfo. Two offsets and eight bits: that is the entire runtime description of an open-coded defer set.

`recover` only works in a deferred function

recover is a very small function:

 go
 
 
// src/runtime/panic.go:1084
// The implementation of the predeclared function recover.
func gorecover() any {
	p := recoverablePanic(3) // skip systemstack_switch, recoverablePanic, gorecover
	if p == nil {
		return nil
	}
	p.recovered = true
	return p.arg
}

The work is in recoverablePanic, which has to answer one question: is the function calling recover the function that the panicking function deferred? The runtime walks the stack from the recover call up to gopanic, counting frames that are not wrappers, and the answer is “there must be exactly one non-wrapper frame between gopanic and gorecover”:

 go
 
 
// src/runtime/panic.go:1179
// So our criteria is, there must be exactly one non-wrapper
// frame between gopanic and gorecover.
//
// We don't recover this:
//
//	defer func() { func() { recover() }() }()
//
// because there are 2 non-wrapper frames.
//
// We don't recover this:
//
//	defer recover()
//
// because there are 0 non-wrapper frames.
//
// It must not be inlined into its callers: they count on its frame being
// there to skip.
//
//go:noinline
func recoverablePanic(skip int) *_panic {
	gp := getg()
	p := gp._panic
	if p == nil || p.goexit || p.recovered {
		return nil
	}

	canRecover := false
	systemstack(func() {
		var u unwinder
		u.init(gp, 0)
		for i := 0; i < skip; i++ {
			u.next()
		}
		nonWrapperFrames := 0
	loop:
		for ; u.valid(); u.next() {
			for iu, f := newInlineUnwinder(u.frame.fn, u.symPC()); f.valid(); f = iu.next(f) {
				sf := iu.srcFunc(f)
				switch sf.funcID {
				case abi.FuncIDWrapper:
					continue
				case abi.FuncID_gopanic:
					if u.frame.sp == uintptr(p.startSP) && nonWrapperFrames > 0 {
						canRecover = true
					}
					break loop
				default:
					nonWrapperFrames++
					if nonWrapperFrames > 1 {
						break loop
					}
				}
			}
		}
	})
	if !canRecover {
		return nil
	}
	return p
}

So recover inside a helper called by your deferred function does nothing, and defer recover() does nothing either. It has to be called directly by the deferred function.

`panic(nil)` and `runtime.Goexit`

Two special cases deserve their own mention, because both changed in recent Go versions.

panic(nil) used to be indistinguishable from “no panic” after a recover. Since Go 1.21 it produces a *runtime.PanicNilError:

 go
 
 
// src/runtime/panic.go:779
// A PanicNilError happens when code calls panic(nil).
//
// Before Go 1.21, programs that called panic(nil) observed recover returning nil.
// Starting in Go 1.21, programs that call panic(nil) observe recover returning a *PanicNilError.
// Programs can change back to the old behavior by setting GODEBUG=panicnil=1.
type PanicNilError struct {
	// This field makes PanicNilError structurally different from
	// any other struct in this package, and the _ makes it different
	// from any struct in other packages too.
	// This avoids any accidental conversions being possible
	// between this struct and some other struct sharing the same fields,
	// like happened in go.dev/issue/56603.
	_ [0]*PanicNilError
}

func (*PanicNilError) Error() string { return "runtime error: panic called with nil argument" }
func (*PanicNilError) RuntimeError() {}

runtime.Goexit is a panic that is not a panic. It runs all the deferred calls and then kills the goroutine, and recover inside those deferred calls returns nil:

 go
 
 
// src/runtime/panic.go:672
// Goexit terminates the goroutine that calls it. No other goroutine is affected.
// Goexit runs all deferred calls before terminating the goroutine. Because Goexit
// is not a panic, any recover calls in those deferred functions will return nil.
//
// Calling Goexit from the main goroutine terminates that goroutine
// without func main returning. Since func main has not returned,
// the program continues execution of other goroutines.
// If all other goroutines exit, the program crashes.
//
// It crashes if called from a thread not created by the Go runtime.
func Goexit() {
	// Create a panic object for Goexit, so we can recognize when it might be
	// bypassed by a recover().
	var p _panic
	p.goexit = true

	p.start(sys.GetCallerPC(), unsafe.Pointer(sys.GetCallerSP()))
	for {
		fn, ok := p.nextDefer()
		if !ok {
			break
		}
		fn()
	}

	goexit1()
}

Structurally it is the same loop as gopanic. The difference is the goexit flag, which recoverablePanic checks and refuses to recover.

Trade-offs

What open-coding buys: a defer in a normal function is a store, an OR, and a bit test. There is no allocation, no lock, no call into the runtime, and no GC-visible pointer in most cases.

What it costs: every exit site of the function grows. The compiler has to emit the bit-test-and-call sequence at every return, which is why it gives up when a function has many returns (NumReturns*NumDefers > 15) and why the mask is limited to eight defers.

What the chain-based kinds buy: they handle the cases open-coding cannot – unbounded numbers of defers, defers in loops, defers whose arguments escape. The chain is a simple intrusive linked list, and the runtime walks it.

What they cost: deferprocStack and deferproc are real function calls into the runtime, deferproc may allocate, and every deferred call is reached through a pointer chase. A loop with a million defers inside it will hold a million records alive at once.

The panic machinery pays a similar tax. Unwinding a frame that used open-coded defers requires reading funcdata, decoding two varints, and computing two stack addresses. It is not free, but it is a lot cheaper than the old scheme, where a panic had to walk the whole stack looking for defer records.

Caveats

Open-coding is an optimisation, not a guarantee. The compiler changes its mind based on the whole function: eight defers, loops, escaping arguments, race instrumentation, heap-allocated results. Never write code that depends on which kind you got.

The bitmask is one byte. Nine defers in a function disables open-coding for the whole function, not just the ninth defer.

A defer in a loop accumulates. Each iteration adds a record; none are removed until the function returns. Ten thousand iterations means ten thousand live records, and on the heap-allocated path that is ten thousand allocations.

recover is frame-sensitive. It only works when called directly by a deferred function. A recover in a helper function does nothing at all, and it returns nil rather than panicking, so it fails silently.

recover returns the panic value, not the stack. The stack is printed by the runtime at crash time, not captured by recover.

panic(nil) is not nil. Since Go 1.21 it is a *runtime.PanicNilError. Code that checks if r := recover(); r != nil now behaves differently from Go 1.20 and earlier, which is exactly why the change was made.

runtime.Goexit is not recoverable. Deferred calls run, recover returns nil, and the goroutine dies. This is how testing stops a test function: t.FailNow calls runtime.Goexit so that the deferred cleanup in the test runs before the goroutine disappears.

A panic while holding a lock is fatal. gopanic checks gp.m.locks != 0 and throws rather than trying to unwind, because running deferred code with a held lock could deadlock.

Wrapping up

The one thing to remember: a defer is a bit in a byte on the stack when the compiler can prove it can be, and a linked-list record otherwise. The bit is set when the defer statement runs; the exit code of the function tests the bits and calls the matching slots.

The part people get wrong: a defer inside a loop is not a cheaper defer, it is a different and much more expensive defer, and all of them stay live until the function returns. The escape analyser is what decides, and it uses loop depth, not your intent.

What to go do about it: run go build -gcflags=-m and look for “deferring” escape notes, or benchmark your function with and without the defer in the loop. If you need cleanup per iteration, call it explicitly at the bottom of the loop body instead of deferring it.

Runtime on Opensource internals

Why Go Randomizes Map Iteration: The Attack It Prevents

The spec’s promise

The two random mechanisms

The hash seed

The random iteration start

Where the offsets get used

The runtime’s random numbers

The compiler’s entry point

The maps package inherits it

Trade-offs

Caveats

Wrapping up

Further reading

Weak Pointers in Go: The Runtime's Special Span for Non-Tracked Objects

The API

What is actually stored

Registering the handle

The special kinds

How the GC treats weak references

Marking: the handle is a root, the target is not

Sweeping: the handle is zeroed

Converting back to a strong pointer

Trade-offs

Caveats

Wrapping up

Further reading

runtime.AddCleanup: How Go Replaced Finalizers With a Queue of Specials

The problem with finalizers

The new design: cleanups

The argument is boxed on purpose

The special record

How the GC finds cleanups

The queue: 512-byte blocks and a lock-free stack

The sweeper enqueues, per-P

Flushing and waking the workers

The sleeping protocol

Trade-offs

Caveats

Wrapping up

Further reading

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's reflect Package Reads Types: The rtype and the Method Table

One type description, two readers

The flag bitfield

The method table

reflect.Value: a triple with a bitfield

packEface: turning a Value back into an any

reflect.TypeOf is an interface conversion

The itab: interface dispatch, for contrast

Reflection versus a type switch

Trade-offs

Caveats

Wrapping up

Further reading

How cgo Works in Go: The Two Compilers and a Bit of Magic

The preamble is the source of truth

The file pipeline

The symbol rewriting

The Go side of a call

The C side of a call

//export: C calling Go

The cost of a call

The pointer rules, and how they’re enforced

Trade-offs

Caveats

Wrapping up

Further reading

GODEBUG: The Knobs Go Gives You to Turn Up the Volume

Two mechanisms, one variable

The `maps` package inherits it

`defer` inside the loop body

`recover` inside the loop body

packEface: turning a Value back into an `any`

`//go:debug` and the `go.mod` block

The dynamic itab: `getitab`

The special case of `error`

The `_defer` record

The `deferreturn` trampoline

Why a `defer` in a loop kills open-coding

`recover` only works in a deferred function

`panic(nil)` and `runtime.Goexit`