Go 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.

unsafe.Pointer and //go:linkname: The Escape Hatches That Break Abstraction

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

TL;DR: unsafe.Pointer is the type system with the safety catch removed. //go:linkname is the other escape hatch: it lets one package call another package’s unexported function by its link-time symbol name. The linker now keeps an explicit allowlist of who may pull which linkname.

Go’s type system is one of its best features and also, occasionally, an obstacle. Sometimes you need to reinterpret a []byte as a []int32. Sometimes you need to call a function the standard library clearly meant to keep to itself. Go provides two doors for both situations, and both of them are unlocked with a comment that says unsafe or linkname.

Understanding how these work matters even if you never use them, because they explain a lot about how the compiler and linker are put together, and because the guard rails around them have changed a lot in the last few releases.

unsafe.Pointer: the type system, optional

The unsafe package documentation opens with the deal:

 go
 
 
// src/unsafe/unsafe.go:21
// Pointer represents a pointer to an arbitrary type. There are four special operations
// available for type Pointer that are not available for other types:
// - A pointer value of any type can be converted to a Pointer.
// - A Pointer can be converted to a pointer value of any type.
// - A uintptr can be converted to a Pointer.
// - A Pointer can be converted to a uintptr.
//
// Pointer therefore allows a program to defeat the type system and read and write
// arbitrary memory. It should be used with extreme care.
//
// The following patterns involving Pointer are valid.
// Code not using these patterns is likely to be invalid today
// or to become invalid in the future.
// Even the valid patterns below come with important caveats.
//
// Running "go vet" can help find uses of Pointer that do not conform to these patterns,
// but silence from "go vet" is not a guarantee that the code is valid.

Then it enumerates the legal patterns. There are five of them, and the distinctions between them are not academic — they are the difference between code that works and code that breaks the moment the garbage collector moves something.

Pattern 1: reinterpret a pointer.

 go
 
 
// src/unsafe/unsafe.go:39
// (1) Conversion of a *T1 to Pointer to *T2.
//
// Provided that T2 is no larger than T1 and that the two share an equivalent
// memory layout, this conversion allows reinterpreting data of one type as
// data of another type. An example is the implementation of
// math.Float64bits:
//
//	func Float64bits(f float64) uint64 {
//		return *(*uint64)(unsafe.Pointer(&f))
//	}

Pattern 2: convert to uintptr and stop. A uintptr is an integer, not a reference. The collector will not update it and will not keep the object alive.

Pattern 3: convert to uintptr, add an offset, convert back — and the conversion must appear in the same expression:

 go
 
 
// src/unsafe/unsafe.go:68
// (3) Conversion of a Pointer to a uintptr and back, with arithmetic.
//
// If p points into an allocated object, it can be advanced through the object
// by conversion to uintptr, addition of an offset, and conversion back to Pointer.
//
//	p = unsafe.Pointer(uintptr(p) + offset)

If you stash the uintptr in a variable in between, the collector is free to move the object and you get a dangling pointer. This is the single most common way people get unsafe wrong, and it is why go vet has a unsafeptr check for it.

Pattern 4: pass a pointer as a uintptr to a syscall, in the argument list, because the compiler knows to keep the object alive across the call.

Pattern 5: convert the result of reflect.Value.Pointer() back immediately, in the same expression.

Pattern 6: use reflect.SliceHeader / reflect.StringHeader, which are only valid when pointing at an actual slice or string.

The modern intrinsics

The unsafe package has grown a set of functions that are much safer than the raw uintptr dance, and these are what you should reach for first:

 go
 
 
// src/unsafe/unsafe.go:229
// The function Slice returns a slice whose underlying array starts at ptr
// and whose length and capacity are len.
// Slice(ptr, len) is equivalent to
//
//	(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
//
// except that, as a special case, if ptr is nil and len is zero,
// Slice returns nil.
//
// The len argument must be of integer type or an untyped constant.
// A constant len argument must be non-negative and representable by a value of type int;
// if it is an untyped constant it is given type int.
// At run time, if len is negative, or if ptr is nil and len is not zero,
// a run-time panic occurs.
func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType

// SliceData returns a pointer to the underlying array of the argument
// slice.
// - If cap(slice) > 0, SliceData returns &slice[:1][0].
// - If slice == nil, SliceData returns nil.
// - Otherwise, SliceData returns a non-nil pointer to an
// unspecified memory address.
func SliceData(slice []ArbitraryType) *ArbitraryType

unsafe.Slice is the modern replacement for the (*[n]T)(ptr)[:] idiom. It takes a *T rather than an unsafe.Pointer, which means the compiler knows the element type and can size the resulting slice correctly. unsafe.SliceData is the inverse, and unsafe.StringData / unsafe.String do the same job for strings.

None of these are ordinary Go functions. They have no bodies. The compiler gives them dedicated opcodes:

 go
 
 
// src/cmd/compile/internal/typecheck/typecheck.go:456
	case ir.OUNSAFESLICE:
		n := n.(*ir.BinaryExpr)
		return tcUnsafeSlice(curfunc, n)

	case ir.OUNSAFESLICEDATA:
		n := n.(*ir.UnaryExpr)
		return tcUnsafeData(curfunc, n)

	case ir.OUNSAFESTRING:
		n := n.(*ir.BinaryExpr)
		return tcUnsafeString(curfunc, n)

	case ir.OUNSAFESTRINGDATA:
		n := n.(*ir.UnaryExpr)
		return tcUnsafeData(curfunc, n)

The type checker enforces the preconditions:

 go
 
 
// src/cmd/compile/internal/typecheck/func.go:767
// tcUnsafeSlice typechecks an OUNSAFESLICE node.
func tcUnsafeSlice(curfunc *ir.Func, n *ir.BinaryExpr) *ir.BinaryExpr {
	n.X = Expr(curfunc, n.X)
	n.Y = Expr(curfunc, n.Y)
	if n.X.Type() == nil || n.Y.Type() == nil {
		n.SetType(nil)
		return n
	}
	t := n.X.Type()
	if !t.IsPtr() {
		base.Errorf("first argument to unsafe.Slice must be pointer; have %L", t)
	} else if t.Elem().NotInHeap() {
		// TODO(mdempsky): This can be relaxed, but should only affect the
		// Go runtime itself. End users should only see not-in-heap
		// types due to incomplete C structs in cgo, and those types don't
		// have a meaningful size anyway.
		base.Errorf("unsafe.Slice of incomplete (or unallocatable) type not allowed")
	}

And then the compiler inlines the runtime check rather than calling it, to avoid the call overhead:

 go
 
 
// src/cmd/compile/internal/walk/builtin.go:783
func (w *walkState) walkUnsafeSlice(n *ir.BinaryExpr, init *ir.Nodes) ir.Node {
	ptr := w.safeExpr(n.X, init)
	len := w.safeExpr(n.Y, init)
	sliceType := n.Type()

	lenType := types.Types[types.TINT64]
	unsafePtr := typecheck.Conv(w.curfunc, ptr, types.Types[types.TUNSAFEPTR])

	// If checkptr enabled, call runtime.unsafeslicecheckptr to check ptr and len.
	// for simplicity, unsafeslicecheckptr always uses int64.
	// Type checking guarantees that TIDEAL len/cap are positive and fit in an int.
	// The case of len or cap overflow when converting TUINT or TUINTPTR to TINT
	// will be handled by the negative range checks in unsafeslice during runtime.
	if ir.ShouldCheckPtr(w.curfunc, 1) {
		fnname := "unsafeslicecheckptr"
		fn := typecheck.LookupRuntime(fnname)
		init.Append(w.mkcall1(fn, nil, init, reflectdata.UnsafeSliceElemRType(w.curfunc, base.Pos, n), unsafePtr, typecheck.Conv(w.curfunc, len, lenType)))
	} else {
		// Otherwise, open code unsafe.Slice to prevent runtime call overhead.
		// Keep this code in sync with runtime.unsafeslice{,64}

The comment “Keep this code in sync with runtime.unsafeslice{,64}” is a loose end the maintainers knowingly accept: the fast path is open-coded in the compiler, and the slow path lives in the runtime, and they have to agree.

 go
 
 
// src/runtime/unsafe.go:53
// Keep this code in sync with cmd/compile/internal/walk/builtin.go:walkUnsafeSlice
func unsafeslice(et *_type, ptr unsafe.Pointer, len int) {
	if len < 0 {
		panicunsafeslicelen1(sys.GetCallerPC())
	}

	if et.Size_ == 0 {
		if ptr == nil && len > 0 {
			panicunsafeslicenilptr1(sys.GetCallerPC())
		}
	}

	mem, overflow := math.MulUintptr(et.Size_, uintptr(len))
	if overflow || mem > -uintptr(ptr) {
		if ptr == nil {
			panicunsafeslicenilptr1(sys.GetCallerPC())
		}
		panicunsafeslicelen1(sys.GetCallerPC())
	}
}

The mem > -uintptr(ptr) test is the interesting one: it checks that the slice would not extend past the end of the address space, which catches the classic “I multiplied a length by a size and it wrapped around” bug.

checkptr: the runtime’s unsafe sanity checker

Go has a mode that checks the unsafe rules at runtime. It is called checkptr, and it is enabled by -d=checkptr, by -race, and by -msan/-asan:

 go
 
 
// src/cmd/compile/internal/base/flag.go:355
	if Flag.Race || Flag.MSan || Flag.ASan {
		// -race, -msan and -asan imply -d=checkptr for now.
		if Debug.Checkptr == -1 { // if not set explicitly
			Debug.Checkptr = 1
		}
	}

It catches two classes of bug. The first is a conversion that produces a misaligned or out-of-bounds pointer:

 go
 
 
// src/runtime/checkptr.go:9
func checkptrAlignment(p unsafe.Pointer, elem *_type, n uintptr) {
	// nil pointer is always suitably aligned (#47430).
	if p == nil {
		return
	}

	// Check that (*[n]elem)(p) is appropriately aligned.
	// Note that we allow unaligned pointers if the types they point to contain
	// no pointers themselves. See issue 37298.
	// TODO(mdempsky): What about fieldAlign?
	if elem.Pointers() && uintptr(p)&(uintptr(elem.Align_)-1) != 0 {
		throw("checkptr: misaligned pointer conversion")
	}

	// Check that (*[n]elem)(p) doesn't straddle multiple heap objects.
	// TODO(mdempsky): Fix #46938 so we don't need to worry about overflow here.
	if checkptrStraddles(p, n*elem.Size_) {
		throw("checkptr: converted pointer straddles multiple allocations")
	}
}

The second is pointer arithmetic that wanders off into a different allocation:

 go
 
 
// src/runtime/checkptr.go:50
func checkptrArithmetic(p unsafe.Pointer, originals []unsafe.Pointer) {
	if 0 < uintptr(p) && uintptr(p) < minLegalPointer {
		throw("checkptr: pointer arithmetic computed bad pointer value")
	}

	// Check that if the computed pointer p points into a heap
	// object, then one of the original pointers must have pointed
	// into the same object.
	base := checkptrBase(p)
	if base == 0 {
		return
	}

	for _, original := range originals {
		if base == checkptrBase(original) {
			return
		}
	}

	throw("checkptr: pointer arithmetic result points to invalid allocation")
}

The compiler injects the calls. For unsafe.Slice and unsafe.String, the runtime versions do a stricter check that the result does not straddle two heap objects:

 go
 
 
// src/runtime/unsafe.go:83
func unsafeslicecheckptr(et *_type, ptr unsafe.Pointer, len64 int64) {
	unsafeslice64(et, ptr, len64)

	// Check that underlying array doesn't straddle multiple heap objects.
	// unsafeslice64 has already checked for overflow.
	if checkptrStraddles(ptr, uintptr(len64)*et.Size_) {
		throw("checkptr: unsafe.Slice result straddles multiple allocations")
	}
}

And there is an escape hatch for the runtime itself, which cannot afford the checks:

 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).

//go:nocheckptr on a function tells the compiler not to instrument it. It is also implied by //go:nosplit.

//go:linkname: calling things you were not invited to call

//go:linkname tells the compiler to give a symbol a different link-time name, or to look up a symbol under a different name. The syntax is:

 go
 
 
// src/cmd/compile/internal/noder/noder.go:281
	case strings.HasPrefix(text, "go:linkname "), strings.HasPrefix(text, "go:linknamestd "):
		f := strings.Fields(text)
		if !(2 <= len(f) && len(f) <= 3) {
			p.error(syntax.Error{Pos: pos, Msg: fmt.Sprintf("usage: //%s localname [linkname]", f[0])})
			break
		}
		// The second argument is optional. If omitted, we use
		// the default object symbol name for this and
		// linkname only serves to mark this symbol as
		// something that may be referenced via the object
		// symbol name from another package.
		var target string
		if len(f) == 3 {
			target = f[2]
		} else if base.Ctxt.Pkgpath != "" {
			// Use the default object symbol name if the
			// user didn't provide one.
			target = objabi.PathToPrefix(base.Ctxt.Pkgpath) + "." + f[1]
		} else {
			panic("missing pkgpath")
		}
		p.linknames = append(p.linknames, linkname{pos, f[0] == "go:linknamestd", f[1], target})

There are two directions. A push is //go:linkname localname other.name on a declaration in the defining package, which publishes a symbol under a different name. A pull is a bodyless declaration with a //go:linkname in the using package, which imports the symbol by that name.

The runtime uses pushes extensively, to expose internal machinery to packages that need it:

 go
 
 
// src/runtime/linkname.go:9
// used in internal/godebug and syscall
//go:linkname write

// used by cgo
//go:linkname _cgo_panic_internal
//go:linkname cgoAlwaysFalse
//go:linkname cgoUse
//go:linkname cgoKeepAlive
//go:linkname cgoCheckPointer
//go:linkname cgoCheckResult
//go:linkname cgoNoCallback
//go:linkname gobytes
//go:linkname gostringn

// used in plugin
//go:linkname doInit

// used in math/bits
//go:linkname overflowError
//go:linkname divideError

A one-argument //go:linkname foo is a push that keeps the default symbol name; it exists purely to say “this symbol may be referenced by name from another package”.

The hall of shame

Some of these pushes exist only because third-party code broke in and the Go team decided to accommodate rather than break. The runtime marks those symbols explicitly, and the comment format is consistent enough to grep for:

 go
 
 
// src/runtime/map.go:30
// makemap_small implements Go map creation for make(map[k]v) and
// make(map[k]v, hint) when hint is known to be at most abi.MapGroupSlots
// at compile time and the map needs to be allocated on the heap.
//
// makemap_small 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 makemap_small
func makemap_small() *maps.Map {
	return maps.NewEmptyMap()
}

The instruction is explicit: do not remove or change the type signature. The signature is now an ABI contract with half a dozen high-profile libraries, whether those libraries like it or not.

The pattern extends well beyond maps. The runtime maintains a whole file of compatibility shims for the Go 1.24 map iterator rewrite:

 go
 
 
// src/runtime/linkname_shim.go:60
type linknameIter struct {
	// Fields from hiter.
	key unsafe.Pointer
	elem unsafe.Pointer
	typ *abi.MapType

	// The real iterator.
	it *maps.Iter
}

with a comment explaining that the shim’s layout has to match the old hiter struct exactly, or the collector will not track the pointers in it correctly:

Our structure must maintain compatibility with the old structure. This means:

Our structure must be the same size or smaller than hiter. Otherwise we may write outside the caller’s hiter allocation.

Our structure must have the same pointer layout as hiter, so that the GC tracks pointers properly.

The full list of shims in that file includes mapiterinit, mapiternext, reflect_mapiterinit, reflect_mapiternext, reflect_mapiterkey and reflect_mapiterelem — six symbols that exist only so that github.com/bytedance/sonic, github.com/segmentio/encoding, github.com/ugorji/go/codec and others keep working.

The linker enforces who may pull what

Go 1.23 tightened this substantially. The linker now checks every linkname reference against an explicit allowlist:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2438
// A list of blocked linknames. Some linknames are allowed only
// in specific packages. This maps symbol names to allowed packages.
// If a name is not in this map, it is allowed iff the definition
// has a linkname (push).
// If a name is in this map, it is allowed only in listed packages,
// even if it has a linknamed definition.
var blockedLinknames = map[string][]string{
	// fips info
	"go:fipsinfo": {"crypto/internal/fips140/check"},
	// New internal linknames in Go 1.24
	// Pushed from runtime
	"crypto/internal/fips140.fatal": {"crypto/internal/fips140"},
	"crypto/internal/fips140.getIndicator": {"crypto/internal/fips140"},
	"crypto/internal/fips140.setIndicator": {"crypto/internal/fips140"},
	"crypto/internal/sysrand.fatal": {"crypto/internal/sysrand"},
	"crypto/rand.fatal": {"crypto/rand"},
	"internal/runtime/maps.errNilAssign": {"internal/runtime/maps"},
	"internal/runtime/maps.fatal": {"internal/runtime/maps"},
	"internal/runtime/maps.newarray": {"internal/runtime/maps"},
	"internal/runtime/maps.newobject": {"internal/runtime/maps"},
	"internal/runtime/maps.rand": {"internal/runtime/maps"},
	"internal/runtime/maps.typedmemclr": {"internal/runtime/maps"},
	"internal/runtime/maps.typedmemmove": {"internal/runtime/maps"},

and at the bottom, the entry that is allowed from nowhere at all:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2527
	"runtime.addmoduledata": {}, // assembly symbol, disallow all packages
}

The check itself:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2530
// check if a linkname reference to symbol s from refpkg is allowed
func (l *Loader) checkLinkname(refpkg *oReader, name string, s Sym) {
	if l.flags&FlagCheckLinkname == 0 {
		return
	}

	pkg := refpkg.unit.Lib.Pkg
	error := func() {
		log.Fatalf("%s: invalid reference to %s", pkg, name)
	}
	pkgs, ok := blockedLinknames[name]
	if ok {
		for _, p := range pkgs {
			if pkg == p {
				return // pkg is allowed
			}
			// crypto/internal/fips140/vX.Y.Z/... is the frozen version of
			// crypto/internal/fips140/... and is similarly allowed.
			if strings.HasPrefix(pkg, "crypto/internal/fips140/v") {
				parts := strings.Split(pkg, "/")
				parts = append(parts[:3], parts[4:]...)
				pkg := strings.Join(parts, "/")
				if pkg == p {
					return
				}
			}
		}
		error()
	}

The default rule, stated in the comment above the map, is the important one: if a name is not in this map, it is allowed iff the definition has a linkname (push). So the ordinary case still works — a package that pushes a symbol can be pulled by anyone. The map is the exception list, for symbols the runtime wants to keep to itself.

And there is a second tier, for symbols pushed with //go:linknamestd, which are restricted to the standard library:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2599
	if osym.IsLinknameStd() {
		// It is pushed with linknamestd. Allow only pulls from the
		// standard library.
		if refpkg.Std() {
			return
		}
	}
	if osym.IsLinkname() {
		// Allow if the def has a linkname (push).
		return
	}
	error()
}

//go:linknamestd is the newer, stricter directive. A symbol pushed with it can only be pulled from within the standard library. That is how the runtime can expose internal machinery to internal/... packages without opening it to the entire ecosystem.

The whole check is behind -checklinkname, which is on by default for standard-library builds:

 go
 
 
// src/cmd/link/internal/ld/lib.go:531
	if *flagCheckLinkname {
		flags |= loader.FlagCheckLinkname
	}

Dead code elimination and method pruning

Now, the part that connects //go:linkname to binary size. The linker performs a reachability analysis from the entry point and deletes everything that is unreachable. But it cannot simply delete every method of every type, because reflection can find methods at runtime by name.

The linker’s dead code pass describes the problem and the three ways a method can be invoked:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:402
// deadcode marks all reachable symbols.
//
// The basis of the dead code elimination is a flood fill of symbols,
// following their relocations, beginning at *flagEntrySymbol.
//
// This flood fill is wrapped in logic for pruning unused methods.
// All methods are mentioned by relocations on their receiver's *rtype.
// These relocations are specially defined as R_METHODOFF by the compiler
// so we can detect and manipulated them here.
//
// There are three ways a method of a reachable type can be invoked:
//
// 1. direct call
// 2. through a reachable interface type
// 3. reflect.Value.Method (or MethodByName), or reflect.Type.Method
// (or MethodByName)
//
// The first case is handled by the flood fill, a directly called method
// is marked as reachable.
//
// The second case is handled by decomposing all reachable interface
// types into method signatures. Each encountered method is compared
// against the interface method signatures, if it matches it is marked
// as reachable. This is extremely conservative, but easy and correct.
//
// The third case is handled by looking for functions that compiler flagged
// as REFLECTMETHOD. REFLECTMETHOD on a function F means that F does a method
// lookup with reflection, but the compiler was not able to statically determine
// the method name.
//
// All functions that call reflect.Value.Method or reflect.Type.Method are REFLECTMETHODs.
// Functions that call reflect.Value.MethodByName or reflect.Type.MethodByName with
// a non-constant argument are REFLECTMETHODs, too. If we find a REFLECTMETHOD,
// we give up on static analysis, and mark all exported methods of all reachable
// types as reachable.
//
// If the argument to MethodByName is a compile-time constant, the compiler
// emits a relocation with the method name. Matching methods are kept in all
// reachable types.
//
// Any unreached text symbols are removed from ctxt.Textp.

The “REFLECTMETHOD” flag is set by the compiler, in two places. One is when you call MethodByName with a non-constant argument:

 go
 
 
// src/cmd/compile/internal/walk/expr.go:1146
	} else {
		w.curfunc.LSym.Set(obj.AttrReflectMethod, true)
	}

The other is when a function value of reflect.Value.Method is taken:

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

The linker reads that flag:

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

and uses it to decide whether to give up on pruning:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:460
		rem := d.markableMethods[:0]
		for _, m := range d.markableMethods {
			if (d.reflectSeen && (m.isExported() || d.dynlink)) || d.ifaceMethod[m.m] || d.genericIfaceMethod[m.m.name] {
				d.markMethod(m)
			} else {
				rem = append(rem, m)
			}
		}

Read that condition carefully. If any function in the program does a non-constant MethodByName, then every exported method of every reachable type is kept. One reflect-by-name call anywhere in your dependency tree can cost you a substantial fraction of your binary size. That is a real and frequently surprising effect.

There is a mitigation. If the argument to MethodByName is a compile-time constant, the compiler emits a relocation naming the method, and the linker can keep only the matching methods. That is the R_USENAMEDMETHOD relocation visible in the same compiler file.

Trade-offs

What the escape hatches buy you:

Zero-copy reinterpretation. unsafe.Slice and unsafe.String let you build a view over memory you already have without copying it.
Access to runtime internals. The standard library’s own packages use //go:linkname to share machinery that is not part of the public API.
Interoperability. Talking to C, to the kernel, or to a memory-mapped device requires unsafe.Pointer somewhere.
A working reflect. reflect itself is a large pile of unsafe.

What they cost:

The compiler stops helping. No bounds checks, no nil checks, no escape analysis guarantees you can rely on.
The collector stops helping. A uintptr in a variable is not a reference. The object can move, or be collected, while you hold it.
You break the compatibility promise. The unsafe package’s own docs say so: “Packages that import unsafe may be non-portable and are not protected by the Go 1 compatibility guidelines.”
You break the linker. A linkname pull from a package that is not allowed is a hard log.Fatalf at link time, not a compile error.
You opt out of method pruning. One MethodByName with a non-constant argument keeps every exported method of every reachable type.

Caveats

unsafe code is not “mostly safe”. The rules in the package doc are precise, and the moment you deviate from them the failure is silent corruption rather than a panic.

checkptr is not on by default. -race turns it on, but a normal production build does not check anything. If your code depends on unsafe being correct, test it with -race or -d=checkptr=1.

//go:nocheckptr silently disables the checks for that function. It is used sparingly in the runtime and it is exactly the sort of thing you should not reach for.

Linkname pulls are checked at link time, not compile time. The compiler will happily compile //go:linkname foo runtime.someInternalThing and you will find out when the linker says invalid reference to runtime.someInternalThing.

The allowlist changes. The blockedLinknames map is updated every release, with sections marked “New internal linknames in Go 1.24”, “Go 1.25”, “Go 1.26”. A linkname that works today can stop working.

//go:linknamestd is the one to prefer if you are writing a package that legitimately needs a runtime internal. It restricts the pull to the standard library, so you are not opening your package’s internals to the world.

Do not linkname into the runtime from a third-party package. It works until it does not. The Go team’s position is visible in the runtime’s own comments: “Do not remove or change the type signature. See go.dev/issue/67401.” That is a promise made under duress.

Wrapping up

The one thing to remember: unsafe.Pointer is where the type system ends and //go:linkname is where the package boundary ends. Both are deliberate, documented holes, and both are policed by machinery that has got much stricter over the last few releases.

The part people get wrong: unsafe.Pointer converted to uintptr and stored in a variable is no longer a pointer. The garbage collector does not update it and does not keep the object alive. The conversion has to happen inside a single expression.

What to go do about it: turn on -race in your test suite. It implies -d=checkptr, it catches misaligned and straddling unsafe conversions, and it costs you nothing in production. If you have a MethodByName with a non-constant argument anywhere in your dependency tree, replace it with a constant one — you may be keeping a lot of dead methods alive.

unique.Make and the Weak Pointer Map: Canonicalizing Strings Without Leaking

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

TL;DR: unique.Make("hello") does not put your string in a map that lives forever. It hashes the value into a lock-free 16-way hash trie whose leaves hold a weak.Pointer to the canonical copy, and registers a cleanup callback. When the last Handle goes away the entry is deleted.

Interning strings is one of those things every language eventually grows. The idea is simple: if a program has ten thousand copies of the string "application/json", you want one copy in memory and ten thousand pointers to it. Comparison gets cheaper, memory gets smaller, and the GC has less work to do.

The problem is that a naive interner is a memory leak with extra steps. A global map[string]string never shrinks. Entries live forever because the map is a root. You can add finalizers, but finalizers are asynchronous, they resurrect the object, and they have never been a good fit for “drop this from the table”.

Go’s unique package (added in Go 1.23) takes a different route. It leans on two pieces of modern runtime machinery: weak pointers (weak.Pointer, Go 1.24) and cleanups (runtime.AddCleanup, Go 1.24). The result is an interner that is both fast and leak-free.

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

The API is three methods

 go
 
 
// src/unique/handle.go:15
// Handle is a globally unique identity for some value of type T.
//
// Two handles compare equal exactly if the two values used to create the handles
// would have also compared equal. The comparison of two handles is trivial and
// typically much more efficient than comparing the values used to create them.
type Handle[T comparable] struct {
	value *T
}

// Value returns a shallow copy of the T value that produced the Handle.
// Value is safe for concurrent use by multiple goroutines.
func (h Handle[T]) Value() T {
	return *h.value
}

That is the entire public surface of the unique package: Handle[T], Handle.Value(), and Make. The whole trick is in Make:

 go
 
 
// src/unique/handle.go:30
// Make returns a globally unique handle for a value of type T. Handles
// are equal if and only if the values used to produce them are equal.
// Make is safe for concurrent use by multiple goroutines.
func Make[T comparable](value T) Handle[T] {
	// Find the map for type T.
	typ := abi.TypeFor[T]()
	if typ.Size() == 0 {
		return Handle[T]{(*T)(unsafe.Pointer(&zero))}
	}
	ma, ok := uniqueMaps.Load(typ)
	if !ok {
		m := &uniqueMap[T]{canonMap: newCanonMap[T](), cloneSeq: makeCloneSeq(typ)}
		ma, _ = uniqueMaps.LoadOrStore(typ, m)
	}
	m := ma.(*uniqueMap[T])

	// Find the value in the map.
	ptr := m.Load(value)
	if ptr == nil {
		// Insert a new value into the map.
		ptr = m.LoadOrStore(clone(value, &m.cloneSeq))
	}
	return Handle[T]{ptr}
}

Read that bottom half carefully. m.Load(value) looks the value up. If it is not there, we clone it and insert it. If it is there, we throw the clone away and return the pointer that was already in the table. That is the whole canonicalization contract: the second unique.Make("hello") returns a handle whose Value() points at the same bytes as the first one.

Note also typ.Size() == 0: the empty struct. Every empty struct is equal to every other empty struct, so there is exactly one canonical one, and it is a pointer to a package-level zero uintptr rather than a heap allocation.

Two levels of dispatch

uniqueMaps is an internal/sync.HashTrieMap keyed by *abi.Type:

 go
 
 
// src/unique/handle.go:55
// uniqueMaps is an index of type-specific concurrent maps used for unique.Make.
//
// The two-level map might seem odd at first since the HashTrieMap could have "any"
// as its key type, but the issue is escape analysis. We do not want to force lookups
// to escape the argument, and using a type-specific map allows us to avoid that where
// possible (for example, for strings and plain-ol'-data structs). We also get the
// benefit of not cramming every different type into a single map, but that's certainly
// not enough to outweigh the cost of two map lookups. What is worth it though, is saving
// on those allocations.
var uniqueMaps isync.HashTrieMap[*abi.Type, any] // any is always a *uniqueMap[T].

The comment explains the odd-looking indirection: one map per type means the compiler can generate a type-specialised map implementation for each T, so hashing a string uses the runtime’s string hasher directly instead of hashing an any box. The cost is one extra lookup in uniqueMaps; the benefit is that the per-value lookup never has to box.

The canonical map is a hash trie, not a Go map

Here is where the design gets interesting. You might expect unique to use an ordinary map[T]*T with weak keys. It does not — it rolls its own trie:

 go
 
 
// src/unique/canonmap.go:17
// canonMap is a map of T -> *T. The map controls the creation
// of a canonical *T, and elements of the map are automatically
// deleted when the canonical *T is no longer referenced.
type canonMap[T comparable] struct {
	root atomic.Pointer[indirect[T]]
	hash func(unsafe.Pointer, uintptr) uintptr
	seed uintptr
}

func newCanonMap[T comparable]() *canonMap[T] {
	cm := new(canonMap[T])
	cm.root.Store(newIndirectNode[T](nil))

	var m map[T]struct{}
	mapType := abi.TypeOf(m).MapType()
	cm.hash = mapType.Hasher
	cm.seed = uintptr(runtime_rand())
	return cm
}

Three things to notice.

First, the hasher is borrowed from the runtime’s map implementation for type T. mapType.Hasher is the exact function the runtime uses to hash map[T] keys, so unique gets the fast, assembly-optimised string hasher for free. The seed is random per map (runtime.rand, pulled in with a //go:linkname so the package does not have to depend on math/rand/v2), which is the same defence against hash-flooding that Go maps have.

Second, abi.NoEscape is used when hashing, so the key does not escape to the heap just because we looked at it.

Third, and most importantly, this is not a map[T]*T. It is a hand-rolled hash trie, because the entries need to be individually removable when the value they point to dies. A Go map cannot do that; you cannot delete an entry whose key you can no longer compare against.

The trie itself is a 16-way radix tree over the bits of the hash:

 go
 
 
// src/unique/canonmap.go:275
const (
	// 16 children. This seems to be the sweet spot for
	// load performance: any smaller and we lose out on
	// 50% or more in CPU performance. Any larger and the
	// returns are minuscule (~1% improvement for 32 children).
	nChildrenLog2 = 4
	nChildren = 1 << nChildrenLog2
	nChildrenMask = nChildren - 1
)

// indirect is an internal node in the hash-trie.
type indirect[T comparable] struct {
	node[T]
	dead atomic.Bool
	parent *indirect[T]
	mu sync.Mutex // Protects mutation to children and any children that are entry nodes.
	children [nChildren]atomic.Pointer[node[T]]
}

Lookups are lock-free — just atomic loads down the trie:

 go
 
 
// src/unique/canonmap.go:37
func (m *canonMap[T]) Load(key T) *T {
	hash := m.hash(abi.NoEscape(unsafe.Pointer(&key)), m.seed)

	i := m.root.Load()
	hashShift := 8 * goarch.PtrSize
	for hashShift != 0 {
		hashShift -= nChildrenLog2

		n := i.children[(hash>>hashShift)&nChildrenMask].Load()
		if n == nil {
			return nil
		}
		if n.isEntry {
			v, _ := n.entry().lookup(key)
			return v
		}
		i = n.indirect()
	}
	panic("unique.canonMap: ran out of hash bits while iterating")
}

Each level consumes four bits of the hash and picks one of sixteen children. A nil child means the key is definitely absent. A leaf node is an entry.

The leaf holds a weak pointer

Here is the heart of the design:

 go
 
 
// src/unique/canonmap.go:307
// entry is a leaf node in the hash-trie.
type entry[T comparable] struct {
	node[T]
	overflow atomic.Pointer[entry[T]] // Overflow for hash collisions.
	key weak.Pointer[T]
	hash uintptr
}

func newEntryNode[T comparable](key T, hash uintptr) (*entry[T], *T, weak.Pointer[T]) {
	k := new(T)
	*k = key
	wp := weak.Make(k)
	return &entry[T]{
		node: node[T]{isEntry: true},
		key: wp,
		hash: hash,
	}, k, wp
}

The entry stores the key weakly. It does not hold a strong reference to the canonical *T. That is the entire trick: the trie is not a GC root for the values it indexes, so the values can die, and when they do, the entries must be removed.

The overflow chain handles full hash collisions — two different values with the same 64-bit hash live in a linked list hanging off the same leaf.

Lookup walks that chain, and a dead entry (one whose weak pointer has been cleared) is simply skipped:

 go
 
 
// src/unique/canonmap.go:326
// lookup finds the entry in the overflow chain that has the provided key.
//
// Returns the key's canonical pointer and the weak pointer for that canonical pointer.
func (e *entry[T]) lookup(key T) (*T, weak.Pointer[T]) {
	for e != nil {
		s := e.key.Value()
		if s != nil && *s == key {
			return s, e.key
		}
		e = e.overflow.Load()
	}
	return nil, weak.Pointer[T]{}
}

s := e.key.Value() returns nil if the canonical value has been collected. That is the “this entry is dead” signal, and it is checked on every single lookup.

Insert, prune, and register the cleanup

Insertion is where the lock comes in. The writer walks the trie without a lock, finds a candidate slot, takes the lock on that node, double-checks, and then either replaces the leaf or expands it into a subtree:

 go
 
 
// src/unique/canonmap.go:121
	newEntry, canon, wp := newEntryNode(key, hash)
	// Prune dead pointers. This is to avoid O(n) lookups when we store the exact same
	// value in the set but the cleanup hasn't run yet because it got delayed for some
	// reason.
	oldEntry = oldEntry.prune()
	if oldEntry == nil {
		// Easy case: create a new entry and store it.
		slot.Store(&newEntry.node)
	} else {
		// We possibly need to expand the entry already there into one or more new nodes.
		//
		// Publish the node last, which will make both oldEntry and newEntry visible. We
		// don't want readers to be able to observe that oldEntry isn't in the tree.
		slot.Store(m.expand(oldEntry, newEntry, hash, hashShift, i))
	}
	runtime.AddCleanup(canon, func(_ struct{}) {
		m.cleanup(hash, wp)
	}, struct{}{})
	return canon
}

Two things stand out.

The prune. Before inserting, the code walks the overflow chain and drops every entry whose weak pointer is already dead. The comment explains why: without pruning, inserting a value that was recently interned and recently dropped would have to walk past a dead entry every time. Pruning keeps the chain short.

The cleanup. runtime.AddCleanup(canon, ...) registers a callback on the canonical *T. The runtime guarantees the callback runs in a separate goroutine some time after canon becomes unreachable. The closure captures the map, the hash, and the weak pointer — and crucially not canon itself, because a cleanup that referenced its own object would never run.

So the lifecycle is:

 text
 
 
 unique.Make("x") last Handle dropped
 | |
 v v
 canonical *T <--- strong ref --- Handle
 | |
 | (map holds only a weak ref) GC frees it
 v |
 weak.Pointer[T].Value() == nil |
 | |
 +--> runtime cleanup fires ----+
 |
 v
 m.cleanup(hash, wp)
 |
 v
 trie entry deleted

Deleting the entry

The cleanup function walks the trie by hash, finds the leaf, verifies the weak pointer matches, and removes the entry — pruning empty interior nodes on the way up:

 go
 
 
// src/unique/canonmap.go:176
// cleanup deletes the entry corresponding to wp in the canon map, if it's
// still in the map. wp must have a Value method that returns nil by the
// time this function is called. hash must be the hash of the value that
// wp once pointed to (that is, the hash of *wp.Value()).
func (m *canonMap[T]) cleanup(hash uintptr, wp weak.Pointer[T]) {
	var i *indirect[T]
	var hashShift uint
	var slot *atomic.Pointer[node[T]]
	var n *node[T]
	for {
		// Find wp in the map by following hash.
		i = m.root.Load()
		hashShift = 8 * goarch.PtrSize
		haveEntry := false
		for hashShift != 0 {
			hashShift -= nChildrenLog2

			slot = &i.children[(hash>>hashShift)&nChildrenMask]
			n = slot.Load()
			if n == nil {
				// We found a nil slot, already deleted.
				return
			}
			if n.isEntry {
				if !n.entry().hasWeakPointer(wp) {
					// The weak pointer was already pruned.
					return
				}
				haveEntry = true
				break
			}
			i = n.indirect()
		}

The rest of the function takes the node’s lock, prunes the leaf, stores nil into the slot if the chain is now empty, and then walks up the tree deleting interior nodes that have become empty — locking each parent in turn, because unlinking a child requires the parent’s lock.

This is the part that makes the design safe under concurrency. Two goroutines can intern the same value at the same time; the second one finds the entry via lookup and returns the first one’s pointer. Two goroutines can drop handles at the same time; the cleanup runs once (the weak pointer match in hasWeakPointer guards against a double-delete), and if the entry was already pruned by somebody else, it returns harmlessly.

The clone trick

There is one more subtlety, and it is the one that surprises people. When unique interns a value, it does not keep the caller’s copy. It makes its own copy first:

 go
 
 
// src/unique/clone.go:13
// clone makes a copy of value, and may update string values found in value
// with a cloned version of those strings. The purpose of explicitly cloning
// strings is to avoid accidentally giving a large string a long lifetime.
//
// Note that this will clone strings in structs and arrays found in value,
// and will clone value if it itself is a string. It will not, however, clone
// strings if value is of interface or slice type (that is, found via an
// indirection).
func clone[T comparable](value T, seq *cloneSeq) T {
	for _, offset := range seq.stringOffsets {
		ps := (*string)(unsafe.Pointer(uintptr(unsafe.Pointer(&value)) + offset))
		*ps = stringslite.Clone(*ps)
	}
	return abi.EscapeToResultNonString(value)
}

Why? Consider unique.Make(bigStruct). The struct contains a string field holding a 10 MB buffer. If the canonical copy pointed at the caller’s bytes, then interning the struct would pin 10 MB for as long as any handle to the struct existed — even if the original owner had long since dropped its reference. Cloning the string first means the canonical value owns its own bytes, and the original 10 MB can be freed independently.

cloneSeq is precomputed per type so that the clone is a fixed sequence of pointer writes rather than a reflective walk:

 go
 
 
// src/unique/clone.go:29
// singleStringClone describes how to clone a single string.
var singleStringClone = cloneSeq{stringOffsets: []uintptr{0}}

// cloneSeq describes how to clone a value of a particular type.
type cloneSeq struct {
	stringOffsets []uintptr
}

// makeCloneSeq creates a cloneSeq for a type.
func makeCloneSeq(typ *abi.Type) cloneSeq {
	if typ == nil {
		return cloneSeq{}
	}
	if typ.Kind() == abi.String {
		return singleStringClone
	}
	var seq cloneSeq
	switch typ.Kind() {
	case abi.Struct:
		buildStructCloneSeq(typ, &seq, 0)
	case abi.Array:
		buildArrayCloneSeq(typ, &seq, 0)
	}
	return seq
}

And the crucial part, back in Make: the clone only happens on the miss path. If the value is already in the table, m.Load(value) returns the existing canonical pointer and clone is never called. So the second unique.Make("hello") allocates nothing and copies nothing — it hands back the same bytes.

What `Handle.Value()` guarantees

Handle[T] holds a plain *T. Two handles to the same value hold the same pointer. Value() dereferences it and returns a copy of the T.

For a string that means the returned string header points at the canonical bytes. Two handles’ Value() results compare equal, and their underlying byte slices are literally the same allocation. That is the memory saving.

The handle itself is a strong reference, and that is what keeps the canonical value alive. As long as you hold a Handle, the value cannot be collected. When you drop the last handle, the value becomes collectable, the cleanup fires, and the table forgets it.

Trade-offs

What you get:

Deduplication. One copy of the bytes per distinct value, no matter how many handles point at it.
Fast comparison. Handle comparison is a pointer compare.
No leak. The table shrinks when the values do.
Lock-free reads. The fast path is a handful of atomic loads and a hash.

What you pay:

A hash on every Make. You are paying a hash plus a trie walk to save memory you might not have been going to use twice.
A cleanup callback per interned value. Every canonical value gets a runtime.AddCleanup registration, which is a special record on the span plus a queue entry when it fires.
Cleanup is asynchronous. The entry is removed some time after the value dies, not at the instant it dies. Between those two moments, the table still holds a dead entry, which is why the prune-on-insert logic exists.
Cloning costs a copy. The first Make of a string copies its bytes. If you were going to use the string only once, that copy is pure overhead.
The value must be comparable. unique.Make is not a general-purpose memoiser.

Caveats

unique is not a string cache; it is a value canonicaliser. The point is that the same value produces the same pointer, not that lookups are fast. If you build the key of a map out of a struct and never compare the handles, you have paid for nothing.

The cleanup is not guaranteed to run promptly. It runs “some time after” the object is unreachable, in a separate goroutine, and cleanups are not guaranteed to run at all before program exit. If you drop the last handle and immediately intern the same value again, you may get a new canonical copy, because the old entry has not been cleaned up yet — or you may get the old one back. Both are legal; the value is still canonical at any given moment.

Zero-sized types get a shared sentinel. unique.Make(struct{}{}) returns a handle to a package-level zero uintptr, not to a heap object.

Handles are not comparable across types. Handle[string] and Handle[[]byte] are different types and do not interoperate.

The weak pointer semantics bite. weak.Pointer.Value() may return nil at any time after the target becomes unreachable, and the runtime may batch tiny pointer-free objects together, in which case a weak pointer may never become nil. unique handles this correctly, but code that reads weak.Pointer directly needs runtime.KeepAlive discipline.

Wrapping up

The one thing to remember: the canonical map’s leaves hold weak pointers, and the deletion of an entry is driven by a runtime.AddCleanup callback on the canonical value. The map is not a root; it is a participant in the same lifetime dance as everything else.

The part people get wrong: unique.Make clones your string the first time it interns it, and reuses the canonical bytes only on the second and subsequent calls. Interning a value you only use once is a pure loss — you pay a copy, a hash, and a trie insert for nothing.

What to go do about it: measure your hit rate before reaching for unique. If your program interns the same few hundred strings repeatedly (a very common shape for parsers, routers, and protocol decoders), the dedup is real and the weak-pointer machinery pays for itself. If it interns values that are mostly unique, use a plain map and let the GC do its job.

sync.Pool: Per-P Caches, a Victim Generation and Why Items Vanish

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

TL;DR: sync.Pool is not a pool of objects you can count on. It is one cache per P, each holding a private slot plus a lock-free chain of ring buffers, and every garbage collection moves the whole thing into a “victim” cache and empties it. An object therefore survives at most two GC cycles, and if nobody asks for it in between, it is gone.

sync.Pool has a reputation for being one of the more confusing pieces of the standard library. The documentation is famously unhelpful (“A Pool is a set of temporary objects that may be individually saved and retrieved”), and the behaviour people trip over is that objects disappear.

Here is what it actually is, from the Go 1.28 tree (commit c0be4674865b).

The contract first

Read this before reading the code, because every design decision follows from it:

 go
 
 
// src/sync/pool.go:15
// A Pool is a set of temporary objects that may be individually saved and
// retrieved.
//
// Any item stored in the Pool may be removed automatically at any time without
// notification. If the Pool holds the only reference when this happens, the
// item might be deallocated.
//
// A Pool is safe for use by multiple goroutines simultaneously.
//
// Pool's purpose is to cache allocated but unused items for later reuse,
// relieving pressure on the garbage collector. That is, it makes it easy to
// build efficient, thread-safe free lists. However, it is not suitable for all
// free lists.
//
// An appropriate use of a Pool is to manage a group of temporary items
// silently shared among and potentially reused by concurrent independent
// clients of a package. Pool provides a way to amortize allocation overhead
// across many clients.
//
// An example of good use of a Pool is in the fmt package, which maintains a
// dynamically-sized store of temporary output buffers. The store scales under
// load (when many goroutines are actively printing) and shrinks when
// quiescent.
//
// On the other hand, a free list maintained as part of a short-lived object is
// not a suitable use for a Pool, since the overhead does not amortize well in
// that scenario. It is more efficient to have such objects implement their own
// free list.
//
// A Pool must not be copied after first use.

“Any item stored in the Pool may be removed automatically at any time without notification.” That is the whole promise. sync.Pool is a best-effort cache, not a container. If your code needs the object to still be there, it needs to own it.

The struct

 go
 
 
// src/sync/pool.go:52
type Pool struct {
	noCopy noCopy

	local unsafe.Pointer // local fixed-size per-P pool, actual type is [P]poolLocal
	localSize uintptr // size of the local array

	victim unsafe.Pointer // local from previous cycle
	victimSize uintptr // size of victims array

	// New optionally specifies a function to generate
	// a value when Get would otherwise return nil.
	// It may not be changed concurrently with calls to Get.
	New func() any
}

Two generations of per-P arrays: local is the current one, victim is the previous one. local is an unsafe.Pointer rather than a slice because the array is reallocated whenever GOMAXPROCS changes, and the whole design avoids a pointer-to-slice-header indirection on the hot path.

The per-P entry is this:

 go
 
 
// src/sync/pool.go:67
// Local per-P Pool appendix.
type poolLocalInternal struct {
	private any // Can be used only by the respective P.
	shared poolChain // Local P can pushHead/popHead; any P can popTail.
}

type poolLocal struct {
	poolLocalInternal

	// Prevents false sharing on widespread platforms with
	// 128 mod (cache line size) = 0 .
	pad [128 - unsafe.Sizeof(poolLocalInternal{})%128]byte
}

Two storage slots per P:

private — a single any that only this P touches. No atomics, no locks, no CAS. This is the fast path: Put into an empty private is one pointer store.
shared — a poolChain, a lock-free structure that this P pushes to and any P may steal from.

And the pad field: each poolLocal is padded out to a multiple of 128 bytes so that two different P’s shards never share a cache line. Without it, every P would false-share its private slot with its neighbour’s and the cache line would ping-pong between cores.

 text
 
 
 Pool.local -> [P]poolLocal

 P0: [private | shared(chain) | pad .... 128 bytes]
 P1: [private | shared(chain) | pad .... 128 bytes]
 P2: [private | shared(chain) | pad .... 128 bytes]
 ^ each on its own cache line

`Put` and `Get`

Both are short, and both are built around pinning the goroutine to its P:

 go
 
 
// src/sync/pool.go:100
func (p *Pool) Put(x any) {
	if x == nil {
		return
	}
	if race.Enabled {
		if runtime_randn(4) == 0 {
			// Randomly drop x on floor.
			return
		}
		race.ReleaseMerge(poolRaceAddr(x))
		race.Disable()
	}
	l, _ := p.pin()
	if l.private == nil {
		l.private = x
	} else {
		l.shared.pushHead(x)
	}
	runtime_procUnpin()
	if race.Enabled {
		race.Enable()
	}
}

Note the very first line: Put(nil) is a no-op, because nil is the sentinel the pool uses for “empty slot”.

The logic is a one-line heuristic: if the private slot is free, use it; otherwise push onto the shared chain. The private slot exists because the overwhelmingly common case is “one goroutine puts, the same goroutine gets”, and that needs no synchronisation at all.

Get is the mirror image:

 go
 
 
// src/sync/pool.go:132
func (p *Pool) Get() any {
	if race.Enabled {
		race.Disable()
	}
	l, pid := p.pin()
	x := l.private
	if x != nil {
		l.private = nil
	} else {
		// Try to pop the head of the local shard. We prefer
		// the head over the tail for temporal locality of
		// reuse.
		x, _ = l.shared.popHead()
		if x == nil {
			x = p.getSlow(pid)
		}
	}
	runtime_procUnpin()
	if race.Enabled {
		race.Enable()
		if x != nil {
			race.Acquire(poolRaceAddr(x))
		}
	}
	if x == nil && p.New != nil {
		x = p.New()
	}
	return x
}

The order of attempts is: private slot, then the head of the local shared chain, then the slow path. The head is preferred over the tail “for temporal locality of reuse” — objects put recently are likely to be put again soon, so they stay hot in cache.

And the New fallback at the end: if the pool came up empty, New is called to manufacture a fresh object. That is how sync.Pool is normally used:

 go
 
 
var bufPool = sync.Pool{
	New: func() any { return new(bytes.Buffer) },
}

New is also the escape hatch that makes Pool usable without pre-warming: the first few calls allocate, and later calls reuse.

Pinning: why items do not migrate between Ps

The pin method is the mechanism that makes the per-P design safe:

 go
 
 
// src/sync/pool.go:201
// pin pins the current goroutine to P, disables preemption and
// returns poolLocal pool for the P and the P's id.
// Caller must call runtime_procUnpin() when done with the pool.
func (p *Pool) pin() (*poolLocal, int) {
	// Check whether p is nil to get a panic.
	// Otherwise the nil dereference happens while the m is pinned,
	// causing a fatal error rather than a panic.
	if p == nil {
		panic("nil Pool")
	}

	pid := runtime_procPin()
	// In pinSlow we store to local and then to localSize, here we load in opposite order.
	// Since we've disabled preemption, GC cannot happen in between.
	// Thus here we must observe local at least as large localSize.
	// We can observe a newer/larger local, it is fine (we must observe its zero-initialized-ness).
	s := rtatomic.LoadAcquintptr(&p.localSize) // load-acquire
	l := p.local // load-consume
	if uintptr(pid) < s {
		return indexLocal(l, pid), pid
	}
	return p.pinSlow()
}

runtime_procPin is astonishingly simple:

 go
 
 
// src/runtime/proc.go:7961
func procPin() int {
	gp := getg()
	mp := gp.m

	mp.locks++
	return int(mp.p.ptr().id)
}

It bumps m.locks, which disables preemption for this goroutine, and returns the id of the P the goroutine is currently running on. Because preemption is disabled, the goroutine cannot be moved to another P between the pin and the unpin, so it is guaranteed that l.private really is private to it.

And procUnpin:

 go
 
 
// src/runtime/proc.go:7981
func procUnpin() {
	gp := getg()
	gp.m.locks--
}

That is the entire pinning mechanism: increment a counter to forbid preemption, use the current P’s id as an index, decrement the counter afterwards. No locks, no atomics.

If the pool’s per-P array has not been allocated yet (or GOMAXPROCS grew since the last allocation), pinSlow handles it under a mutex:

 go
 
 
// src/sync/pool.go:225
func (p *Pool) pinSlow() (*poolLocal, int) {
	// Retry under the mutex.
	// Can not lock the mutex while pinned.
	runtime_procUnpin()
	allPoolsMu.Lock()
	defer allPoolsMu.Unlock()
	pid := runtime_procPin()
	// poolCleanup won't be called while we are pinned.
	s := p.localSize
	l := p.local
	if uintptr(pid) < s {
		return indexLocal(l, pid), pid
	}
	if p.local == nil {
		allPools = append(allPools, p)
	}
	// If GOMAXPROCS changes between GCs, we re-allocate the array and lose the old one.
	size := runtime.GOMAXPROCS(0)
	local := make([]poolLocal, size)
	atomic.StorePointer(&p.local, unsafe.Pointer(&local[0])) // store-release
	rtatomic.StoreReluintptr(&p.localSize, uintptr(size)) // store-release
	return &local[pid], pid
}

Note the comment: “If GOMAXPROCS changes between GCs, we re-allocate the array and lose the old one.” Changing GOMAXPROCS at runtime therefore discards the pool’s contents. So does calling runtime.GC() twice.

The lock-free chain

The shared slot is a poolChain:

 go
 
 
// src/sync/poolqueue.go:194
type poolChain struct {
	// head is the poolDequeue to push to. This is only accessed
	// by the producer, so doesn't need to be synchronized.
	head *poolChainElt

	// tail is the poolDequeue to popTail from. This is accessed
	// by consumers, so reads and writes must be atomic.
	tail atomic.Pointer[poolChainElt]
}

type poolChainElt struct {
	poolDequeue

	// next and prev link to the adjacent poolChainElts in this
	// poolChain.
	//
	// next is written atomically by the producer and read
	// atomically by the consumer. It only transitions from nil to
	// non-nil.
	//
	// prev is written atomically by the consumer and read
	// atomically by the producer. It only transitions from
	// non-nil to nil.
	next, prev atomic.Pointer[poolChainElt]
}

It is a doubly-linked list of poolDequeue rings. The producer (the owning P) pushes onto the head element; consumers pop from the tail element. When a ring fills up, a new, twice-as-large ring is appended; when a ring empties, it is dropped from the chain.

 go
 
 
// src/sync/poolqueue.go:220
func (c *poolChain) pushHead(val any) {
	d := c.head
	if d == nil {
		// Initialize the chain.
		const initSize = 8 // Must be a power of 2
		d = new(poolChainElt)
		d.vals = make([]eface, initSize)
		c.head = d
		c.tail.Store(d)
	}

	if d.pushHead(val) {
		return
	}

	// The current dequeue is full. Allocate a new one of twice
	// the size.
	newSize := len(d.vals) * 2
	if newSize >= dequeueLimit {
		// Can't make it any bigger.
		newSize = dequeueLimit
	}

	d2 := &poolChainElt{}
	d2.prev.Store(d)
	d2.vals = make([]eface, newSize)
	c.head = d2
	d.next.Store(d2)
	d2.pushHead(val)
}

So the chain grows 8, 16, 32, 64 … slots. The producer only ever pushes to the newest ring, and consumers pop from the oldest.

 text
 
 
 poolChain
 head (producer) tail (consumers)
 | |
 v v
 +----------+ next +----------+ +----------+
 | 64 slots | -------> | 32 slots | | 8 slots |
 +----------+ +----------+ +----------+
 ^
 popHead here ^
 popTail here

The head/tail trick

The core data structure is poolDequeue, a single-producer, multi-consumer queue with no locks and one atomic word of state:

 go
 
 
// src/sync/poolqueue.go:19
type poolDequeue struct {
	// headTail packs together a 32-bit head index and a 32-bit
	// tail index. Both are indexes into vals modulo len(vals)-1.
	//
	// tail = index of oldest data in queue
	// head = index of next slot to fill
	//
	// Slots in the range [tail, head) are owned by consumers.
	// A consumer continues to own a slot outside this range until
	// it nils the slot, at which point ownership passes to the
	// producer.
	//
	// The head index is stored in the most-significant bits so
	// that we can atomically add to it and the overflow is
	// harmless.
	headTail atomic.Uint64

	// vals is a ring buffer of interface{} values stored in this
	// dequeue. The size of this must be a power of 2.
	//
	// vals[i].typ is nil if the slot is empty and non-nil
	// otherwise. A slot is still in use until *both* the tail
	// index has moved beyond it and typ has been set to nil. This
	// is set to nil atomically by the consumer and read
	// atomically by the producer.
	vals []eface
}

One 64-bit word holds both indices: head in the top 32 bits, tail in the bottom 32. Packing them means a single atomic operation can move either one, and head is in the high bits specifically so that incrementing it (which is += 1 << 32) cannot overflow into tail.

The ownership protocol is the clever part:

Slots in [tail, head) are owned by consumers.
A consumer that pops a slot still owns it until it nils the slot out.
Only then does ownership pass back to the producer, which may reuse the slot.

The producer therefore cannot overwrite a slot that a consumer is still reading. That is what makes the queue lock-free but safe.

Pushing

 go
 
 
// src/sync/poolqueue.go:80
func (d *poolDequeue) pushHead(val any) bool {
	ptrs := d.headTail.Load()
	head, tail := d.unpack(ptrs)
	if (tail+uint32(len(d.vals)))&(1<<dequeueBits-1) == head {
		// Queue is full.
		return false
	}
	slot := &d.vals[head&uint32(len(d.vals)-1)]

	// Check if the head slot has been released by popTail.
	typ := atomic.LoadPointer(&slot.typ)
	if typ != nil {
		// Another goroutine is still cleaning up the tail, so
		// the queue is actually still full.
		return false
	}

	// The head slot is free, so we own it.
	if val == nil {
		val = dequeueNil(nil)
	}
	*(*any)(unsafe.Pointer(slot)) = val

	// Increment head. This passes ownership of slot to popTail
	// and acts as a store barrier for writing the slot.
	d.headTail.Add(1 << dequeueBits)
	return true
}

Two fullness checks: the index arithmetic says “full”, and the typ check says “the consumer has not finished with the tail slot yet, so it is really full”. The typ check is the extra step that the plain ring buffer does not need, because the producer and consumer here are different goroutines.

Note the dequeueNil sentinel: nil is used to mean “empty slot”, so nil values need a different representation:

 go
 
 
// src/sync/poolqueue.go:60
// dequeueNil is used in poolDequeue to represent interface{}(nil).
// Since we use nil to represent empty slots, we need a sentinel value
// to represent nil.
type dequeueNil *struct{}

Popping from the head

Only the owning P does this, so it does not need a CAS loop with a racing consumer… but it still uses one, because the tail can move underneath it:

 go
 
 
// src/sync/poolqueue.go:112
func (d *poolDequeue) popHead() (any, bool) {
	var slot *eface
	for {
		ptrs := d.headTail.Load()
		head, tail := d.unpack(ptrs)
		if tail == head {
			// Queue is empty.
			return nil, false
		}

		// Confirm tail and decrement head. We do this before
		// reading the value to take back ownership of this
		// slot.
		head--
		ptrs2 := d.pack(head, tail)
		if d.headTail.CompareAndSwap(ptrs, ptrs2) {
			// We successfully took back slot.
			slot = &d.vals[head&uint32(len(d.vals)-1)]
			break
		}
	}

	val := *(*any)(unsafe.Pointer(slot))
	if val == dequeueNil(nil) {
		val = nil
	}
	// Zero the slot. Unlike popTail, this isn't racing with
	// pushHead, so we don't need to be careful here.
	*slot = eface{}
	return val, true
}

The comment “We do this before reading the value to take back ownership of this slot” is the ordering that matters: the CAS decrements head first, which claims the slot, and only then is the value read. A concurrent pushHead cannot touch the slot until head has moved, and it cannot move head until our CAS succeeds.

Popping from the tail

Any P may do this — this is the steal path:

 go
 
 
// src/sync/poolqueue.go:147
func (d *poolDequeue) popTail() (any, bool) {
	var slot *eface
	for {
		ptrs := d.headTail.Load()
		head, tail := d.unpack(ptrs)
		if tail == head {
			// Queue is empty.
			return nil, false
		}

		// Confirm head and tail (for our speculative check
		// above) and increment tail. If this succeeds, then
		// we own the slot at tail.
		ptrs2 := d.pack(head, tail+1)
		if d.headTail.CompareAndSwap(ptrs, ptrs2) {
			// Success.
			slot = &d.vals[tail&uint32(len(d.vals)-1)]
			break
		}
	}

	// We now own slot.
	val := *(*any)(unsafe.Pointer(slot))
	if val == dequeueNil(nil) {
		val = nil
	}

	// Tell pushHead that we're done with this slot. Zeroing the
	// slot is also important so we don't leave behind references
	// that could keep this object live longer than necessary.
	//
	// We write to val first and then publish that we're done with
	// this slot by atomically writing to typ.
	slot.val = nil
	atomic.StorePointer(&slot.typ, nil)
	// At this point pushHead owns the slot.

	return val, true
}

The last three lines are the hand-off: clear the value so the GC can collect it if nobody wants it, then atomically clear typ to tell the producer “you may reuse this slot now”. The ordering (val first, then typ) matters — the producer reads typ to decide whether it can write.

The slow path: stealing and the victim cache

When the local shard is empty, getSlow goes hunting:

 go
 
 
// src/sync/pool.go:162
func (p *Pool) getSlow(pid int) any {
	// See the comment in pin regarding ordering of the loads.
	size := rtatomic.LoadAcquintptr(&p.localSize) // load-acquire
	locals := p.local // load-consume
	// Try to steal one element from other procs.
	for i := 0; i < int(size); i++ {
		l := indexLocal(locals, (pid+i+1)%int(size))
		if x, _ := l.shared.popTail(); x != nil {
			return x
		}
	}

	// Try the victim cache. We do this after attempting to steal
	// from all primary caches because we want objects in the
	// victim cache to age out if at all possible.
	size = atomic.LoadUintptr(&p.victimSize)
	if uintptr(pid) >= size {
		return nil
	}
	locals = p.victim
	l := indexLocal(locals, pid)
	if x := l.private; x != nil {
		l.private = nil
		return x
	}
	for i := 0; i < int(size); i++ {
		l := indexLocal(locals, (pid+i)%int(size))
		if x, _ := l.shared.popTail(); x != nil {
			return x
		}
	}

	// Mark the victim cache as empty for future gets don't bother
	// with it.
	atomic.StoreUintptr(&p.victimSize, 0)

	return nil
}

Three stages:

Steal from every other P’s shared chain, starting with the next P and wrapping around. This is the work-stealing pattern, and it is why popTail exists: the tail is the end of the queue that the owner is least likely to want, so it is the safest thing to take.
The victim cache, but only after trying every primary cache. The comment gives the reason: “we want objects in the victim cache to age out if at all possible”. Objects that have been sitting for a whole GC cycle should be reclaimed before objects that were just put back.
If that fails too, the victim cache is marked empty and Get returns nil (or calls New).

The two-generation rule

Here is the part that makes items vanish. At the start of every garbage collection, with the world stopped, the runtime calls the pool cleanup hook:

 go
 
 
// src/sync/pool.go:258
//go:linkname poolCleanup
func poolCleanup() {
	// This function is called with the world stopped, at the beginning of a garbage collection.
	// It must not allocate and probably should not call any runtime functions.

	// Because the world is stopped, no pool user can be in a
	// pinned section (in effect, this has all Ps pinned).

	// Drop victim caches from all pools.
	for _, p := range oldPools {
		p.victim = nil
		p.victimSize = 0
	}

	// Move primary cache to victim cache.
	for _, p := range allPools {
		p.victim = p.local
		p.victimSize = p.localSize
		p.local = nil
		p.localSize = 0
	}

	// The pools with non-empty primary caches now have non-empty
	// victim caches and no pools have primary caches.
	oldPools, allPools = allPools, nil
}

The rule is right there in the code:

Old victim caches are dropped. Anything that was in the victim generation at the start of this GC is thrown away. It has now survived two collections without being used.
The primary cache becomes the victim cache, and the primary cache is emptied.

So the lifecycle of an object is:

 text
 
 
 Put()
 |
 v
 [ primary ] -- GC #1 --> [ victim ] -- GC #2 --> gone
 | |
 | Get() here | Get() here
 v v
 reused reused (one last chance)

An object that is put and never fetched survives one garbage collection. If it is still sitting in the victim cache at the next collection, it is dropped and the garbage collector reclaims it.

The runtime calls this from the garbage collector:

 go
 
 
// src/runtime/mgc.go:2175
func clearpools() {
	// clear sync.Pools
	if poolcleanup != nil {
		poolcleanup()
	}

	// clear boringcrypto caches
	for _, p := range boringCaches {
		atomicstorep(p, nil)
	}

	// Clear central sudog cache.
	// Leave per-P caches alone, they have strictly bounded size.
	// Disconnect cached list before dropping it on the floor,
	// so that a dangling ref to one entry does not pin all of them.
	lock(&sched.sudoglock)

Note that the GC clears all pools in the program, not just the ones you know about, and it does so with the world stopped, which is why the cleanup function “must not allocate and probably should not call any runtime functions”.

Why a victim cache at all?

It seems wasteful to throw everything away at every GC. Why not just keep one generation?

Because the victim cache solves a specific problem: a burst of activity that ends just before a GC. Suppose a server handles a burst of 10 000 requests, each allocating a buffer, and then goes idle. The GC runs. If the pool dropped everything, the next burst would allocate 10 000 fresh buffers from the heap — a latency spike exactly when the system is trying to recover.

With the victim cache, the buffers survive one GC cycle. The next burst finds them waiting, and the GC that follows that reclaims them. So the pool adapts to the workload: an idle pool shrinks to nothing, a pool that is used every few milliseconds keeps its objects warm across the collection that happens in between.

That is the design intent, stated plainly in the doc comment: “The store scales under load (when many goroutines are actively printing) and shrinks when quiescent.”

Trade-offs

What the per-P design buys. Almost no contention. The common case — Put then Get on the same P — touches one any field with no atomic operation at all. Cross-P traffic is a single CAS on the shared chain, and it only happens when a P is empty.

What it costs. Load imbalance. If 90% of the work runs on one P, the other P’s shards stay empty and the busy P’s shard grows into a long chain of rings. GOMAXPROCS changes and scheduler decisions affect the hit rate.

What the private slot buys. A lock-free fast path for the dominant case, at the cost of one wasted slot per P.

What the victim generation buys. Objects survive one GC cycle, which smooths out the “burst, then GC, then burst again” pattern. The cost is that the pool can hold roughly twice the memory it needs, and that runtime.GC() twice in a row empties it completely.

What the lock-free chain buys. No locks in the hot path at all. The cost is a subtle ownership protocol: a slot is owned by a consumer until it clears typ, and the producer must check typ before reusing it.

Caveats

Do not store anything you need. The pool can drop an object at any GC. If losing it would be a bug, it does not belong in a sync.Pool.

Do not use a sync.Pool for a bounded set of objects. If you need “exactly N buffers, reused”, a pool is the wrong tool: it will happily grow without bound between collections, and it will shrink under you at the worst moment. Use a channel-based free list or a fixed-size ring.

Put(nil) does nothing. It is not an error and it does not store nil. Get will not return nil from the pool itself.

The private slot is not really private. The comment says “Can be used only by the respective P”, and pinning enforces that in the common case. But getSlow does read victim’s private slot directly, and after a GOMAXPROCS change the array is reallocated. Treat private as an optimisation, not a guarantee.

Changing GOMAXPROCS discards the pool. pinSlow reallocates the array when the P count grows, and the old array is thrown away — contents included.

runtime.GC() twice empties the pool. The first collection moves everything to the victim cache; the second drops the victim cache.

The pool is per-P, so a Pool used by one goroutine only ever touches one shard. If your program has one goroutine doing all the work, the other GOMAXPROCS-1 shards are pure overhead — a slice of 128-byte structs per P.

Do not copy a Pool. The noCopy field is there to make go vet catch it. A copied pool shares one local pointer, so both copies fight over the same shards.

Items in the pool are reachable from the Pool, so they are not collected while the pool holds them. That is the point, but it means a pool that holds a 10 MB buffer keeps that buffer alive for up to two GC cycles after you Put it.

Wrapping up

The one thing to remember: sync.Pool is a per-P cache with a private single-item slot and a lock-free shared chain, and every garbage collection rotates it into a victim generation. An object survives one GC cycle, and is dropped at the second.

The part people get wrong: the pool is a cache, not a container. Get returning nil is legal and expected; the fix is a New function (or holding your own reference), never assuming the object is still there.

What to go do about it: if you are using sync.Pool to avoid allocations, measure with testing.AllocsPerRun and check the allocation count across a runtime.GC() — if the number of allocations jumps after a collection, your objects are being dropped and you need to either keep a reference yourself or accept that the pool is doing its job and the allocation is the price of the memory.

sync.Map: Two Maps, A Miss Counter and Why Read-Mostly Wins

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

TL;DR: sync.Map used to be two maps — a lock-free read map and a mutex-guarded dirty map — plus a misses counter that promoted dirty to read. That implementation is gone: the type is now a wrapper around internal/sync.HashTrieMap, a 16-way hash trie whose reads take no locks at all.

If you learned Go concurrency from the sync package, you learned sync.Map as a piece of cleverness: a fast read path with no mutex, a slow write path with one, and a heuristic that promotes the slow map to the fast one when the reads outnumber the writes.

That description is now history. The type in the Go 1.28 tree looks like this:

 go
 
 
// src/sync/map.go:11
// Map is like a Go map[any]any but is safe for concurrent use
// by multiple goroutines without additional locking or coordination.
// Loads, stores, and deletes run in amortized constant time.
//
// The Map type is specialized. Most code should use a plain Go map instead,
// with separate locking or coordination, for better type safety and to make it
// easier to maintain other invariants along with the map content.
//
// The Map type is optimized for two common use cases: (1) when the entry for a given
// key is only ever written once but read many times, as in caches that only grow,
// or (2) when multiple goroutines read, write, and overwrite entries for disjoint
// sets of keys. In these two cases, use of a Map may significantly reduce lock
// contention compared to a Go map paired with a separate [Mutex] or [RWMutex].
//
// The zero Map is empty and ready for use. A Map must not be copied after first use.
//
// In the terminology of [the Go memory model], Map arranges that a write operation
// “synchronizes before” any read operation that observes the effect of the write, where
// read and write operations are defined as follows.
// [Map.Load], [Map.LoadAndDelete], [Map.LoadOrStore], [Map.Swap], [Map.CompareAndSwap],
// and [Map.CompareAndDelete] are read operations;
// [Map.Delete], [Map.LoadAndDelete], [Map.Store], and [Map.Swap] are write operations;
// [Map.LoadOrStore] is a write operation when it returns loaded set to false;
// [Map.CompareAndSwap] is a write operation when it returns swapped set to true;
// and [Map.CompareAndDelete] is a write operation when it returns deleted set to true.
//
// [the Go memory model]: https://go.dev/ref/mem
type Map struct {
	_ noCopy

	m isync.HashTrieMap[any, any]
}

One field. Every method is a one-line forward:

 go
 
 
// src/sync/map.go:44
// Load returns the value stored in the map for a key, or nil if no
// value is present.
// The ok result indicates whether value was found in the map.
func (m *Map) Load(key any) (value any, ok bool) {
	return m.m.Load(key)
}

// Store sets the value for a key.
func (m *Map) Store(key, value any) {
	m.m.Store(key, value)
}

So let’s do this in two parts: first, how the old design worked (because it explains the name of the type, and the guidance that survived), and second, what is actually in the tree now.

The old design: two maps and a miss counter

Until Go 1.23, sync.Map held roughly this:

 text
 
 
type Map struct {
 mu sync.Mutex
 read atomic.Pointer[readOnly] // immutable snapshot, read without a lock
 dirty map[any]*entry // guarded by mu; the "current" map
 misses int // read misses on read while it was amended
}

type readOnly struct {
 m map[any]*entry
 amended bool // true if dirty holds keys not in m
}

The read path was the whole point. Load first consulted read.m — an ordinary Go map published through an atomic pointer, so reading it needed no lock at all. Only if the key was missing and read.amended was true (meaning dirty had entries not yet in read) did it take the mutex.

The write path always took the mutex and wrote to dirty. That made writes expensive but kept the lock-free map stable, because mutating a map that concurrent readers are walking is not allowed.

That leaves the obvious problem: dirty accumulates everything, read stays stale, and every read of a key that was written after the last promotion has to fall back to the mutex. The misses counter was the fix. Every time a read missed in read and had to go to dirty under the lock, misses went up by one. When misses reached len(dirty), the map concluded that the reads were overwhelmingly hitting dirty, and promoted it:

 text
 
 
 read.m --(misses >= len(dirty))--> read.m = copy of dirty
 dirty = nil
 amended = false

Promotion copies dirty into a fresh read map so the old one can keep being read without a lock. It is expensive, and it is amortised: it happens roughly once per len(dirty) misses.

The other elegant piece was the expunged sentinel. When a key was deleted, its entry in the read-only map had to be marked somehow, because a plain delete would mutate a map concurrent readers are walking. The old code did not delete the key; it replaced the entry’s atomic pointer with a pointer to a special sentinel expunged entry. A tombstone. That tombstone mattered during promotion: if the key was later re-added to dirty, the promotion had to know that the delete had already been observed by readers, so the key must not come back from the dead. expunged said “this deletion is already public”.

So the classic algorithm was: reads are lock-free when the read map is warm, writes are always locked, and a miss counter decides when to pay for a promotion.

What replaced it: a hash trie

The tree now delegates to internal/sync.HashTrieMap, the same structure the unique package uses. The design goal is stated at the top of the file:

 go
 
 
// src/internal/sync/hashtriemap.go:14
// HashTrieMap is an implementation of a concurrent hash-trie. The implementation
// is designed around frequent loads, but offers decent performance for stores
// and deletes as well, especially if the map is larger. Its primary use-case is
// the unique package, but can be used elsewhere as well.
//
// The zero HashTrieMap is empty and ready to use.
// It must not be copied after first use.
type HashTrieMap[K comparable, V any] struct {
	inited atomic.Uint32
	initMu Mutex
	root atomic.Pointer[indirect[K, V]]
	keyHash hashFunc
	valEqual equalFunc
	seed uintptr
}

There is no mu, no read, no dirty, and no misses. There is a root pointer and a hash function.

Initialisation is lazy and one-time

 go
 
 
// src/internal/sync/hashtriemap.go:30
func (ht *HashTrieMap[K, V]) init() {
	if ht.inited.Load() == 0 {
		ht.initSlow()
	}
}

//go:noinline
func (ht *HashTrieMap[K, V]) initSlow() {
	ht.initMu.Lock()
	defer ht.initMu.Unlock()

	if ht.inited.Load() != 0 {
		// Someone got to it while we were waiting.
		return
	}

	// Set up root node, derive the hash function for the key, and the
	// equal function for the value, if any.
	var m map[K]V
	mapType := abi.TypeOf(m).MapType()
	ht.root.Store(newIndirectNode[K, V](nil))
	ht.keyHash = mapType.Hasher
	ht.valEqual = mapType.Elem.Equal
	ht.seed = uintptr(runtime_rand())

	ht.inited.Store(1)
}

Two things worth noticing. The hash function is the runtime’s own map hasher, obtained from the map type — so HashTrieMap hashes keys exactly the way a map[K]V would. And the seed is random, per map instance, mixed into every hash. That is the same defence against hash-flooding that ordinary Go maps use, and it is why the trie needs no external seed parameter.

The read path takes no locks

This is the part that matters most, and it is short:

 go
 
 
// src/internal/sync/hashtriemap.go:64
func (ht *HashTrieMap[K, V]) Load(key K) (value V, ok bool) {
	ht.init()
	hash := ht.keyHash(abi.NoEscape(unsafe.Pointer(&key)), ht.seed)

	i := ht.root.Load()
	hashShift := 8 * goarch.PtrSize
	for hashShift != 0 {
		hashShift -= nChildrenLog2

		n := i.children[(hash>>hashShift)&nChildrenMask].Load()
		if n == nil {
			return *new(V), false
		}
		if n.isEntry {
			return n.entry().lookup(key)
		}
		i = n.indirect()
	}
	panic("internal/sync.HashTrieMap: ran out of hash bits while iterating")
}

No mutex. No atomic read-modify-write. Just a walk down the trie following bits of the hash, loading an atomic pointer at each level. atomic.Pointer loads are ordinary atomic loads, so this is safe against concurrent writers — the writer publishes new nodes with slot.Store(...) and the reader either sees the old node or the new one.

The fan-out is 16:

 go
 
 
// src/internal/sync/hashtriemap.go:530
const (
	// 16 children. This seems to be the sweet spot for
	// load performance: any smaller and we lose out on
	// 50% or more in CPU performance. Any larger and the
	// returns are minuscule (~1% improvement for 32 children).
	nChildrenLog2 = 4
	nChildren = 1 << nChildrenLog2
	nChildrenMask = nChildren - 1
)

// indirect is an internal node in the hash-trie.
type indirect[K comparable, V any] struct {
	node[K, V]
	dead atomic.Bool
	mu Mutex // Protects mutation to children and any children that are entry nodes.
	parent *indirect[K, V]
	children [nChildren]atomic.Pointer[node[K, V]]
}

So a 64-bit hash gives you 64 / 4 = 16 levels of 4 bits each. The mu in an indirect node is the only lock in the whole structure, and it protects one node’s children — not the whole map. That is the crucial difference from the old design: the old sync.Map had one mutex for the entire map, so two goroutines storing to different keys still serialised. Here, two goroutines storing to different branches of the trie usually take different node locks and never meet.

The leaves are entries, with an overflow chain for genuine hash collisions:

 go
 
 
// src/internal/sync/hashtriemap.go:563
// entry is a leaf node in the hash-trie.
type entry[K comparable, V any] struct {
	node[K, V]
	overflow atomic.Pointer[entry[K, V]] // Overflow for hash collisions.
	key K
	value V
}

func newEntryNode[K comparable, V any](key K, value V) *entry[K, V] {
	return &entry[K, V]{
		node: node[K, V]{isEntry: true},
		key: key,
		value: value,
	}
}

func (e *entry[K, V]) lookup(key K) (V, bool) {
	for e != nil {
		if e.key == key {
			return e.value, true
		}
		e = e.overflow.Load()
	}
	return *new(V), false
}

Note that the entry’s value is not atomic — it is immutable. An update replaces the whole entry node rather than mutating it in place, which is what makes the lock-free read path safe: a reader that has loaded a node sees a consistent key/value pair, and an updater publishes the replacement with a single atomic store.

The write path: double-checked locking on one node

Writing is where the lock is taken, and the pattern is textbook double-checked locking over an atomic pointer:

 go
 
 
// src/internal/sync/hashtriemap.go:126
		// Grab the lock and double-check what we saw.
		i.mu.Lock()
		n = slot.Load()
		if (n == nil || n.isEntry) && !i.dead.Load() {
			// What we saw is still true, so we can continue with the insert.
			break
		}
		// We have to start over.
		i.mu.Unlock()
	}
	// N.B. This lock is held from when we broke out of the outer loop above.
	// We specifically break this out so that we can use defer here safely.
	// One option is to break this out into a new function instead, but
	// there's so much local iteration state used below that this turns out
	// to be cleaner.
	defer i.mu.Unlock()

The optimistic walk is done without the lock, and only if the slot looks like it needs changing does the code take the node’s lock and re-check. If the state changed underneath — another goroutine split the node, or the node was deleted — it drops the lock and starts the whole walk over.

The other interesting write path is expand, which handles two keys that hash to the same slot:

 go
 
 
// src/internal/sync/hashtriemap.go:165
// expand takes oldEntry and newEntry whose hashes conflict from bit 64 down to hashShift and
// produces a subtree of indirect nodes to hold the two new entries.
func (ht *HashTrieMap[K, V]) expand(oldEntry, newEntry *entry[K, V], newHash uintptr, hashShift uint, parent *indirect[K, V]) *node[K, V] {
	// Check for a hash collision.
	oldHash := ht.keyHash(unsafe.Pointer(&oldEntry.key), ht.seed)
	if oldHash == newHash {
		// Store the old entry in the new entry's overflow list, then store
		// the new entry.
		newEntry.overflow.Store(oldEntry)
		return &newEntry.node
	}
	// We have to add an indirect node. Worse still, we may need to add more than one.
	newIndirect := newIndirectNode(parent)
	top := newIndirect
	for {
		if hashShift == 0 {
			panic("internal/sync.HashTrieMap: ran out of hash bits while inserting (incorrect use of unsafe or cgo, or data race?)")
		}
		hashShift -= nChildrenLog2 // hashShift is for the level parent is at. We need to go deeper.
		oi := (oldHash >> hashShift) & nChildrenMask
		ni := (newHash >> hashShift) & nChildrenMask
		if oi != ni {
			newIndirect.children[oi].Store(&oldEntry.node)
			newIndirect.children[ni].Store(&newEntry.node)
			break
		}
		nextIndirect := newIndirectNode(newIndirect)
		newIndirect.children[oi].Store(&nextIndirect.node)
		newIndirect = nextIndirect
	}
	return &top.node
}

Two keys with the same hash become an overflow chain — the old expunged-style linked list, but for collisions rather than deletions. Two keys that merely collide in a slot get an extra level of indirection, growing the trie until their hashes diverge. The trie therefore has a bounded depth (16 levels for a 64-bit hash) no matter how many keys you put in it, which is exactly the property that stops the old hash table from degrading into a linear scan.

Range walks the tree

 go
 
 
// src/internal/sync/hashtriemap.go:498
func (ht *HashTrieMap[K, V]) iter(i *indirect[K, V], yield func(key K, value V) bool) bool {
	for j := range i.children {
		n := i.children[j].Load()
		if n == nil {
			continue
		}
		if !n.isEntry {
			if !ht.iter(n.indirect(), yield) {
				return false
			}
			continue
		}
		e := n.entry()
		for e != nil {
			if !yield(e.key, e.value) {
				return false
			}
			e = e.overflow.Load()
		}
	}
	return true
}

No snapshot, no lock, no dirty-map fallback. The old sync.Map.Range had to fall back to the dirty map when read.amended was true, which meant Range could see the same key twice or hold the mutex for the whole iteration. The trie does not need any of that: it walks the live tree, and the doc comment is explicit about the weaker guarantee.

 go
 
 
// src/sync/map.go:102
// Range calls f sequentially for each key and value present in the map.
// If f returns false, range stops the iteration.
//
// Range does not necessarily correspond to any consistent snapshot of the Map's
// contents: no key will be visited more than once, but if the value for any key
// is stored or deleted concurrently (including by f), Range may reflect any
// mapping for that key from any point during the Range call. Range does not
// block other methods on the receiver; even f itself may call any method on m.
//
// Range may be O(N) with the number of elements in the map even if f returns
// false after a constant number of calls.
func (m *Map) Range(f func(key, value any) bool) {
	m.m.Range(f)
}

Note the Clear method too — the old sync.Map had to walk its maps to clear them; the trie can drop the root on the floor and start over.

Why read-mostly still wins

The guidance in the doc comment has not changed, and the reason it has not changed is that it is not really about the implementation. It is about contention patterns.

A plain map[K]V guarded by a sync.RWMutex has one lock. Every reader takes it (in read mode). Readers scale reasonably, but any writer blocks every reader, and writers serialise against each other.

sync.Map is better when:

Entries are written once and read many times. A cache that is populated once and then read. Reads are lock-free; writes are rare and paid for.
Goroutines work on disjoint key sets. With the old design, two goroutines storing to different keys still serialised on the single mutex. With the trie, they usually take different node locks. This case got dramatically better with the rewrite.

It is worse when the workload is write-heavy or the key set is shared: you pay for a lock-free-read data structure and get a per-node mutex plus the cost of growing the trie. For that case, map[K]V plus a sync.RWMutex (or sync.Mutex) is simpler and usually faster.

The old misses counter was a heuristic for “the reads have moved to the dirty map, so promote”. The trie replaces that heuristic with structure: there is no dirty copy to promote, because there is only one copy, and the parts of it that are being written are protected by narrow locks while everything else is read without any lock at all.

Trade-offs

What the trie buys:

Lock-free reads. Load is a pure pointer walk. No atomic RMW, no shared cache line being written on the read path.
Fine-grained write locking. The lock is per trie node, not per map. Disjoint key sets genuinely do not contend any more.
Bounded depth. Sixteen levels maximum, so lookup is O(16) pointer hops regardless of map size. No rehash-the-world, no long probe chains.
Cheap Clear. Drop the root, allocate a new one.

What it costs:

More memory per key. Every key lives in an entry struct with a key, a value, an overflow pointer and a node header — more than a slot in a Go map.
More pointers to chase. A map lookup is one hash, one bucket, one comparison sequence. A trie lookup is a hash plus up to sixteen pointer dereferences.
any boxing. sync.Map is HashTrieMap[any, any], so every key and value is an interface. Storing a string key boxes it, and comparisons go through the runtime’s equality function rather than a direct string compare.
No snapshot iteration. Range is not consistent, and in a write-heavy workload it can be O(N) even if your callback returns false immediately.

Caveats

sync.Map is not a faster map. It is a different data structure with different trade-offs. The doc comment is right there: “Most code should use a plain Go map instead, with separate locking or coordination, for better type safety”.

Do not copy a Map. The struct embeds noCopy, and the hash trie’s root pointer and lazily-initialised state make a copy meaningless.

Clear exists now but the zero value still must not be copied. Clear drops the root and the next operation re-initialises.

The seed is per-instance. Two sync.Maps hash the same key differently, which is good for hash-flooding resistance and bad for anything that assumes stable hashing.

Range is weakly consistent. If you need a stable view, copy into a plain map under your own lock.

Watch for the any tax. sync.Map cannot be typed. HashTrieMap can, but it is internal. If you are storing a large number of values, the interface boxing and the per-key entry allocation are real costs.

The old implementation is not coming back. If you are reading a blog post or a book that describes read, dirty, amended, misses and expunged, that describes sync.Map as it was up to Go 1.23. The public API is identical; the internals are a completely different machine.

Wrapping up

The one thing to remember: sync.Map in this tree is internal/sync.HashTrieMap — a 16-way hash trie with an atomic root, lock-free reads, and a per-node mutex for writes. There is no dirty map and no misses counter to promote.

The part people get wrong: believing that sync.Map is faster than a plain map plus a mutex. It is not, in general. It wins in exactly two situations — write-once/read-many caches, and disjoint key sets — and the doc comment says so in the second paragraph.

What to go do about it: benchmark your actual pattern. If your map is written once per key and read many times, sync.Map will win; if it is written as often as it is read, map[K]V with a sync.RWMutex will win and will be far easier to reason about. And if you need the typed version of the trie, the unique package is the public face of the same code.

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 Unicode Tables Are Generated and Why the Runtime Doesn't Use Them

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

TL;DR: unicode.IsLetter('é') is a binary search over a sorted list of ranges, each with a stride that lets one entry cover a whole arithmetic progression of code points. Below U+0100 there’s a 256-byte property table as a fast path, and utf8 decoding uses a 256-entry first-byte table plus five “accept ranges” that say which second bytes are legal. The runtime imports none of it — it treats strings as bytes.

Every Go program that does anything with text ends up depending on the unicode package, and unicode is a 10,000-line generated file. That file is regenerated every time Unicode publishes a new version of the UCD, and its shape is unusual enough to be worth understanding: it is not a trie, it is not a perfect hash, and it is not a sorted set of code points. It’s a sorted list of ranges, with a compression trick that lets a single entry cover many code points, plus a flat byte table for the first 256 of them.

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

Where the tables come from

The whole file is generated. Here’s the first six lines of src/unicode/tables.go:

 go
 
 
// src/unicode/tables.go:1
// Code generated by running "go generate" in golang.org/x/text. DO NOT EDIT.

package unicode

// Version is the Unicode edition from which the tables are derived.
const Version = "17.0.0"

That single constant is the whole version story: Unicode 17.0.0. The unicode package’s tables and the utf8 package’s tables are kept consistent by the unicode/utf8 tests, which is why the latter doesn’t depend on the former.

The generator itself is not in this tree. It used to be — Go had a src/unicode/maketables.go that read UnicodeData.txt and friends from the UCD archive and emitted these tables — but the generation now lives alongside golang.org/x/text, and the only thing left behind in the Go tree is the generated output and the hand-written lookup code around it.

The input files are the standard Unicode Character Database: UnicodeData.txt for the general categories and the code point names, DerivedCoreProperties.txt for properties like White_Space and Unified_Ideograph, CaseFolding.txt for simple case folding, and PropList.txt for the binary properties. The generator turns those into range tables.

The shape of a RangeTable

Here is the central data structure:

 go
 
 
// src/unicode/letter.go:16
// RangeTable defines a set of Unicode code points by listing the ranges of
// code points within the set. The ranges are listed in two slices
// to save space: a slice of 16-bit ranges and a slice of 32-bit ranges.
// The two slices must be in sorted order and non-overlapping.
// Also, R32 should contain only values >= 0x10000 (1<<16).
type RangeTable struct {
	R16 []Range16
	R32 []Range32
	LatinOffset int // number of entries in R16 with Hi <= MaxLatin1
}

// Range16 represents of a range of 16-bit Unicode code points. The range runs from Lo to Hi
// inclusive and has the specified stride.
type Range16 struct {
	Lo uint16
	Hi uint16
	Stride uint16
}

// Range32 represents of a range of Unicode code points and is used when one or
// more of the values will not fit in 16 bits. The range runs from Lo to Hi
// inclusive and has the specified stride. Lo and Hi must always be >= 1<<16.
type Range32 struct {
	Lo uint32
	Hi uint32
	Stride uint32
}

Three fields, and the third is the interesting one. Lo and Hi bound a range. Stride says how to step through it.

Stride == 1 means “every code point in [Lo, Hi] is in the set”. Stride == 2 means “every even code point in [Lo, Hi] is in the set”. Stride == 3 means every third, and so on.

That’s a big compression win, because Unicode categories are full of alternating patterns. Look at the actual generated data for the C (category “Other”) table:

 go
 
 
// src/unicode/tables.go:96
var _C = &RangeTable{
	R16: []Range16{
		{0x0000, 0x001f, 1},
		{0x007f, 0x009f, 1},
		{0x00ad, 0x0378, 715},
		{0x0379, 0x0380, 7},
		{0x0381, 0x0383, 1},
		{0x038b, 0x038d, 2},
		{0x03a2, 0x0530, 398},
		{0x0557, 0x0558, 1},
		{0x058b, 0x058c, 1},
		{0x0590, 0x05c8, 56},
		{0x05c9, 0x05cf, 1},

Read {0x00ad, 0x0378, 715} carefully: from U+00AD to U+0378, step by 715. That’s two code points — U+00AD and U+0378 — covering 715 code points of range. And {0x00ad, 0x0378, 715} is two entries’ worth of information in twelve bytes.

The comment in RangeTable says R32 must contain only values ≥ 0x10000. So the table is split: R16 covers the Basic Multilingual Plane, R32 covers the astral planes. Code points below 0x10000 fit in a uint16; the rest don’t. That’s the “two-level” structure — not a trie, but a split by integer width.

LatinOffset is the third field and it’s a search optimisation: it records how many entries of R16 have Hi <= MaxLatin1, so the caller can skip straight past the Latin-1 portion when it already knows the answer.

Stride compression, in code

The lookup code has to honour the stride:

 go
 
 
// src/unicode/letter.go:90
// is16 reports whether r is in the sorted slice of 16-bit ranges.
func is16(ranges []Range16, r uint16) bool {
	if len(ranges) <= linearMax || r <= MaxLatin1 {
		for i := range ranges {
			range_ := &ranges[i]
			if r < range_.Lo {
				return false
			}
			if r <= range_.Hi {
				return range_.Stride == 1 || (r-range_.Lo)%range_.Stride == 0
			}
		}
		return false
	}

	// binary search over ranges
	lo := 0
	hi := len(ranges)
	for lo < hi {
		m := int(uint(lo+hi) >> 1)
		range_ := &ranges[m]
		if range_.Lo <= r && r <= range_.Hi {
			return range_.Stride == 1 || (r-range_.Lo)%range_.Stride == 0
		}
		if r < range_.Lo {
			hi = m
		} else {
			lo = m + 1
		}
	}
	return false
}

The stride test is (r - range_.Lo) % range_.Stride == 0. If the code point is inside the range but not on the right step, it is not a member.

Two search strategies, chosen by table size:

 go
 
 
// src/unicode/letter.go:86
// linearMax is the maximum size table for linear search for non-Latin1 rune.
// Derived by running 'go test -calibrate'.
const linearMax = 18

Eighteen. Below that a linear scan beats a binary search: the branch predictor learns the loop, and you avoid the data-dependent load of the midpoint. The threshold was found by measurement, not guessed.

Now, the dispatch that decides which search to use:

 go
 
 
// src/unicode/letter.go:156
// Is reports whether the rune is in the specified table of ranges.
func Is(rangeTab *RangeTable, r rune) bool {
	r16 := rangeTab.R16
	// Compare as uint32 to correctly handle negative runes.
	if len(r16) > 0 && uint32(r) <= uint32(r16[len(r16)-1].Hi) {
		return is16(r16, uint16(r))
	}
	r32 := rangeTab.R32
	if len(r32) > 0 && r >= rune(r32[0].Lo) {
		return is32(r32, uint32(r))
	}
	return false
}

func isExcludingLatin(rangeTab *RangeTable, r rune) bool {
	r16 := rangeTab.R16
	// Compare as uint32 to correctly handle negative runes.
	if off := rangeTab.LatinOffset; len(r16) > off && uint32(r) <= uint32(r16[len(r16)-1].Hi) {
		return is16(r16[off:], uint16(r))
	}
	r32 := rangeTab.R32
	if len(r32) > 0 && r >= rune(r32[0].Lo) {
		return is32(r32, uint32(r))
	}
	return false
}

Is is the general entry point. isExcludingLatin is the same thing but starts the R16 scan at LatinOffset, skipping the entries the caller already knows don’t contain the answer.

Both compare as uint32 rather than rune: “Compare as uint32 to correctly handle negative runes.” A negative rune is an invalid code point, and casting to uint32 makes it larger than every valid one, so it falls out of the range checks cleanly.

The Latin-1 fast path

Below U+0100 there is a completely different mechanism: a flat array of 256 bytes, one per code point, each holding a bitmask of properties.

 go
 
 
// src/unicode/graphic.go:7
// Bit masks for each code point under U+0100, for fast lookup.
const (
	pC = 1 << iota // a control character.
	pP // a punctuation character.
	pN // a numeral.
	pS // a symbolic character.
	pZ // a spacing character.
	pLu // an upper-case letter.
	pLl // a lower-case letter.
	pp // a printable character according to Go's definition.
	pg = pp | pZ // a graphical character according to the Unicode definition.
	pLo = pLl | pLu // a letter that is neither upper nor lower case.
	pLmask = pLo
)

And the table itself, at the very bottom of tables.go:

 go
 
 
// src/unicode/tables.go:9426
var properties = [MaxLatin1 + 1]uint8{
	0x00: pC, // '\x00'
	0x01: pC, // '\x01'
	0x02: pC, // '\x02'
	0x03: pC, // '\x03'
	0x04: pC, // '\x04'
	0x05: pC, // '\x05'
	0x06: pC, // '\x06'
	0x07: pC, // '\a'

256 bytes. The whole Latin-1 range, classified, in a quarter of a kilobyte. A single array index.

Which means unicode.IsLetter is two completely different code paths depending on the argument:

 go
 
 
// src/unicode/graphic.go:89
// IsLetter reports whether the rune is a letter (category [L]).
func IsLetter(r rune) bool {
	if uint32(r) <= MaxLatin1 {
		return properties[uint8(r)]&(pLmask) != 0
	}
	return isExcludingLatin(Letter, r)
}

For ASCII and Latin-1, it’s a load and a mask. For anything else, it’s a binary search over a table with a few hundred entries.

The same trick appears in IsDigit:

 go
 
 
// src/unicode/digit.go:7
// IsDigit reports whether the rune is a decimal digit.
func IsDigit(r rune) bool {
	if r <= MaxLatin1 {
		return '0' <= r && r <= '9'
	}
	return isExcludingLatin(Digit, r)
}

Note that IsDigit doesn’t even consult the properties table for Latin-1 — it hardcodes '0' <= r && r <= '9', because decimal digits in Latin-1 are exactly the ASCII digits. The properties table is used for the category Nd, which includes things like superscripts and other numeric forms; IsDigit means ASCII-style digits only.

IsGraphic and IsPrint show the same structure with different masks:

 go
 
 
// src/unicode/graphic.go:33
// IsGraphic reports whether the rune is defined as a Graphic by Unicode.
// Such characters include letters, marks, numbers, punctuation, symbols, and
// spaces, from categories [L], [M], [N], [P], [S], [Zs].
func IsGraphic(r rune) bool {
	// We convert to uint32 to avoid the extra test for negative,
	// and in the index we convert to uint8 to avoid the range check.
	if uint32(r) <= MaxLatin1 {
		return properties[uint8(r)]&pg != 0
	}
	return In(r, GraphicRanges...)
}

// IsPrint reports whether the rune is defined as printable by Go. Such
// characters include letters, marks, numbers, punctuation, symbols, and the
// ASCII space character, from categories [L], [M], [N], [P], [S] and the ASCII space
// character. This categorization is the same as [IsGraphic] except that the
// only spacing character is ASCII space, U+0020.
func IsPrint(r rune) bool {
	if uint32(r) <= MaxLatin1 {
		return properties[uint8(r)]&pp != 0
	}
	return In(r, PrintRanges...)
}

The comment “We convert to uint32 to avoid the extra test for negative, and in the index we convert to uint8 to avoid the range check” is a nice piece of micro-optimisation commentary: casting to uint32 handles the negativity check for free (negatives become huge), and casting to uint8 for the index lets the compiler drop the bounds check because uint32(r) <= MaxLatin1 implies uint8(r) < 256.

Case mapping and the delta trick

Case conversion uses a different table, because the mapping isn’t a membership question — it’s an arithmetic one:

 go
 
 
// src/unicode/letter.go:44
// CaseRange represents a range of Unicode code points for simple (one
// code point to one code point) case conversion.
// The range runs from Lo to Hi inclusive, with a fixed stride of 1. Deltas
// are the number to add to the code point to reach the code point for a
// different case for that character. They may be negative. If zero, it
// means the character is in the corresponding case. There is a special
// case representing sequences of alternating corresponding Upper and Lower
// pairs. It appears with a fixed Delta of
//
//	{UpperLower, UpperLower, UpperLower}
//
// The constant UpperLower has an otherwise impossible delta value.
type CaseRange struct {
	Lo uint32
	Hi uint32
	Delta d
}

Delta is a three-element array — one delta for upper case, one for lower case, one for title case:

 go
 
 
// src/unicode/letter.go:69
// Indices into the Delta arrays inside CaseRanges for case mapping.
const (
	UpperCase = iota
	LowerCase
	TitleCase
	MaxCase
)

type d [MaxCase]rune // to make the CaseRanges text shorter

And the generated data:

 go
 
 
// src/unicode/tables.go:9085
// CaseRanges is the table describing case mappings for all letters with
// non-self mappings.
var CaseRanges = _CaseRanges
var _CaseRanges = []CaseRange{
	{0x0041, 0x005A, d{0, 32, 0}},
	{0x0061, 0x007A, d{-32, 0, -32}},
	{0x00B5, 0x00B5, d{743, 0, 743}},
	{0x00C0, 0x00D6, d{0, 32, 0}},
	{0x00D8, 0x00DE, d{0, 32, 0}},
	{0x00E0, 0x00F6, d{-32, 0, -32}},
	{0x00F8, 0x00FE, d{-32, 0, -32}},
	{0x00FF, 0x00FF, d{121, 0, 121}},
	{0x0100, 0x012F, d{UpperLower, UpperLower, UpperLower}},
	{0x0130, 0x0130, d{0, -199, 0}},
	{0x0131, 0x0131, d{-232, 0, -232}},

{0x0041, 0x005A, d{0, 32, 0}} is the whole of ASCII uppercase: ‘A’ to ‘Z’, and to get lowercase you add 32. d{0, 32, 0} means: upper case delta 0 (already upper), lower case delta 32 (add 32), title case delta 0.

d{121, 0, 121} for U+00FF (ÿ) is the interesting one: to get uppercase you add 121, giving U+0178 (Ÿ). Unicode’s case mappings are not always subtract-32.

And UpperLower is the special case for alternating pairs:

 go
 
 
// src/unicode/letter.go:79
// If the Delta field of a [CaseRange] is UpperLower, it means
// this CaseRange represents a sequence of the form (say)
// [Upper] [Lower] [Upper] [Lower].
const (
	UpperLower = MaxRune + 1 // (Cannot be a valid delta.)
)

MaxRune + 1 — a value that cannot possibly be a valid delta, used as a sentinel. The conversion code detects it and flips the low bit of the offset instead:

 go
 
 
// src/unicode/letter.go:240
		// The correct mapping can be done by clearing or setting the low
		// bit in the sequence offset.
		// The constants UpperCase and TitleCase are even while LowerCase
		// is odd so we take the low bit from _case.
		return rune(cr.Lo) + ((r-rune(cr.Lo))&^1 | rune(_case&1))
	}
	return r + delta
}

UpperCase is 0 (even), LowerCase is 1 (odd), TitleCase is 2 (even). The low bit of the case constant selects upper or lower; the low bit of the offset selects which member of the alternating pair you are. One branchless expression handles the whole alternating range.

Lookup is a plain binary search:

 go
 
 
// src/unicode/letter.go:211
func lookupCaseRange(r rune, caseRange []CaseRange) *CaseRange {
	// binary search over ranges
	lo := 0
	hi := len(caseRange)
	for lo < hi {
		m := int(uint(lo+hi) >> 1)
		cr := &caseRange[m]
		if rune(cr.Lo) <= r && r <= rune(cr.Hi) {
			return cr
		}
		if r < rune(cr.Lo) {
			hi = m
		} else {
			lo = m + 1
		}
	}
	return nil
}

The special cases — Turkish and Azeri — are hand-written, because the generator never got around to them:

 go
 
 
// src/unicode/casetables.go:5
// TODO: This file contains the special casing rules for Turkish and Azeri only.
// It should encompass all the languages with special casing rules
// and be generated automatically, but that requires some API
// development first.

That’s an honest TODO left in the tree, and it’s a good illustration of the gap between “Unicode has a data file for this” and “Go exposes it”.

Simple folding

Case folding is a third thing: mapping a code point to any other code point in its equivalence class. SimpleFold walks that class:

 go
 
 
// src/unicode/letter.go:336
// SimpleFold iterates over Unicode code points equivalent under
// the Unicode-defined simple case folding. Among the code points
// equivalent to rune (including rune itself), SimpleFold returns the
// smallest rune > r if one exists, or else the smallest rune >= 0.
// If r is not a valid Unicode code point, SimpleFold(r) returns r.
//
// For example:
//
//	SimpleFold('A') = 'a'
//	SimpleFold('a') = 'A'
//
//	SimpleFold('K') = 'k'
//	SimpleFold('k') = '\u212A' (Kelvin symbol, K)
//	SimpleFold('\u212A') = 'K'
//

The Kelvin sign is the classic case: ‘K’, ‘k’ and ‘K’ (U+212A) are all equivalent under case folding. A simple delta table can’t express that, because the equivalence class isn’t a simple arithmetic progression. So there’s a separate small table:

 go
 
 
// src/unicode/tables.go:9816
var caseOrbit = []foldPair{
	{0x004B, 0x006B},
	{0x0053, 0x0073},
	{0x006B, 0x212A},
	{0x0073, 0x017F},
	{0x00B5, 0x039C},
	{0x00C5, 0x00E5},
	{0x00DF, 0x1E9E},
	{0x00E5, 0x212B},
	{0x0130, 0x0130},
	{0x0131, 0x0131},
	{0x017F, 0x0053},
	{0x01C4, 0x01C5},
	{0x01C5, 0x01C6},
	{0x01C6, 0x01C4},

An orbit: each entry says “these two are equivalent under folding”. SimpleFold looks up the current rune in this table first, and if it’s not there, falls back to the lower/upper case ranges.

utf8: the accept-ranges trick

The utf8 package is a different kind of table. It doesn’t need Unicode properties at all — it only needs to know what a legal UTF-8 encoding looks like.

The design is a 256-entry table indexed by the first byte, whose entries pack two facts: how long the sequence is, and which “accept range” applies to the second byte.

 go
 
 
// src/unicode/utf8/utf8.go:49
	// These names of these constants are chosen to give nice alignment in the
	// table below. The first nibble is an index into acceptRanges or F for
	// special one-byte cases. The second nibble is the Rune length or the
	// Status for the special one-byte case.
	xx = 0xF1 // invalid: size 1
	as = 0xF0 // ASCII: size 1
	s1 = 0x02 // accept 0, size 2
	s2 = 0x13 // accept 1, size 3
	s3 = 0x03 // accept 0, size 3
	s4 = 0x23 // accept 2, size 3
	s5 = 0x34 // accept 3, size 4
	s6 = 0x04 // accept 0, size 4
	s7 = 0x44 // accept 4, size 4
)

The high nibble is the accept-range index, the low nibble is the sequence length. So s7 = 0x44 means “4 bytes, use accept range 4”. xx = 0xF1 means “invalid, treat as size 1”.

The first-byte table itself:

 go
 
 
// src/unicode/utf8/utf8.go:70
// first is information about the first byte in a UTF-8 sequence.
var first = [256]uint8{
	// 1 2 3 4 5 6 7 8 9 A B C D E F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x00-0x0F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x10-0x1F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x20-0x2F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x30-0x3F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x40-0x4F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x50-0x5F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x60-0x6F
	as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, as, // 0x70-0x7F
	// 1 2 3 4 5 6 7 8 9 A B C D E F
	xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, // 0x80-0x8F
	xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, // 0x90-0x9F
	xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, // 0xA0-0xAF
	xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, // 0xB0-0xBF
	xx, xx, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, // 0xC0-0xCF
	s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, s1, // 0xD0-0xDF
	s2, s3, s3, s3, s3, s3, s3, s3, s3, s3, s3, s3, s3, s4, s3, s3, // 0xE0-0xEF
	s5, s6, s6, s6, s7, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, xx, // 0xF0-0xFF
}

Now the accept ranges:

 go
 
 
// src/unicode/utf8/utf8.go:92
// acceptRange gives the range of valid values for the second byte in a UTF-8
// sequence.
type acceptRange struct {
	lo uint8 // lowest value for second byte.
	hi uint8 // highest value for second byte.
}

// acceptRanges has size 16 to avoid bounds checks in the code that uses it.
var acceptRanges = [16]acceptRange{
	0: {locb, hicb},
	1: {0xA0, hicb},
	2: {locb, 0x9F},
	3: {0x90, hicb},
	4: {locb, 0x8F},
}

Five real ranges. Why do they exist at all? Because UTF-8’s leading bytes encode some of the value, and the second byte’s legal range depends on which bits the first byte already supplied. The classic example: a 3-byte sequence starting with 0xE0 has its second byte restricted to 0xA0..0xBF, because 0xE0 already means the code point starts at 0x0000, and allowing 0x80..0x9F there would let you encode an overlong (invalid) form.

The five ranges cover exactly those boundary cases:

Range	Second byte	Why
0	`0x80..0xBF`	The default continuation byte range
1	`0xA0..0xBF`	After `0xE0` — prevents overlong 3-byte forms
2	`0x80..0x9F`	After `0xED` — prevents UTF-16 surrogates `0xD800..0xDFFF`
3	`0x90..0xBF`	After `0xF0` — prevents overlong 4-byte forms
4	`0x80..0x8F`	After `0xF4` — prevents code points above `0x10FFFF`

That’s the entire validation of UTF-8, in five lines of table.

Now the decoder:

 go
 
 
// src/unicode/utf8/utf8.go:219
func DecodeRuneInString(s string) (r rune, size int) {
	// Inlineable fast path for ASCII characters; see #48195.
	// This implementation is a bit weird but effective at rendering the
	// function inlineable.
	if s != "" && s[0] < RuneSelf {
		return rune(s[0]), 1
	} else {
		r, size = decodeRuneInStringSlow(s)
	}
	return
}

func decodeRuneInStringSlow(s string) (rune, int) {
	n := len(s)
	if n < 1 {
		return RuneError, 0
	}
	s0 := s[0]
	x := first[s0]
	if x >= as {
		// The following code simulates an additional check for x == xx and
		// handling the ASCII and invalid cases accordingly. This mask-and-or
		// approach prevents an additional branch.
		mask := rune(x) << 31 >> 31 // Create 0x0000 or 0xFFFF.
		return rune(s[0])&^mask | RuneError&mask, 1
	}
	sz := int(x & 7)
	accept := acceptRanges[x>>4]
	if n < sz {
		return RuneError, 1
	}
	s1 := s[1]
	if s1 < accept.lo || accept.hi < s1 {
		return RuneError, 1
	}
	if sz <= 2 { // <= instead of == to help the compiler eliminate some bounds checks
		return rune(s0&mask2)<<6 | rune(s1&maskx), 2
	}
	s2 := s[2]
	if s2 < locb || hicb < s2 {
		return RuneError, 1
	}
	if sz <= 3 {
		return rune(s0&mask3)<<12 | rune(s1&maskx)<<6 | rune(s2&maskx), 3
	}
	s3 := s[3]
	if s3 < locb || hicb < s3 {
		return RuneError, 1
	}
	return rune(s0&mask4)<<18 | rune(s1&maskx)<<12 | rune(s2&maskx)<<6 | rune(s3&maskx), 4
}

The mask-and-or trick for the ASCII/invalid case is worth a moment. x is as (0xF0) for ASCII and xx (0xF1) for an invalid starter byte, so the low bit of the table entry distinguishes the two cases. rune(x) << 31 shifts that low bit up to the sign bit, and the arithmetic >> 31 turns it back into a full mask: 0x0000 for ASCII, all-ones for invalid. Then rune(s[0])&^mask | RuneError&mask picks the byte or the replacement rune without a branch.

Now utf8.Valid:

 go
 
 
// src/unicode/utf8/utf8.go:469
// Valid reports whether p consists entirely of valid UTF-8-encoded runes.
func Valid(p []byte) bool {
	// This optimization avoids the need to recompute the capacity
	// when generating code for slicing p, bringing it to parity with
	// ValidString, which was 20% faster on long ASCII strings.
	p = p[:len(p):len(p)]

	for len(p) > 0 {
		p0 := p[0]
		if p0 < RuneSelf {
			p = p[1:]
			// If there's one ASCII byte, there are probably more.
			// Advance quickly through ASCII-only data.
			// Note: using > instead of >= here is intentional. That avoids
			// needing pointing-past-the-end fixup on the slice operations.
			if len(p) > ptrSize && word(p)&hiBits == 0 {
				p = p[ptrSize:]
				if len(p) > 2*ptrSize && (word(p)|word(p[ptrSize:]))&hiBits == 0 {
					p = p[2*ptrSize:]
					for len(p) > 4*ptrSize && ((word(p)|word(p[ptrSize:]))|(word(p[2*ptrSize:])|word(p[3*ptrSize:])))&hiBits == 0 {
						p = p[4*ptrSize:]
					}
				}
			}
			continue
		}

That’s the ASCII fast path: after seeing one ASCII byte, it loads 8 bytes at a time and checks that all the high bits are clear, skipping whole words. On long ASCII strings, utf8.Valid runs at several gigabytes per second.

Why the runtime doesn’t use any of this

Here’s the punchline: the runtime package imports neither unicode nor unicode/utf8. A grep of src/runtime/*.go for those imports turns up exactly one hit, and it’s in runtime/string_test.go.

That’s a deliberate design decision with three reasons.

Size. The runtime is in every binary. unicode/tables.go is over 10,000 lines and several hundred kilobytes of generated data. Importing unicode into the runtime would put all of it into every Go program, including the ones that never look at a non-ASCII character.

The runtime doesn’t need it. Go strings are byte sequences. The runtime manipulates them — slicing, concatenating, hashing, comparing — and none of those operations care whether the bytes are valid UTF-8. The GC traces pointers, not characters. The scheduler doesn’t parse text.

It would be a layering violation. unicode is a user-facing library with a big generated blob and a go:generate pipeline. The runtime is the bottom of the stack. Making the runtime depend on it would mean the runtime’s own binary size is coupled to the Unicode version.

The same reasoning shows up in unicode/utf8, which duplicates a handful of constants rather than importing unicode:

 go
 
 
// src/unicode/utf8/utf8.go:10
// The conditions RuneError==unicode.ReplacementChar and
// MaxRune==unicode.MaxRune are verified in the tests.
// Defining them locally avoids this package depending on package unicode.

Three constants, redefined, with the invariant enforced by a test. That’s the price of keeping the dependency graph acyclic and the binaries small.

Where Unicode knowledge is needed — the compiler, scanning source identifiers, and the strings package — it lives in ordinary library code, not in the runtime.

Trade-offs

What the range-table design buys:

Compactness. The stride trick compresses the categories enormously. A table that would need thousands of individual entries becomes tens of entries.
Speed for the common case. Latin-1 is a single byte lookup. ASCII is a single byte lookup with a mask.
Cache friendliness. A sorted array of 12-byte entries is far more compact than a hash table or a trie, so a binary search touches fewer cache lines.
No initialization. The tables are compile-time constants. No init() function, no lazy building, no lock.

What it costs:

Binary search. IsLetter for a non-Latin-1 rune is O(log n) with data-dependent memory access — the classic profile of a cache-missing binary search.
A lookup is a lookup, not a bit test. For a trie you’d get one memory access; here you get log(n) of them, scattered across the table.
Two code paths everywhere. Every predicate in the package has to handle Latin-1 and non-Latin-1 separately, and the two paths must agree.
Regeneration is a chore. A new Unicode version means regenerating 10,000 lines of Go and reviewing the diff.

Caveats

The tables are only as good as their Unicode version. The Version constant says 17.0.0. Code that depends on the exact set of characters in a category is depending on that version.

IsDigit is not unicode.IsNumber. IsDigit means ASCII-style decimal digits. IsNumber is category N, which includes Roman numerals, superscripts, and fractions. Getting this wrong is a classic source of validation bugs.

Case conversion is “simple” case conversion only. One code point in, one code point out. The German ß uppercases to “SS” — two code points — and unicode.ToUpper('ß') does not do that. The package documentation is explicit:

 go
 
 
// src/unicode/letter.go:66
// BUG(r): There is no mechanism for full case folding, that is, for
// characters that involve multiple runes in the input or output.

Turkish casing is a special case, not a general mechanism. Only Turkish and Azeri have hand-written special tables. Greek final sigma, German sharp s, and Lithuanian rules are not handled.

unicode has no normalisation. NFC and NFD are not in the standard library. If you need them, golang.org/x/text/unicode/norm is where they live.

A rune can hold an invalid code point. rune is just an int32. You can hold -1, or 0x110000, or a surrogate. The range tables handle this by casting to uint32 for comparison, but any code that does its own rune arithmetic has to be careful.

The generated file is generated somewhere else. src/unicode/maketables.go no longer exists in this tree; the header of tables.go credits golang.org/x/text. If you’re looking for the generator in the Go source tree, it isn’t there.

Wrapping up

The one thing to remember: Go’s Unicode tables are sorted range tables with a stride, not a trie. One Range16 entry with Stride == 715 covers two code points 715 apart and stands in for 715 individual membership tests. Below U+0100 there’s a 256-byte property table that bypasses the search entirely. utf8 uses the same idea in a different key: a 256-entry first-byte table plus five “accept ranges” that constrain the second byte to reject overlong encodings, surrogates and out-of-range code points.

The part people get wrong: they assume unicode is a general-purpose character database. It isn’t. It has no normalisation, no full case folding, no grapheme clusters, and only two language-specific casing rules. And unicode.IsDigit is not unicode.IsNumber — the first is ASCII digits, the second is the whole Nd category.

What to go do about it: if you’re validating user input, decide which property you actually mean (IsDigit vs IsNumber vs IsLetter) and write the test with a non-Latin-1 character in it — the Latin-1 fast path and the binary search are different code, and a test suite made entirely of ASCII only ever exercises the first one.

How Go's select Picks a Random Ready Case (and Why the Order Is Random)

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

TL;DR: select does not “pick a random case” by rolling dice on the ready set. It shuffles the order it polls the cases in using cheaprandn, then takes the first case that turns out to be ready. Random order plus first-match is exactly equivalent to a uniform random choice among the ready cases, and it costs one random number per case, no allocation and no second scan.

Everyone knows the rule: if several cases of a select are ready, Go picks one at random. Almost nobody knows how, and the “how” is where the interesting engineering lives — because the naive implementation of “pick one at random” is surprisingly expensive.

This is what the Go 1.28 runtime actually does, read from src/runtime/select.go.

The case descriptor

The compiler hands the runtime a flat array of cases, sends first:

 go
 
 
// src/runtime/select.go:20
type scase struct {
	c *hchan // chan
	elem unsafe.Pointer // data element
}

and an array of uint16 order slots:

 go
 
 
// src/runtime/select.go:118
// selectgo returns the index of the chosen scase, which matches the
// ordinal position of its respective select{recv,send,default} call.
// Also, if the chosen scase was a receive operation, it reports whether
// a value was received.
func selectgo(cas0 *scase, order0 *uint16, pc0 *uintptr, nsends, nrecvs int, block bool) (int, bool) {
	gp := getg()
	if debugSelect {
		print("select: cas0=", cas0, "\n")
	}

	// NOTE: In order to maintain a lean stack size, the number of scases
	// is capped at 65536.
	cas1 := (*[1 << 16]scase)(unsafe.Pointer(cas0))
	order1 := (*[1 << 17]uint16)(unsafe.Pointer(order0))

	ncases := nsends + nrecvs
	scases := cas1[:ncases:ncases]
	pollorder := order1[:ncases:ncases]
	lockorder := order1[ncases:][:ncases:ncases]

Two order arrays share one backing allocation: pollorder is the randomised order in which cases are polled, and lockorder is the order in which the channels are locked (sorted by address, to avoid deadlock). Both live on the goroutine’s stack, so a select allocates nothing.

Step one: shuffle the poll order

Here is the randomness, in full:

 go
 
 
// src/runtime/select.go:167
	// generate permuted order
	norder := 0
	allSynctest := true
	for i := range scases {
		cas := &scases[i]

		// Omit cases without channels from the poll and lock orders.
		if cas.c == nil {
			cas.elem = nil // allow GC
			continue
		}

		if cas.c.bubble != nil {
			if getg().bubble != cas.c.bubble {
				fatal("select on synctest channel from outside bubble")
			}
		} else {
			allSynctest = false
		}

		if cas.c.timer != nil {
			cas.c.timer.maybeRunChan(cas.c)
		}

		j := cheaprandn(uint32(norder + 1))
		pollorder[norder] = pollorder[j]
		pollorder[j] = uint16(i)
		norder++
	}
	pollorder = pollorder[:norder]
	lockorder = lockorder[:norder]

This is an insertion shuffle — the classic Fisher-Yates “select a random slot and swap” trick, done inline as the cases are collected. For each case, pick a random position among the ones seen so far and swap it into place. The result is a uniformly random permutation of the cases.

cheaprandn is the cheap, unbiased version:

 go
 
 
// src/runtime/rand.go:317
//go:linkname cheaprandn
//go:nosplit
func cheaprandn(n uint32) uint32 {
	// See https://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/
	return uint32((uint64(cheaprand()) * uint64(n)) >> 32)
}

That is Lemire’s multiply-shift method: instead of rand() % n, which is biased because 2^32 is not a multiple of n, it multiplies a 32-bit random number by n and keeps the top 32 bits. One multiply, one shift, no division, and no modulo bias.

Note the cas.c == nil check at the top of the loop. A select case with a nil channel is dropped from the poll order entirely. It is not “a case that blocks forever” — it is not a case at all. That is the documented way to disable a branch of a select at runtime, and it costs one branch in the shuffle loop.

Step two: work out the lock order

Before the runtime can look at any channel, it has to decide the order in which to lock them. Two goroutines running two selects over the same two channels in opposite orders would deadlock if they locked in case order, so the lock order is sorted by channel address:

 go
 
 
// src/runtime/select.go:206
	// sort the cases by Hchan address to get the locking order.
	// simple heap sort, to guarantee n log n time and constant stack footprint.
	for i := range lockorder {
		j := i
		// Start with the pollorder to permute cases on the same channel.
		c := scases[pollorder[i]].c
		for j > 0 && scases[lockorder[(j-1)/2]].c.sortkey() < c.sortkey() {
			k := (j - 1) / 2
			lockorder[j] = lockorder[k]
			j = k
		}
		lockorder[j] = pollorder[i]
	}

A heap sort, written out longhand, because sort would allocate and the runtime cannot. The sort key is the channel’s address:

 go
 
 
// src/runtime/select.go:545
func (c *hchan) sortkey() uintptr {
	return uintptr(unsafe.Pointer(c))
}

Address order is a total order that every select over the same set of channels agrees on, which is exactly what a deadlock-free lock ordering requires.

The locks are then taken in that order, and released in reverse:

 go
 
 
// src/runtime/select.go:34
func sellock(scases []scase, lockorder []uint16) {
	var c *hchan
	for _, o := range lockorder {
		c0 := scases[o].c
		if c0 != c {
			c = c0
			lock(&c.lock)
		}
	}
}

Note that a channel appearing in several cases is locked once — sellock skips a repeat of the previous channel.

Step three: pass one, poll for something already ready

Now the actual selection. The runtime holds every channel’s lock and walks the randomised poll order, taking the first case that can proceed immediately:

 go
 
 
// src/runtime/select.go:251
	// lock all the channels involved in the select
	sellock(scases, lockorder)

	var (
		sg *sudog
		c *hchan
		k *scase
		sglist *sudog
		sgnext *sudog
		qp unsafe.Pointer
		nextp **sudog
	)

	// pass 1 - look for something already waiting
	var casi int
	var cas *scase
	var caseSuccess bool
	var caseReleaseTime int64 = -1
	var recvOK bool
	for _, casei := range pollorder {
		casi = int(casei)
		cas = &scases[casi]
		c = cas.c

		if casi >= nsends {
			sg = c.sendq.dequeue()
			if sg != nil {
				goto recv
			}
			if c.qcount > 0 {
				goto bufrecv
			}
			if c.closed != 0 {
				goto rclose
			}
		} else {
			if raceenabled {
				racereadpc(c.raceaddr(), casePC(casi), chansendpc)
			}
			if c.closed != 0 {
				goto sclose
			}
			sg = c.recvq.dequeue()
			if sg != nil {
				goto send
			}
			if c.qcount < c.dataqsiz {
				goto bufsend
			}
		}
	}

This is the whole selection algorithm. It is a single pass over the shuffled cases, and the first one that is ready wins. There is no counter of ready cases, no second pass to pick an index, no array of ready flags.

Why is “shuffle then take the first ready” the same as “pick uniformly at random among the ready ones”? Because the permutation is uniform: for any set of ready cases, each of them is equally likely to be first in the permutation, so each is equally likely to be the one that is found first. The shuffling trick lets the runtime avoid the bookkeeping of finding the ready set before choosing from it — it just finds the first one while scanning.

Note also that this pass does not sleep, allocate or block: it only inspects the channels under their locks. For a send case, “ready” means there is a waiting receiver or there is buffer space; for a receive case, “ready” means there is a waiting sender, or there is a value in the buffer, or the channel is closed.

The `default` case

If the pass finds nothing and the select has a default, the runtime gives up immediately:

 go
 
 
// src/runtime/select.go:303
	if !block {
		selunlock(scases, lockorder)
		casi = -1
		goto retc
	}

block is false exactly when the compiler saw a default clause. The -1 is the “no case chosen” sentinel, which the compiler turns back into “run the default branch”.

So a select with a default never parks. It is a poll.

Step four: pass two, park on everything

If nothing was ready and there is no default, the goroutine has to commit to waiting. It registers itself as a waiter on every channel in the select — this is the part that makes a select expensive:

 go
 
 
// src/runtime/select.go:309
	// pass 2 - enqueue on all chans
	if gp.waiting != nil {
		throw("gp.waiting != nil")
	}
	nextp = &gp.waiting
	for _, casei := range lockorder {
		casi = int(casei)
		cas = &scases[casi]
		c = cas.c
		sg := acquireSudog()
		sg.g = gp
		sg.isSelect = true
		// No stack splits between assigning elem and enqueuing
		// sg on gp.waiting where copystack can find it.
		sg.elem.set(cas.elem)
		sg.releasetime = 0
		if t0 != 0 {
			sg.releasetime = -1
		}
		sg.c.set(c)
		// Construct waiting list in lock order.
		*nextp = sg
		nextp = &sg.waitlink

		if casi < nsends {
			c.sendq.enqueue(sg)
		} else {
			c.recvq.enqueue(sg)
		}

		if c.timer != nil {
			blockTimerChan(c)
		}
	}

One sudog per case, each enqueued on its channel’s wait queue, and the sudogs also linked into gp.waiting in lock order — that link order is what lets the park machinery unlock the channels in the right sequence.

Then the goroutine parks:

 go
 
 
// src/runtime/select.go:344
	// wait for someone to wake us up
	gp.param = nil
	// Signal to anyone trying to shrink our stack that we're about
	// to park on a channel. The window between when this G's status
	// changes and when we set gp.activeStackChans is not safe for
	// stack shrinking.
	gp.parkingOnChan.Store(true)
	gopark(selparkcommit, nil, waitReason, traceBlockSelect, 1)
	gp.activeStackChans = false

	sellock(scases, lockorder)

selparkcommit is the unlockf that releases every channel lock:

 go
 
 
// src/runtime/select.go:63
func selparkcommit(gp *g, _ unsafe.Pointer) bool {
	// There are unlocked sudogs that point into gp's stack. Stack
	// copying must lock the channels of those sudogs.
	// Set activeStackChans here instead of before we try parking
	// because we could self-deadlock in stack growth on a
	// channel lock.
	gp.activeStackChans = true
	// Mark that it's safe for stack shrinking to occur now,
	// because any thread acquiring this G's stack for shrinking
	// is guaranteed to observe activeStackChans after this store.
	gp.parkingOnChan.Store(false)
	// Make sure we unlock after setting activeStackChans and
	// unsetting parkingOnChan. The moment we unlock any of the
	// channel locks we risk gp getting readied by a channel operation
	// and so gp could continue running before everything before the
	// unlock is visible (even to gp itself).

	// This must not access gp's stack (see gopark). In
	// particular, it must not access the *hselect. That's okay,
	// because by the time this is called, gp.waiting has all
	// channels in lock order.
	var lastc *hchan
	for sg := gp.waiting; sg != nil; sg = sg.waitlink {
		if sg.c.get() != lastc && lastc != nil {
			// As soon as we unlock the channel, fields in
			// any sudog with that channel may change,
			// including c and waitlink. Since multiple
			// sudogs may have the same channel, we unlock
			// only after we've passed the last instance
			// of a channel.
			unlock(&lastc.lock)
		}
		lastc = sg.c.get()
	}
	if lastc != nil {
		unlock(&lastc.lock)
	}
	return true
}

The unlocking walks gp.waiting — which was built in lock order — so the channels are released in exactly the reverse of the order they were taken. That is what keeps two selects over the same channels from deadlocking.

Step five: pass three, clean up

When the goroutine is woken by one of the channels, it has to remove itself from the other channels’ wait queues. This is the part people forget: a select over five channels parks five sudogs and has to dequeue four of them.

 go
 
 
// src/runtime/select.go:360
	// pass 3 - dequeue from unsuccessful chans
	// otherwise they stack up on quiet channels
	// record the successful case, if any.
	// We singly-linked up the SudoGs in lock order.
	casi = -1
	cas = nil
	caseSuccess = false
	sglist = gp.waiting
	// Clear all elem before unlinking from gp.waiting.
	for sg1 := gp.waiting; sg1 != nil; sg1 = sg1.waitlink {
		sg1.isSelect = false
		sg1.elem.set(nil)
		sg1.c.set(nil)
	}
	gp.waiting = nil

	for _, casei := range lockorder {
		k = &scases[casei]
		if k.c.timer != nil {
			unblockTimerChan(k.c)
		}
		if sg == sglist {
			// sg has already been dequeued by the G that woke us up.
			casi = int(casei)
			cas = k
			caseSuccess = sglist.success
			if sglist.releasetime > 0 {
				caseReleaseTime = sglist.releasetime
			}
		} else {
			c = k.c
			if int(casei) < nsends {
				c.sendq.dequeueSudoG(sglist)
			} else {
				c.recvq.dequeueSudoG(sglist)
			}
		}
		sgnext = sglist.waitlink
		sglist.waitlink = nil
		releaseSudog(sglist)
		sglist = sgnext
	}

The successful case is the sudog that the waking goroutine already dequeued from the queue; every other sudog has to be unlinked by hand. This is also where the “select on a closed channel” result comes from: caseSuccess is false if the wake-up was caused by a close rather than a value transfer.

The two immediate cases

Pass one does not handle the “value is sitting in the buffer” cases inline; it jumps to labels that do the copy. A buffered receive:

 go
 
 
// src/runtime/select.go:446
bufrecv:
	// can receive from buffer
	if raceenabled {
		if cas.elem != nil {
			raceWriteObjectPC(c.elemtype, cas.elem, casePC(casi), chanrecvpc)
		}
		racenotify(c, c.recvx, nil)
	}
	if msanenabled && cas.elem != nil {
		msanwrite(cas.elem, c.elemtype.Size_)
	}
	if asanenabled && cas.elem != nil {
		asanwrite(cas.elem, c.elemtype.Size_)
	}
	recvOK = true
	qp = chanbuf(c, c.recvx)
	if cas.elem != nil {
		typedmemmove(c.elemtype, cas.elem, qp)
	}
	typedmemclr(c.elemtype, qp)
	c.recvx++
	if c.recvx == c.dataqsiz {
		c.recvx = 0
	}
	c.qcount--
	selunlock(scases, lockorder)
	goto retc

and a buffered send:

 go
 
 
// src/runtime/select.go:474
bufsend:
	// can send to buffer
	if raceenabled {
		racenotify(c, c.sendx, nil)
		raceReadObjectPC(c.elemtype, cas.elem, casePC(casi), chansendpc)
	}
	if msanenabled {
		msanread(cas.elem, c.elemtype.Size_)
	}
	if asanenabled {
		asanread(cas.elem, c.elemtype.Size_)
	}
	typedmemmove(c.elemtype, chanbuf(c, c.sendx), cas.elem)
	c.sendx++
	if c.sendx == c.dataqsiz {
		c.sendx = 0
	}
	c.qcount++
	selunlock(scases, lockorder)
	goto retc

Both unlock every channel before returning. A select that completes immediately still paid for locking all of the channels.

`reflect.Select` is the same function

The reflection-based select does not have its own implementation. It rebuilds the case array and calls selectgo directly:

 go
 
 
// src/runtime/select.go:568
//go:linkname reflect_rselect reflect.rselect
func reflect_rselect(cases []runtimeSelect) (int, bool) {
	if len(cases) == 0 {
		block()
	}
	sel := make([]scase, len(cases))
	orig := make([]int, len(cases))
	nsends, nrecvs := 0, 0
	dflt := -1
	for i, rc := range cases {
		var j int
		switch rc.dir {
		case selectDefault:
			dflt = i
			continue
		case selectSend:
			j = nsends
			nsends++
		case selectRecv:
			nrecvs++
			j = len(cases) - nrecvs
		}

		sel[j] = scase{c: rc.ch, elem: rc.val}
		orig[j] = i
	}

	// Only a default case.
	if nsends+nrecvs == 0 {
		return dflt, false
	}

	// Compact sel and orig if necessary.
	if nsends+nrecvs < len(cases) {
		copy(sel[nsends:], sel[len(cases)-nrecvs:])
		copy(orig[nsends:], orig[len(cases)-nrecvs:])
	}

	order := make([]uint16, 2*(nsends+nrecvs))
	var pc0 *uintptr
	if raceenabled {
		pcs := make([]uintptr, nsends+nrecvs)
		for i := range pcs {
			selectsetpc(&pcs[i])
		}
		pc0 = &pcs[0]
	}

	chosen, recvOK := selectgo(&sel[0], &order[0], pc0, nsends, nrecvs, dflt == -1)

	// Translate chosen back to caller's ordering.
	if chosen < 0 {
		chosen = dflt
	} else {
		chosen = orig[chosen]
	}
	return chosen, recvOK
}

The interesting part is the reordering: reflect.Select takes its cases in the caller’s order, but the runtime wants sends first and receives after, so it shuffles them into sel and keeps an orig map to translate the chosen index back. And unlike a compiled select, reflect.Select allocates: sel, orig and order are all heap slices.

The single-case special case

A select with exactly one case and a default does not go through selectgo at all. The compiler rewrites it into a plain non-blocking channel operation:

 go
 
 
// src/runtime/chan.go:761
// compiler implements
//
//	select {
//	case c <- v:
//		... foo
//	default:
//		... bar
//	}
//
// as
//
//	if selectnbsend(c, v) {
//		... foo
//	} else {
//		... bar
//	}
func selectnbsend(c *hchan, elem unsafe.Pointer) (selected bool) {
	return chansend(c, elem, false, sys.GetCallerPC())
}

and the receive twin:

 go
 
 
// src/runtime/chan.go:781
// compiler implements
//
//	select {
//	case v, ok = <-c:
//		... foo
//	default:
//		... bar
//	}
//
// as
//
//	if selected, ok = selectnbrecv(&v, c); selected {
//		... foo
//	} else {
//		... bar
//	}
func selectnbrecv(elem unsafe.Pointer, c *hchan) (selected, received bool) {
	return chanrecv(c, elem, false)
}

So select { case v := <-c: default: } costs one lock-free check and, if it fails, one lock. It never locks more than one channel and never randomises anything — there is nothing to randomise between.

What a select costs

Let’s put numbers on it. For a select over N channels:

Step	Cost
Shuffle	N calls to `cheaprandn`, N swaps
Sort	N log N comparisons, heap sort, no allocation
Lock	up to N mutex acquisitions
Poll	up to N queue checks under those locks
Park (if nothing ready)	N `sudog`s allocated, N enqueues, N dequeues on wake-up

Compare that with a plain channel operation: one lock, one check, maybe one copy.

So a select over N channels is roughly N times the cost of a single channel operation even in the best case where one case is immediately ready, because all N channels are locked before any of them is inspected.

This is the single most useful practical fact in this article:

 go
 
 
// hot path: a select that usually has exactly one ready case
for {
	select {
	case v := <-a:
		handle(v)
	case v := <-b:
		handle(v)
	}
}

is measurably slower than the same thing written as two separate receives guarded by len() checks, or as two goroutines feeding one channel. The select buys you the ability to wait on many channels at once; it charges you for all of them, always.

The mitigation is to keep the number of cases small and to use default where a non-blocking poll is enough.

Trade-offs

What random order buys. Fairness. If select always preferred the first ready case in source order, then a channel earlier in the list would starve the ones after it under load. Shuffling makes every case equally likely to win, so no case is systematically favoured.

What it costs. One multiply and one shift per case, plus the swap. For a two-case select that is a couple of nanoseconds — negligible compared to the locking.

What the locking buys. The runtime must hold all the channel locks while it decides, otherwise two goroutines could both decide to take the same value. The address-ordered lock acquisition is what makes that safe without deadlock.

What it costs. A select over N channels blocks N mutexes. If two goroutines select over the same channels in different orders, the address sort saves them. But if they select over overlapping channel sets, the locks are held for the duration of the decision — which includes the parking setup.

Caveats

The randomness is not crypto-strength and not seeded per call. It comes from the per-M cheap random generator, whose state advances on every use. Two selects in a row from the same goroutine get different orders; but you should never build a protocol on the exact case chosen.

A select on a nil channel never fires. The case is dropped from the poll order during the shuffle, so it is not merely “blocked” — it is invisible. This is the documented way to disable a branch, and it is also why select {} with no cases blocks forever.

select {} with no cases blocks forever. The runtime does it with an explicit park:

 go
 
 
// src/runtime/select.go:103
func block() {
	gopark(nil, nil, waitReasonSelectNoCases, traceBlockForever, 1) // forever
}

A send on a closed channel in a select panics, even if other cases were ready. The panic happens in the sclose label after the unlock, so the other channels are released properly and the panic does not wedge the runtime:

 go
 
 
// src/runtime/select.go:539
sclose:
	// send on closed channel
	selunlock(scases, lockorder)
	panic(plainError("send on closed channel"))
}

Receiving from a closed channel in a select succeeds immediately with the zero value and ok == false, and it competes with other ready cases like any other.

Descriptions of select that say “the runtime counts the ready cases and picks one at random” describe an older implementation. The code in this tree does not count anything: it shuffles the poll order and takes the first ready case. The observable behaviour is the same, but the cost is different, and the cost is what matters when you are deciding whether a select is affordable in a hot loop.

Wrapping up

The one thing to remember: select shuffles the order it polls its cases in with cheaprandn and takes the first ready one. Random order plus first-match is a uniform random choice among the ready cases, computed in one pass with no allocation.

The part people get wrong: a select locks every channel it mentions, before it knows whether any of them is ready. A select over N channels is not “N cheap polls”; it is N mutex acquisitions plus N queue inspections, even when the first case would have sufficed.

What to go do about it: measure it. Write a benchmark that selects over two always-ready channels and compare it with two plain receives on separate channels feeding a single select with one case. If the select is the bottleneck, the fix is almost never the language — it is fewer cases, or a default, or restructuring so that one channel carries everything.

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 Go's Race Detector Works: Shadow Memory and Vector Clocks

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

TL;DR: go test -race compiles in hooks into LLVM’s ThreadSanitizer, which ships as a prebuilt .syso blob. The compiler adds raceread/racewrite around every memory access, the runtime tells the blob where the heap lives, and vector clocks decide which accesses were actually unordered.

Data races are the bugs that don’t reproduce on your machine, don’t reproduce in CI, and then reproduce for a user at 3am. Go’s answer to them is -race, and most people use it as a black box: push the flag, get a stack trace if you are unlucky, feel good.

It is worth understanding what is actually happening, because the design explains both why the detector is so effective and why it is not a proof.

Where the race detector actually lives

The first surprise is that the Go source tree does not contain a race detector.

src/runtime/race/doc.go is four lines long:

 go
 
 
// src/runtime/race/doc.go:5
// Package race implements data race detection logic.
// No public interface is provided.
// For details about the race detector see
// https://golang.org/doc/articles/race_detector.html
package race

And src/runtime/race/README explains where the code went:

 text
 
 
// src/runtime/race/README:1
runtime/race package contains the data race detector runtime library.
It is based on ThreadSanitizer race detector, that is currently a part of
the LLVM project (https://github.com/llvm/llvm-project/tree/main/compiler-rt).

To update the .syso files use golang.org/x/build/cmd/racebuild.

internal/amd64v1/race_darwin.syso built with LLVM 51bfeff0e4b0757ff773da6882f4d538996c9b04 with patch internal/amd64v1/race_darwin.patch and Go a61fd428974822a8c57a2b2840fc237e6711b24d.

So the shadow memory machinery, the vector clock implementation, the happens-before analysis — none of that is in the Go tree. It is compiled C code from LLVM’s compiler-rt, linked into the Go binary as an object file. The Go tree contains the hooks into it.

That is worth internalising, because it means the Go tree can only show you the interface, not the algorithm. Let’s look at the interface, because it is where the interesting Go-specific decisions live.

The compile-time instrumentation

With -race, the compiler turns on two things: memory instrumentation and function-entry instrumentation.

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:347
	if base.Flag.Cfg.Instrumenting && fn.Pragma&ir.Norace == 0 && !fn.Linksym().ABIWrapper() {
		if !base.Flag.Race || !objabi.LookupPkgSpecial(fn.Sym().Pkg.Path).NoRaceFunc {
			s.instrumentMemory = true
			if base.Flag.Race {
				s.instrumentEnterExit = true
			}
		}
	}

instrumentEnterExit means every function gets a call at its entry with the caller’s program counter, so the detector can attribute an access to a source line rather than to “somewhere in this function”:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:577
	// Convert the AST-based IR to the SSA-based IR
	if s.instrumentEnterExit {
		s.rtcall(ir.Syms.Racefuncenter, true, nil, s.newValue0(ssaop.OpGetCallerPC, types.Types[types.TUINTPTR]))
	}

instrumentMemory is the read/write hook, and it has two flavours. For a scalar, one address is enough:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:1558
	} else if base.Flag.Race {
		// for non-composite objects we can write just the start
		// address, as any write must write the first byte.
		switch kind {
		case instrumentRead:
			fn = ir.Syms.Raceread
		case instrumentWrite:
			fn = ir.Syms.Racewrite
		default:
			panic("unreachable")
		}

But for a composite — a struct, an array — a write to any subobject has to be reported, so the whole range is instrumented:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:1545
	} else if base.Flag.Race && t.NumComponents(types.CountBlankFields) > 1 {
		// for composite objects we have to write every address
		// because a write might happen to any subobject.
		// composites with only one element don't have subobjects, though.
		switch kind {
		case instrumentRead:
			fn = ir.Syms.Racereadrange
		case instrumentWrite:
			fn = ir.Syms.Racewriterange
		default:
			panic("unreachable")
		}
		needWidth = true

The symbols those calls point at are declared in the runtime:

 go
 
 
// src/runtime/race.go:424
func racefuncenter(callpc uintptr)
func racefuncenterfp(fp uintptr)
func racefuncexit()
func raceread(addr uintptr)
func racewrite(addr uintptr)
func racereadrange(addr, size uintptr)
func racewriterange(addr, size uintptr)
func racereadrangepc1(addr, size, pc uintptr)
func racewriterangepc1(addr, size, pc uintptr)
func racecallbackthunk(uintptr)

And on amd64 they are thin assembly thunks that switch to the g0 stack and call straight into the C runtime:

 asm
 
 
// src/runtime/race_amd64.s:43
// func runtime·raceread(addr uintptr)
// Called from instrumented code.
// Defined as ABIInternal so as to avoid introducing a wrapper,
// which would render sys.GetCallerPC ineffective.
TEXT	runtime·raceread<ABIInternal>(SB), NOSPLIT, $0-8
	MOVQ	AX, RARG1
	MOVQ	(SP), RARG2
	// void __tsan_read(ThreadState *thr, void *addr, void *pc);
	MOVQ	$__tsan_read(SB), AX
	JMP	racecalladdr<>(SB)

That file’s header comment explains the whole design in three bullets:

 asm
 
 
// src/runtime/race_amd64.s:13
// The following thunks allow calling the gcc-compiled race runtime directly
// from Go code without going all the way through cgo.
// First, it's much faster (up to 50% speedup for real Go programs).
// Second, it eliminates race-related special cases from cgocall and scheduler.
// Third, in long-term it will allow to remove cyclic runtime/race dependency on cmd/go.

“Up to 50% speedup for real Go programs” — that is a number from the tree, and it is a hint at how much of the race build’s cost is cgo overhead rather than detection.

There is also a fast-path filter: if the address being accessed is not in the heap arena or the data segment, there is no shadow for it, so the call is dropped immediately.

 asm
 
 
// src/runtime/race_amd64.s:149
// If addr (RARG1) is out of range, do nothing.
// Otherwise, setup goroutine context and invoke racecall. Other arguments already set.
TEXT	racecalladdr<>(SB), NOSPLIT, $0-0
	MOVQ	g_racectx(R14), RARG0	// goroutine context
	// Check that addr is within [arenastart, arenaend) or within [racedatastart, racedataend).
	CMPQ	RARG1, runtime·racearenastart(SB)
	JB	data
	CMPQ	RARG1, runtime·racearenaend(SB)
	JB	call
data:
	CMPQ	RARG1, runtime·racedatastart(SB)
	JB	ret
	CMPQ	RARG1, runtime·racedataend(SB)
	JAE	ret
call:
	MOVQ	AX, AX		// w/o this 6a miscompiles this function
	JMP	racecall<>(SB)
ret:
	RET

Shadow memory

The detector needs to remember, for every byte of program memory, who last wrote it and what they knew at the time. It does that with a shadow region: a parallel address range holding one byte per eight bytes of application memory (the eight-to-one granularity is a constant inside the prebuilt C runtime, not in this tree — but it is why the detector can afford to instrument every single access, and why a one-byte write to an eight-byte integer is still caught).

The Go tree’s job is to tell the runtime where that shadow should exist. There are exactly two places that matters: the program’s global data, and the heap.

The global data segment is mapped once, at startup:

 go
 
 
// src/runtime/race.go:484
	// Use exact bounds for boundary check in racecalladdr. See issue 73483.
	racedatastart = start
	racedataend = end
	// Round data segment to page boundaries for race detector (TODO: still needed?)
	start = alignDown(start, _PageSize)
	end = alignUp(end, _PageSize)
	racecall(&__tsan_map_shadow, start, end-start, 0, 0)

And the heap is mapped as it grows:

 go
 
 
// src/runtime/race.go:524
//go:nosplit
func racemapshadow(addr unsafe.Pointer, size uintptr) {
	if racearenastart == 0 {
		racearenastart = uintptr(addr)
	}
	if racearenaend < uintptr(addr)+size {
		racearenaend = uintptr(addr) + size
	}
	racecall(&__tsan_map_shadow, uintptr(addr), size, 0, 0)
}

racemapshadow is called from the allocator every time the heap arena grows:

 go
 
 
// src/runtime/malloc.go:926
		racemapshadow(v, size)

That’s the whole of the Go-side shadow management. Everything else — how many shadow bytes, how they’re allocated, how they’re reclaimed — is the C runtime’s business.

Vector clocks: how “happens before” is decided

The shadow byte for a given location holds a shadow clock: the vector clock of the last write to that location. Each goroutine (each OS thread, in TSan’s model) carries its own vector clock. A release bumps the writer’s clock and merges it into the shadow clock of the address; an acquire merges the shadow clock of the address into the reader’s clock. When a read finds that the shadow clock’s write and the reader’s clock are concurrent — neither happens before the other — that is a data race.

Again: the implementation is in the blob. The Go tree shows you the verbs, and the verbs are the whole story. Here is the complete vocabulary the Go runtime uses:

 go
 
 
// src/runtime/race.go:317
// Race runtime functions called via runtime·racecall.
//
//go:linkname __tsan_init __tsan_init
var __tsan_init byte

//go:linkname __tsan_fini __tsan_fini
var __tsan_fini byte

//go:linkname __tsan_proc_create __tsan_proc_create
var __tsan_proc_create byte

//go:linkname __tsan_proc_destroy __tsan_proc_destroy
var __tsan_proc_destroy byte

//go:linkname __tsan_map_shadow __tsan_map_shadow
var __tsan_map_shadow byte

//go:linkname __tsan_finalizer_goroutine __tsan_finalizer_goroutine
var __tsan_finalizer_goroutine byte

//go:linkname __tsan_go_start __tsan_go_start
var __tsan_go_start byte

//go:linkname __tsan_go_end __tsan_go_end
var __tsan_go_end byte

//go:linkname __tsan_malloc __tsan_malloc
var __tsan_malloc byte

//go:linkname __tsan_free __tsan_free
var __tsan_free byte

//go:linkname __tsan_acquire __tsan_acquire
var __tsan_acquire byte

//go:linkname __tsan_release __tsan_release
var __tsan_release byte

//go:linkname __tsan_release_acquire __tsan_release_acquire
var __tsan_release_acquire byte

//go:linkname __tsan_release_merge __tsan_release_merge
var __tsan_release_merge byte

Four happens-before verbs: acquire, release, release_acquire, release_merge. Each maps to a Go-side helper:

 go
 
 
// src/runtime/race.go:611
//go:nosplit
func raceacquire(addr unsafe.Pointer) {
	raceacquireg(getg(), addr)
}

//go:nosplit
func raceacquireg(gp *g, addr unsafe.Pointer) {
	if getg().raceignore != 0 || !isvalidaddr(addr) {
		return
	}
	racecall(&__tsan_acquire, gp.racectx, uintptr(addr), 0, 0)
}

//go:nosplit
func raceacquirectx(racectx uintptr, addr unsafe.Pointer) {
	if !isvalidaddr(addr) {
		return
	}
	racecall(&__tsan_acquire, racectx, uintptr(addr), 0, 0)
}

//go:nosplit
func racerelease(addr unsafe.Pointer) {
	racereleaseg(getg(), addr)
}

//go:nosplit
func racereleaseg(gp *g, addr unsafe.Pointer) {
	if getg().raceignore != 0 || !isvalidaddr(addr) {
		return
	}
	racecall(&__tsan_release, gp.racectx, uintptr(addr), 0, 0)
}

//go:nosplit
func racereleaseacquire(addr unsafe.Pointer) {
	racereleaseacquireg(getg(), addr)
}

//go:nosplit
func racereleaseacquireg(gp *g, addr unsafe.Pointer) {
	if getg().raceignore != 0 || !isvalidaddr(addr) {
		return
	}
	racecall(&__tsan_release_acquire, gp.racectx, uintptr(addr), 0, 0)
}

//go:nosplit
func racereleasemerge(addr unsafe.Pointer) {
	racereleasemergeg(getg(), addr)
}

isvalidaddr is the same “is this address in the heap or the data segment” test the assembly does, but in Go, for the paths that are not assembly:

 go
 
 
// src/runtime/race.go:441
//go:nosplit
func isvalidaddr(addr unsafe.Pointer) bool {
	return racearenastart <= uintptr(addr) && uintptr(addr) < racearenaend ||
		racedatastart <= uintptr(addr) && uintptr(addr) < racedataend
}

The four kinds of event the detector understands

The Go tree funnels everything the detector knows about into four categories.

1. Data races

Ordinary memory accesses, instrumented by the compiler. raceread and racewrite for scalars, racereadrange/racewriterange for composites. This is the category that produces the reports you have seen.

2. Goroutine creation

A goroutine is a thread as far as the detector is concerned, so starting one creates a new clock, and ending one retires it:

 go
 
 
// src/runtime/race.go:545
//go:nosplit
func racegostart(pc uintptr) uintptr {
	gp := getg()
	var spawng *g
	if gp.m.curg != nil {
		spawng = gp.m.curg
	} else {
		spawng = gp
	}

	var racectx uintptr
	racecall(&__tsan_go_start, spawng.racectx, uintptr(unsafe.Pointer(&racectx)), pc, 0)
	return racectx
}

The runtime calls this from newproc1, and the returned context is stored on the new goroutine so every subsequent access in that goroutine is attributed to it:

 go
 
 
// src/runtime/proc.go:5470
	// Set up race context.
	if raceenabled {
		newg.racectx = racegostart(callerpc)
		newg.raceignore = 0
		if newg.labels != nil {
			// See note in proflabel.go on labelSync's role in synchronizing
			// with the reads in the signal handler.
			racereleasemergeg(newg, unsafe.Pointer(&labelSync))
		}
	}

This is also where the “goroutine creation” race shows up: the parent writes to a variable and then starts the goroutine, and the child reads it. Because go start establishes a happens-before edge from the parent’s clock to the child’s, that pattern is not a race. A race is reported when the child touches the variable and the parent writes it later without an edge.

3. Channel operations

Channels are the runtime’s own synchronisation primitive, so the runtime teaches the detector about them directly. Every channel gets a synthetic address used purely as a synchronisation object:

 go
 
 
// src/runtime/chan.go:900
func (c *hchan) raceaddr() unsafe.Pointer {
	// Treat read-like and write-like operations on the channel to
	// happen at this address. Avoid using the address of qcount
	// or dataqsiz, because the len() and cap() builtins read
	// those addresses, and we don't want them racing with
	// operations like close().
	return unsafe.Pointer(&c.buf)
}

And the actual edges are created in racenotify:

 go
 
 
// src/runtime/chan.go:916
// Notify the race detector of a send or receive involving buffer entry idx
// and a channel c or its communicating partner sg.
// This function handles the special case of c.elemsize==0.
func racenotify(c *hchan, idx uint, sg *sudog) {
	// We could have passed the unsafe.Pointer corresponding to entry idx
	// instead of idx itself. However, in a future version of this function,
	// we can use idx to better handle the case of elemsize==0.
	// A future improvement to the detector is to call TSan with c and idx:
	// this way, Go will continue to not allocating buffer entries for channels
	// of elemsize==0, yet the race detector can be made to handle multiple
	// sync objects underneath the hood (one sync object per idx)
	qp := chanbuf(c, idx)
	// When elemsize==0, we don't allocate a full buffer for the channel.
	// Instead of individual buffer entries, the race detector uses the
	// c.buf as the only buffer entry. This simplification prevents us from
	// following the memory model's happens-before rules (rules that are
	// implemented in racereleaseacquire). Instead, we accumulate happens-before
	// information in the synchronization object associated with c.buf.
	if c.elemsize == 0 {
		if sg == nil {
			raceacquire(qp)
			racerelease(qp)
		} else {
			raceacquireg(sg.g, qp)
			racereleaseg(sg.g, qp)
		}
	} else {
		if sg == nil {
			racereleaseacquire(qp)
		} else {
			racereleaseacquireg(sg.g, qp)
		}
	}
}

racereleaseacquire is the important one: a send releases and a receive acquires, which is precisely the happens-before edge the Go memory model promises for channels.

4. Synchronisation primitives

sync.Mutex does not use channels, so it teaches the detector about itself directly. On lock:

 go
 
 
// src/internal/sync/mutex.go:61
func (m *Mutex) Lock() {
	// Fast path: grab unlocked mutex.
	if atomic.CompareAndSwapInt32(&m.state, 0, mutexLocked) {
		if race.Enabled {
			race.Acquire(unsafe.Pointer(m))
		}
		return
	}
	// Slow path (outlined so that the fast path can be inlined)
	m.lockSlow()
}

and on unlock:

 go
 
 
// src/internal/sync/mutex.go:187
func (m *Mutex) Unlock() {
	if race.Enabled {
		_ = m.state
		race.Release(unsafe.Pointer(m))
	}

The mutex’s own address is the synchronisation object. Release on unlock, Acquire on lock, and everything the lock holder wrote before unlocking is visible to whoever locks next.

sync.WaitGroup is more subtle, because a WaitGroup is a counter and a semaphore, and the detector needs to model both. Look at how Add handles the first increment:

 go
 
 
// src/sync/waitgroup.go:104
	state := wg.state.Add(uint64(delta) << 32)
	if state&waitGroupBubbleFlag != 0 && !bubbled {
		// Add has been called from within a synctest bubble (and we aren't in one).
		fatal("sync: WaitGroup.Add called from inside and outside synctest bubble")
	}
	v := int32(state >> 32)
	w := uint32(state & 0x7fffffff)
	if race.Enabled && delta > 0 && v == int32(delta) {
		// The first increment must be synchronized with Wait.
		// Need to model this as a read, because there can be
		// several concurrent wg.counter transitions from 0.
		race.Read(unsafe.Pointer(&wg.sema))
	}

And how Wait models the last decrement:

 go
 
 
// src/sync/waitgroup.go:185
			if race.Enabled && w == 0 {
				// Wait must be synchronized with the first Add.
				// Need to model this is as a write to race with the read in Add.
				// As a consequence, can do the write only for the first waiter,
				// otherwise concurrent Waits will race with each other.
				race.Write(unsafe.Pointer(&wg.sema))
			}

The comments are the interesting part: the WaitGroup deliberately fabricates a read and a write on the same semaphore address so that two concurrent Wait calls, or an Add racing a Wait, are modelled the way the implementation actually behaves.

And atomics

Atomic operations are special-cased in a way that is easy to miss. Under -race, the compiler refuses to intrinsify sync/atomic calls:

 go
 
 
// src/cmd/compile/internal/ssagen/intrinsics.go:2607
	if base.Flag.Race && pkg == "sync/atomic" {
		// The race detector needs to be able to intercept these calls.
		// We can't intrinsify them.
		return nil
	}

So under -race, atomic.LoadInt32 becomes a real call to the assembly in src/runtime/race_amd64.s, which forwards to the detector’s own implementation:

 asm
 
 
// src/runtime/race_amd64.s:196
// Atomic operations for sync/atomic package.

// Load
TEXT	sync∕atomic·LoadInt32(SB), NOSPLIT|NOFRAME, $0-12
	GO_ARGS
	MOVQ	$__tsan_go_atomic32_load(SB), AX
	CALL	racecallatomic<>(SB)
	RET

TEXT	sync∕atomic·LoadInt64(SB), NOSPLIT|NOFRAME, $0-16
	GO_ARGS
	MOVQ	$__tsan_go_atomic64_load(SB), AX
	CALL	racecallatomic<>(SB)
	RET

Compare-and-swap goes through the same door:

 asm
 
 
// src/runtime/race_amd64.s:357
// CompareAndSwap
TEXT	sync∕atomic·CompareAndSwapInt32(SB), NOSPLIT|NOFRAME, $0-17
	GO_ARGS
	MOVQ	$__tsan_go_atomic32_compare_exchange(SB), AX
	CALL	racecallatomic<>(SB)
	RET

This is how the detector learns that an atomic read observed an atomic write: the detector implements the atomic operation itself, on its own shadow cells, so it knows exactly which write it read.

GORACE

The detector is configured through the GORACE environment variable. The runtime’s documentation is one line:

 go
 
 
// src/runtime/extern.go:247
The GORACE variable configures the race detector, for programs built using -race.
See the [Race Detector article] for details.

The parsing itself happens in the C runtime, so the Go tree only shows the options in use. From src/runtime/race/output_test.go:

 go
 
 
// src/runtime/race/output_test.go:201
	{"halt_on_error", "run", "", "atexit_sleep_ms=0 halt_on_error=1", `
package main
func main() {
	done := make(chan bool)
	x := 0; _ = x
	go func() {
		x = 42
		done <- true
	}()
	x = 43
	<-done
}
`, []string{`
==================
exit status 66
`}},

Three things to notice.

halt_on_error=1 stops at the first race and exits with status 66. By default the detector reports every race it finds and exits with 66 at the end. With halt_on_error=1 you get the first one and stop — much faster, and what you want in CI.

atexit_sleep_ms=0 disables a sleep the detector performs at exit. That sleep exists because other goroutines may still be running and might produce reports; setting it to zero makes the process exit immediately instead. Every test in that file sets it, precisely so the tests are deterministic and fast.

Other options that show up in the tree include exitcode=13 (change the exit status) and strip_path_prefix=/main. (rewrite paths in the report). The one everybody meets first is history_size, which controls how many previous accesses the detector remembers per address; raising it lets the detector report the other access that conflicted, not just the current one. Its default is set inside the prebuilt runtime, not in this tree.

The testing package picks the detector’s findings up and turns them into test failures:

 go
 
 
// src/testing/testing.go:1869
		c.Errorf("race detected during execution of test")

What it costs

The widely-quoted figures are a 5–10x slowdown and a large memory overhead. Those numbers come from the race detector article, not from this tree, and they depend enormously on what your program does: a program that spends its life in the allocator sees a much bigger relative hit than one that spends it in tight numeric loops.

What the tree does tell you is that a large fraction of the overhead is cgo, not detection — hence the hand-written thunks and the “up to 50% speedup” comment in src/runtime/race_amd64.s:13. The other half of the cost is the instrumentation itself: every memory access becomes a function call into the detector.

There is a cheaper way to run the detector’s checks without paying the instrumentation cost everywhere: sync/atomic’s own implementation. The runtime’s internal/runtime/atomic package has relaxed-ordering variants that the detector understands, and internal/runtime/atomic.Uint32 documents the trade-off:

 go
 
 
// src/internal/runtime/atomic/types.go:197
// LoadAcquire is a partially unsynchronized version
// of Load that relaxes ordering constraints. Other threads
// may observe operations that precede this operation to
// occur after it, but no operation that occurs after it
// on this thread can be observed to occur before it.
//
// WARNING: Use sparingly and with great care.
//
//go:nosplit
func (u *Uint32) LoadAcquire() uint32 {
	return LoadAcq(&u.value)
}

Trade-offs

What the detector gives you. It finds the races you actually execute. It understands channels, mutexes, wait groups, atomics, and goroutine creation, so it will not cry wolf about a correctly synchronised program. It prints both stacks — the conflicting access and the previous conflicting access — with source lines. That is an enormous improvement over “it crashed once”.

What it costs. Memory and time, both significant. It is a debugging tool, not something you leave on in production.

What it cannot do. It is a dynamic detector. It only sees the accesses that actually happened on that run, on that machine, with that scheduling. A race that requires a particular interleaving to manifest may never be observed.

Why the algorithm is in a blob. Because ThreadSanitizer is a decade-old C++ codebase with a decade of tuning. Reimplementing it in Go would have been a large project with no obvious benefit, and would have to be re-validated against the same corpus of real programs. The Go team’s job was to write the hooks, and that is where the Go-specific design decisions live.

Caveats

The detector only sees races it observes. This is the big one. A race that did not happen during the run is not reported. If the bug only shows up once a week under production load, -race in CI may never see it.

Memory outside the Go heap and globals is not tracked. The shadow mapping covers the heap arena and the data/BSS segments. Memory obtained from cgo or from mmap outside those ranges has no shadow, and accesses to it are dropped by the address filter in racecalladdr.

unsafe and hand-written assembly defeat it. The detector instruments what the compiler sees. A pointer chase through unsafe.Pointer in a loop that the compiler cannot see is invisible to it.

//go:norace disables instrumentation entirely for a function. It exists for code that would otherwise deadlock or crash the detector, and it is a blank cheque, not a hint.

The detector’s own goroutines are excluded. race.Disable() and race.Enable() bracket regions that must not be reported — see internal/race/norace.go for the no-op versions that are compiled into non-race builds:

 go
 
 
// src/internal/race/norace.go:14
const Enabled = false

func Acquire(addr unsafe.Pointer) {
}

func Release(addr unsafe.Pointer) {
}

Note that these are real functions with empty bodies, not absent symbols. That is deliberate: the call sites in sync and internal/sync stay identical in both builds, so the if race.Enabled branch is a predictable one and the code paths do not diverge.

GORACE is read at startup. Changing it after the process starts has no effect on the parts of the configuration that were parsed already.

Wrapping up

The one thing to remember: go test -race compiles in hooks, not a detector. The compiler adds a raceread/racewrite around every memory access and a racefuncenter at every function entry; the runtime tells LLVM’s ThreadSanitizer where the heap and globals live; the detector then uses shadow memory and vector clocks to decide whether the accesses it saw were actually unordered.

The part people get wrong: a clean -race run proves nothing about the races you did not hit. The detector reports the races it observed, on that run, with that scheduler. A program that races only under contention may pass -race in CI for years.

What to go do about it: run -race in CI with GORACE="halt_on_error=1" so the first race fails the build fast, add -count so the tests run more than once, and read src/internal/race/race.go and src/internal/sync/mutex.go next time you wonder how the detector learns about your mutex.

How Go's JSON Parser Avoids Reflection: The Scanner and the v2 Experiment

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

TL;DR: encoding/json is two programs wearing one coat. A hand-written scanner — a state machine with one indirect call per byte — validates the syntax and reports events, and a reflection-driven decoder walks the result into your Go values. The Go 1.28 tree also contains a full experimental rewrite: encoding/json/jsontext for syntax and encoding/json/v2 for semantics, both gated behind GOEXPERIMENT=jsonv2.

JSON is the most-executed format on the modern internet, and Go’s standard library JSON implementation is older than most people think. encoding/json dates from 2009, when the standard library’s flagship data interchange format was written by a small team for a small language, and it has been bolted onto ever since.

But there is a lot to learn from the inside of it: the scanner is a hand-written state machine that most Go programmers have never read, the decoder is a reflection walk with a surprising amount of caching, and the Go 1.28 development tree now contains an experimental replacement that splits “JSON syntax” from “JSON semantics” — a split that is arguably the most important design decision in the whole package.

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

Two passes over your data

json.Unmarshal does something that surprises people: it parses the input twice.

 go
 
 
// src/encoding/json/decode.go:108
func Unmarshal(data []byte, v any) error {
	// Check for well-formedness.
	// Avoids filling out half a data structure
	// before discovering a JSON syntax error.
	var d decodeState
	err := checkValid(data, &d.scan)
	if err != nil {
		return err
	}

	d.init(data)
	return d.unmarshal(v)
}

The first pass is checkValid, which runs the scanner over every byte and throws the result away. The second pass is the actual decode, which runs the scanner again, this time reacting to the events it reports.

Why? The comment says it: “Avoids filling out half a data structure before discovering a JSON syntax error.” Without it, json.Unmarshal into a struct could fill in the first ten fields, hit a syntax error at byte 5000, and leave you with a half-populated struct. With it, the struct is either fully populated or untouched.

The cost is one extra linear pass. For a 1 MB document that is measurable but small compared to the reflection work in the second pass.

 text
 
 
 data []byte
 |
 v
 +----------------------------+
 | PASS 1: checkValid |
 | scanner.step() per byte | --> error? return SyntaxError
 | result: syntax OK or not |
 +----------------------------+
 |
 | (if OK)
 v
 +----------------------------+
 | PASS 2: d.unmarshal(v) |
 | scanner reports events: |
 | scanBeginObject -> d.object(reflect.Value)
 | scanBeginArray -> d.array(reflect.Value)
 | scanBeginLiteral -> d.literalStore(bytes, reflect.Value)
 +----------------------------+
 |
 v
 populated Go value

The v2 experiment replaces the two-layer arrangement with a three-layer one:

 text
 
 
 +---------------------------------------------+
 | encoding/json/jsontext (SYNTAX) |
 | Encoder / Decoder, Token, Value, Kind |
 | state machine, duplicate-name namespaces |
 +---------------------------------------------+
 |
 v
 +---------------------------------------------+
 | encoding/json/v2 (SEMANTICS) |
 | Marshal / Unmarshal / MarshalWrite / ... |
 | per-type arshalers, struct field cache |
 +---------------------------------------------+

The scanner: a state machine with an indirect call per byte

The scanner is the heart of the package, and it opens with an honest assessment of itself:

 go
 
 
// src/encoding/json/scanner.go:9
// JSON value parser state machine.
// Just about at the limit of what is reasonable to write by hand.
// Some parts are a bit tedious, but overall it nicely factors out the
// otherwise common code from the multiple scanning functions
// in this package (Compact, Indent, checkValid, etc).

The “multiple scanning functions” it factors out are json.Valid, json.Compact, json.Indent, and the streaming json.Decoder — all of them need to know where the tokens are, and none of them want to write their own JSON grammar.

The state is a function pointer, and the comment explains why:

 go
 
 
// src/encoding/json/scanner.go:68
type scanner struct {
	// The step is a func to be called to execute the next transition.
	// Also tried using an integer constant and a single func
	// with a switch, but using the func directly was 10% faster
	// on a 64-bit Mac Mini, and it's nicer to read.
	step func(*scanner, byte) int

	// Reached end of top-level value.
	endTop bool

	// Stack of what we're in the middle of - array values, object keys, object values.
	parseState []int

	// Error that happened, if any.
	err error

	// total bytes consumed, updated by decoder.Decode (and deliberately
	// not set to zero by scan.reset)
	bytes int64
}

An indirect call per input byte. That sounds terrible, and it is — but the alternative (a switch on an integer state constant, in one big function) was measured as 10% slower, because the big switch has a mispredicted branch on every byte while the indirect call is a perfectly predictable one, and the states have different code sizes.

The scanner reports events rather than values. The opcodes are:

 go
 
 
// src/encoding/json/scanner.go:111
// These values are returned by the state transition functions
// assigned to scanner.state and the method scanner.eof.
// They give details about the current state of the scan that
// callers might be interested to know about.
// It is okay to ignore the return value of any particular
// call to scanner.state: if one call returns scanError,
// every subsequent call will return scanError too.
const (
	// Continue.
	scanContinue = iota // uninteresting byte
	scanBeginLiteral // end implied by next result != scanContinue
	scanBeginObject // begin object
	scanObjectKey // just finished object key (string)
	scanObjectValue // just finished non-last object value
	scanEndObject // end object (implies scanObjectValue if possible)
	scanBeginArray // begin array
	scanArrayValue // just finished array value
	scanEndArray // end array (implies scanArrayValue if possible)
	scanSkipSpace // space byte; can skip; known to be last "continue" result

	// Stop.
	scanEnd // top-level value ended *before* this byte; known to be first "stop" result
	scanError // hit an error, scanner.err.
)

So the scanner is not a parser in the usual sense. It is a validator that emits events, and the decoder is written as a state machine over those events rather than over bytes. That is the key architectural decision, and it is what lets the same scanner serve Compact, Indent, Valid, the Decoder, and the Unmarshal path.

The grammar itself is the states. Starting a value:

 go
 
 
// src/encoding/json/scanner.go:216
// stateBeginValue is the state at the beginning of the input.
func stateBeginValue(s *scanner, c byte) int {
	if isSpace(c) {
		return scanSkipSpace
	}
	switch c {
	case '{':
		s.step = stateBeginStringOrEmpty
		return s.pushParseState(c, parseObjectKey, scanBeginObject)
	case '[':
		s.step = stateBeginValueOrEmpty
		return s.pushParseState(c, parseArrayValue, scanBeginArray)
	case '"':
		s.step = stateInString
		return scanBeginLiteral
	case '-':
		s.step = stateNeg
		return scanBeginLiteral
	case '0': // beginning of 0.123
		s.step = state0
		return scanBeginLiteral
	case 't': // beginning of true
		s.step = stateT
		return scanBeginLiteral
	case 'f': // beginning of false
		s.step = stateF
		return scanBeginLiteral
	case 'n': // beginning of null
		s.step = stateN
		return scanBeginLiteral
	}
	if '1' <= c && c <= '9' { // beginning of 1234.5
		s.step = state1
		return scanBeginLiteral
	}
	return s.error(c, "looking for beginning of value")
}

and finishing one, where the parseState stack decides what is legal next:

 go
 
 
// src/encoding/json/scanner.go:279
// stateEndValue is the state after completing a value,
// such as after reading `{}` or `true` or `["x"`.
func stateEndValue(s *scanner, c byte) int {
	n := len(s.parseState)
	if n == 0 {
		// Completed top-level before the current byte.
		s.step = stateEndTop
		s.endTop = true
		return stateEndTop(s, c)
	}
	if isSpace(c) {
		s.step = stateEndValue
		return scanSkipSpace
	}
	ps := s.parseState[n-1]
	switch ps {
	case parseObjectKey:
		if c == ':' {
			s.parseState[n-1] = parseObjectValue
			s.step = stateBeginValue
			return scanObjectKey
		}
		return s.error(c, "after object key")
	case parseObjectValue:
		if c == ',' {
			s.parseState[n-1] = parseObjectKey
			s.step = stateBeginString
			return scanObjectValue
		}
		if c == '}' {
			s.popParseState()
			return scanEndObject
		}
		return s.error(c, "after object key:value pair")
	case parseArrayValue:
		if c == ',' {
			s.step = stateBeginValue
			return scanArrayValue
		}
		if c == ']' {
			s.popParseState()
			return scanEndArray
		}
		return s.error(c, "after array element")
	}
	return s.error(c, "")
}

Three parse states — “expecting an object key”, “expecting an object value”, “expecting an array value” — pushed and popped on a stack of ints. And a depth limit, because JSON nesting is a denial-of-service vector:

 go
 
 
// src/encoding/json/scanner.go:146
// This limits the max nesting depth to prevent stack overflow.
// This is permitted by https://tools.ietf.org/html/rfc7159#section-9
const maxNestingDepth = 10000

Ten thousand nested arrays is deep enough to blow the stack of a recursive decoder and shallow enough to permit any legitimate document.

The decoder: a reflection walk

The scanner produced events. The decoder consumes them. decodeState is the whole decoder state:

 go
 
 
// src/encoding/json/decode.go:219
// decodeState represents the state while decoding a JSON value.
type decodeState struct {
	data []byte
	off int // next read offset in data
	opcode int // last read result
	scan scanner
	errorContext *errorContext
	savedError error
	useNumber bool
	disallowUnknownFields bool
}

and value is the dispatcher that turns the scanner’s events into recursive calls:

 go
 
 
// src/encoding/json/decode.go:370
func (d *decodeState) value(v reflect.Value) error {
	switch d.opcode {
	default:
		panic(phasePanicMsg)

	case scanBeginArray:
		if v.IsValid() {
			if err := d.array(v); err != nil {
				return err
			}
		} else {
			d.skip()
		}
		d.scanNext()

	case scanBeginObject:
		if v.IsValid() {
			if err := d.object(v); err != nil {
				return err
			}
		} else {
			d.skip()
		}
		d.scanNext()

	case scanBeginLiteral:
		// All bytes inside literal return scanContinue op code.
		start := d.readIndex()
		d.rescanLiteral()

		if v.IsValid() {
			if err := d.literalStore(d.data[start:d.readIndex()], v, false); err != nil {
				return err
			}
		}
	}
	return nil
}

The v.IsValid() check is the “skip this subtree” mechanism: when the decoder is asked for a value it does not want — an unknown struct field, a value it is going to discard — it passes an invalid reflect.Value and the decoder skips over the whole subtree without allocating anything for it.

literalStore is where a scalar lands in a Go value, and it is a switch on the first byte of the literal:

 go
 
 
// src/encoding/json/decode.go:863
func (d *decodeState) literalStore(item []byte, v reflect.Value, fromQuoted bool) error {
	// Check for unmarshaler.
	if len(item) == 0 {
		// Empty string given.
		d.saveError(fmt.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item, v.Type()))
		return nil
	}
	isNull := item[0] == 'n' // null
	u, ut, pv := indirect(v, isNull)
	if u != nil {
		return u.UnmarshalJSON(item)
	}

 go
 
 
// src/encoding/json/decode.go:941
	case '"': // string
		s, ok := unquoteBytes(item)
		if !ok {
			if fromQuoted {
				return fmt.Errorf("json: invalid use of ,string struct tag, trying to unmarshal %q into %v", item, v.Type())
			}
			panic(phasePanicMsg)
		}
		switch v.Kind() {
		default:
			d.saveError(&UnmarshalTypeError{Value: "string", Type: v.Type(), Offset: int64(d.readIndex())})
		case reflect.Slice:
			if v.Type().Elem().Kind() != reflect.Uint8 {
				d.saveError(&UnmarshalTypeError{Value: "string", Type: v.Type(), Offset: int64(d.readIndex())})
				break
			}
			b := make([]byte, base64.StdEncoding.DecodedLen(len(s)))
			n, err := base64.StdEncoding.Decode(b, s)
			if err != nil {
				d.saveError(err)
				break
			}
			v.SetBytes(b[:n])
		case reflect.String:
			t := string(s)
			if v.Type() == numberType && !isValidNumber(t) {
				return fmt.Errorf("json: invalid number literal, trying to unmarshal %q into Number", item)
			}
			v.SetString(t)
		case reflect.Interface:
			if v.NumMethod() == 0 {
				v.Set(reflect.ValueOf(string(s)))
			} else {
				d.saveError(&UnmarshalTypeError{Value: "string", Type: v.Type(), Offset: int64(d.readIndex())})
			}
		}

So a JSON string can land in a string, in a []byte (base64-decoded), or in an any. That is three completely different behaviours decided by v.Kind(), at run time, per value.

Where the reflection cost is controlled

The expensive part of reflection is not SetString — it is figuring out what to do. Doing that on every value of every document would be unbearable. So Go caches the answer per type.

For the encoder:

 go
 
 
// src/encoding/json/encode.go:373
var encoderCache sync.Map // map[reflect.Type]encoderFunc

func valueEncoder(v reflect.Value) encoderFunc {
	if !v.IsValid() {
		return invalidValueEncoder
	}
	return typeEncoder(v.Type())
}

typeEncoder builds a closure specialised for the type and stores it in a sync.Map. The recursion dance with sync.OnceValue exists to handle recursive types:

 go
 
 
// src/encoding/json/encode.go:382
func typeEncoder(t reflect.Type) encoderFunc {
	if fi, ok := encoderCache.Load(t); ok {
		return fi.(encoderFunc)
	}

	// To deal with recursive types, populate the map with an
	// indirect func before we build it. If the type is recursive,
	// the second lookup for the type will return the indirect func.
	//
	// This indirect func is only used for recursive types,
	// and briefly during racing calls to typeEncoder.
	indirect := sync.OnceValue(func() encoderFunc {
		return newTypeEncoder(t, true)
	})

For the decoder, the equivalent cache is over the struct fields:

 go
 
 
// src/encoding/json/encode.go:705
type structFields struct {
	list []field
	byExactName map[string]*field
	byFoldedName map[string]*field
}

 go
 
 
// src/encoding/json/encode.go:1323
var fieldCache sync.Map // map[reflect.Type]structFields

// cachedTypeFields is like typeFields but uses a cache to avoid repeated work.
func cachedTypeFields(t reflect.Type) structFields {
	if f, ok := fieldCache.Load(t); ok {
		return f.(structFields)
	}
	f, _ := fieldCache.LoadOrStore(t, typeFields(t))
	return f.(structFields)
}

and the lookup at decode time is two map hits:

 go
 
 
// src/encoding/json/decode.go:705
		} else {
			f := fields.byExactName[string(key)]
			if f == nil {
				f = fields.byFoldedName[string(foldName(key))]
			}
			if f != nil {
				subv = v
				destring = f.quoted

First try the exact name, then the case-folded name. That second lookup is why encoding/json matches "Name" to a field named name — a convenience that is also a genuine interoperability hazard, and one of the things the v2 experiment changes.

The encoder side does the same field walk, once per field, following an index path:

 go
 
 
// src/encoding/json/encode.go:711
func (se structEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) {
	next := byte('{')
FieldLoop:
	for i := range se.fields.list {
		f := &se.fields.list[i]

		// Find the nested struct field by following f.index.
		fv := v
		for _, i := range f.index {
			if fv.Kind() == reflect.Pointer {
				if fv.IsNil() {
					continue FieldLoop
				}
				fv = fv.Elem()
			}
			fv = fv.Field(i)
		}

f.index is the path through embedded structs, precomputed once at compile-of-the-type time.

The v2 experiment

The Go 1.28 development tree contains something the 1.x releases never had: a complete second implementation of encoding/json, guarded by a build tag.

The gate is a Go experiment:

 go
 
// src/internal/goexperiment/exp_jsonv2_on.go:1
// Code generated by mkconsts.go. DO NOT EDIT.

//go:build goexperiment.jsonv2

package goexperiment

const JSONv2 = true
const JSONv2Int = 1

Every existing v1 file is excluded when the experiment is on:

 go
 
 
// src/encoding/json/scanner.go:5
//go:build !goexperiment.jsonv2

and replaced by a v2_-prefixed file in the same package, so that json.Marshal and friends keep their old signatures and semantics while being implemented on top of the new machinery:

 go
 
 
// src/encoding/json/v2_decode.go:5
//go:build goexperiment.jsonv2

The new code lives in two packages.

`encoding/json/jsontext`: syntax only

The jsontext package’s doc comment makes the architectural argument better than any blog post could:

 go
 
 
// src/encoding/json/jsontext/doc.go:50
// # Terminology
//
// The terms "encode" and "decode" are used for syntactic functionality
// that is concerned with processing JSON based on its grammar, and
// the terms "marshal" and "unmarshal" are used for semantic functionality
// that determines the meaning of JSON values as Go values and vice versa.
// This package deals with JSON syntax,
// while [encoding/json/v2] deals with JSON semantics.
// The goal is to provide a clear distinction between functionality that
// is purely concerned with encoding versus that of marshaling.
// For example, one can directly encode a stream of JSON tokens without
// needing to marshal a concrete Go value representing them.
// Similarly, one can decode a stream of JSON tokens without
// needing to unmarshal them into a concrete Go value.

Syntax and semantics are separated. jsontext knows what a JSON object is; it does not know what a Go struct is. encoding/json/v2 knows what a Go struct is; it does not re-implement the grammar.

The state machine in jsontext is a different design from v1’s. Where v1 used a stack of ints and one function per state, jsontext packs the entire per-level state into a single 64-bit word:

 go
 
 
// src/encoding/json/jsontext/state.go:430
// stateEntry encodes several artifacts within a single unsigned integer:
// - whether this represents a JSON object or array,
// - whether this object should check for duplicate names, and
// - how many elements are in this JSON object or array.
type stateEntry uint64

const (
	// The type mask (1 bit) records whether this is a JSON object or array.
	stateTypeMask stateEntry = 0x8000_0000_0000_0000
	stateTypeObject stateEntry = 0x8000_0000_0000_0000
	stateTypeArray stateEntry = 0x0000_0000_0000_0000

	// The name check mask (2 bits) records whether to update
	// the namespaces for the current JSON object and
	// whether the namespace is valid.
	stateNamespaceMask stateEntry = 0x6000_0000_0000_0000
	stateDisableNamespace stateEntry = 0x4000_0000_0000_0000
	stateInvalidNamespace stateEntry = 0x2000_0000_0000_0000

	// The count mask (61 bits) records the number of elements.
	stateCountMask stateEntry = 0x1fff_ffff_ffff_ffff
	stateCountLSBMask stateEntry = 0x0000_0000_0000_0001
	stateCountOdd stateEntry = 0x0000_0000_0000_0001
	stateCountEven stateEntry = 0x0000_0000_0000_0000
)

One bit for object-or-array, two bits for the duplicate-name namespace state, sixty-one bits for the element count. And here is the lovely part: the low bit of the count doubles as the “am I expecting a name or a value?” flag, so the parser does not need a separate bit for it.

 go
 
 
// src/encoding/json/jsontext/state.go:472
// NeedObjectName reports whether the next token must be a JSON string,
// which is necessary for JSON object names.
func (e stateEntry) NeedObjectName() bool {
	return e&(stateTypeMask|stateCountLSBMask) == stateTypeObject|stateCountEven
}

// needImplicitColon reports whether a colon should occur next,
// which always occurs after JSON object names.
func (e stateEntry) needImplicitColon() bool {
	return e.needObjectValue()
}

// needObjectValue reports whether the next token must be a JSON value,
// which is necessary after every JSON object name.
func (e stateEntry) needObjectValue() bool {
	return e&(stateTypeMask|stateCountLSBMask) == stateTypeObject|stateCountOdd
}

“Expecting a name” and “expecting a value” are the same bit with different polarity, so the parity of the element count is the parser state. That is the kind of trick that only shows up once you decide to make the state machine word-sized.

The tokenizer itself is a recursive descent over a byte buffer, and it dispatches on the first byte of the value, which is enough to identify the kind:

 go
 
 
// src/encoding/json/jsontext/decode.go:861
func (d *decoderState) consumeValue(flags *jsonwire.ValueFlags, pos, depth int) (newPos int, err error) {
	for {
		var n int
		var err error
		switch next := Kind(d.buf[pos]).normalize(); next {
		case 'n':
			if n = jsonwire.ConsumeNull(d.buf[pos:]); n == 0 {
				n, err = jsonwire.ConsumeLiteral(d.buf[pos:], "null")
			}
		case 'f':
			if n = jsonwire.ConsumeFalse(d.buf[pos:]); n == 0 {
				n, err = jsonwire.ConsumeLiteral(d.buf[pos:], "false")
			}
		case 't':
			if n = jsonwire.ConsumeTrue(d.buf[pos:]); n == 0 {
				n, err = jsonwire.ConsumeLiteral(d.buf[pos:], "true")
			}
		case '"':
			if n = jsonwire.ConsumeSimpleString(d.buf[pos:]); n == 0 {
				return d.consumeString(flags, pos)
			}
		case '0':
			// NOTE: Since JSON numbers are not self-terminating,
			// we need to make sure that the next byte is not part of a number.
			if n = jsonwire.ConsumeSimpleNumber(d.buf[pos:]); n == 0 || d.needMore(pos+n) {
				return d.consumeNumber(pos)
			}
		case '{':
			return d.consumeObject(flags, pos, depth)
		case '[':
			return d.consumeArray(flags, pos, depth)

And the token kinds are just bytes:

 go
 
 
// src/encoding/json/jsontext/token.go:620
// A Kind represents the kind of a JSON token.
//
// A Kind is a single byte, which is conveniently the first byte of that
// kind's symbol in the grammar (except for numbers, which are always represented
// with '0').
type Kind byte

const (
	KindInvalid Kind = 0 // invalid kind
	KindNull Kind = 'n' // null
	KindFalse Kind = 'f' // false
	KindTrue Kind = 't' // true
	KindString Kind = '"' // string
	KindNumber Kind = '0' // number
	KindBeginObject Kind = '{' // begin object
	KindEndObject Kind = '}' // end object
	KindBeginArray Kind = '[' // begin array
	KindEndArray Kind = ']' // end array
)

`encoding/json/v2`: semantics, and streaming

The v2 package offers the same three shapes of operation as the old json.Encoder/json.Decoder, but as plain functions with a consistent naming scheme — and crucially, without the []byte round trip:

 go
 
 
// src/encoding/json/v2/arshal.go:175
// MarshalWrite serializes a Go value into an [io.Writer] according to the provided
// marshal and encode options (while ignoring unmarshal or decode options).
// It does not terminate the output with a newline.
// See [Marshal] for details about the conversion of a Go value into JSON.
func MarshalWrite(out io.Writer, in any, opts ...Options) (err error) {
	enc := export.GetStreamingEncoder(out, opts...)
	defer export.PutStreamingEncoder(enc)
	xe := export.Encoder(enc)
	xe.Flags.Set(jsonflags.OmitTopLevelNewline | 1)
	err = marshalEncode(enc, in, &xe.Struct)
	if err != nil && xe.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
		return internal.TransformMarshalError(in, err)
	}
	return err
}

 go
 
 
// src/encoding/json/v2/arshal.go:191
// MarshalEncode serializes a Go value into an [jsontext.Encoder] according to
// the provided marshal or encode options (while ignoring unmarshal or decode options).
// The options provided take precedence over options already applied on
// the [jsontext.Encoder] and only apply for the duration of the marshal call.
//
// See [Marshal] for details about the conversion of a Go value into JSON.
func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) (err error) {

 go
 
 
// src/encoding/json/v2/arshal.go:397
// UnmarshalRead deserializes a Go value from an [io.Reader] according to the
// provided unmarshal and decode options (while ignoring marshal or encode options).
// The input must be a single JSON value with optional whitespace interspersed.
// It consumes the entirety of [io.Reader] until [io.EOF] is encountered,
// without reporting an error for EOF. The output must be a non-nil pointer.
// See [Unmarshal] for details about the conversion of JSON into a Go value.
func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error) {

So the v2 API is: Marshal (into []byte), MarshalWrite (into an io.Writer), MarshalEncode (into a jsontext.Encoder), and the mirror Unmarshal, UnmarshalRead, UnmarshalDecode. The io.Writer and io.Reader variants never materialise the whole JSON document in memory — that is the performance story, and it is a real one for large payloads.

The per-type work is still cached, with a sync.Once so that concurrent first-use of a type does not race:

 go
 
 
// src/encoding/json/v2/fields.go:80
type structFieldsCacheEntry struct {
	once sync.Once
	fields structFields
	err *SemanticError
}

var structFieldsCache sync.Map // map[reflect.Type]*structFieldsCacheEntry

func lookupStructFields(t reflect.Type) (*structFields, *SemanticError) {
	entry, _ := structFieldsCache.LoadOrStore(t, new(structFieldsCacheEntry))
	cached := entry.(*structFieldsCacheEntry)
	cached.once.Do(func() {
		cached.fields, cached.err = makeStructFields(t)
	})
	return &cached.fields, cached.err
}

The behaviour changes

The v2 doc is unusually candid about where the two packages disagree, and it is worth reading in full. The summary:

Invalid UTF-8: v1 replaces it with U+FFFD; v2 rejects it.
Duplicate names: v1 allows them; v2 rejects them by default.
Case-insensitive name matching: v1 does it; v2 is strict by default.
Unknown members: both ignore them by default.

 go
 
 
// src/encoding/json/v2/doc.go:175
// The v1 [encoding/json] and [encoding/json/v2] packages
// interpret some inputs in different ways. In particular:
//
// - The standard specifies that JSON must be encoded using UTF-8.
// By default, v1 replaces invalid bytes of UTF-8 in JSON strings
// with the Unicode replacement character,
// while v2 rejects inputs with invalid UTF-8.
// To change the default, specify the [jsontext.AllowInvalidUTF8] option.
// The replacement of invalid UTF-8 is a form of data corruption
// that alters the precise meaning of strings.
//
// - The standard does not specify a particular behavior when
// duplicate names are encountered within a JSON object,
// which means that different implementations may behave differently.
// By default, v1 allows for the presence of duplicate names,
// while v2 rejects duplicate names.
// To change the default, specify the [jsontext.AllowDuplicateNames] option.

Each of these is a security decision, not a style decision. The v1 behaviours are all “be liberal in what you accept”, and liberal parsing is how two implementations end up disagreeing about what a document means.

Trade-offs

What the v1 design buys: a stable, universally understood API, one implementation that has been fuzzed for fifteen years, and a scanner that is shared by five different entry points.

What it costs:

Two passes over the input. Unmarshal scans the document twice.
An indirect call per byte. The scanner’s function-pointer design costs a branch misprediction budget on every byte of every document.
Case-insensitive field matching. byFoldedName means {"name": ...} populates a field called Name. It is convenient and it is a source of interoperability bugs.
Everything goes through reflect. Even []int is decoded by reflection, with a switch v.Kind() per element.

What v2 buys:

Streaming. MarshalWrite and UnmarshalRead never hold the whole document in memory.
A real separation of syntax and semantics. jsontext is usable on its own for token-level processing, and encoding/json/v2 is a set of semantic rules on top of it.
Stricter, safer defaults. Duplicate names, invalid UTF-8 and ambiguous case matching are all rejected rather than silently accepted.

What v2 costs:

It is an experiment. GOEXPERIMENT=jsonv2 is not a supported configuration for production, and the API is still moving.
Reflection is still there. The per-type work is cached, but the per-value walk is still a reflect.Value walk. v2 is not “no reflection”; it is “less reflection, cached better”.
Behaviour differences. Code that relies on v1’s liberal parsing will break, which is the point but also the cost.

Caveats

json.Unmarshal twice is the price of safety. If you control the input and it is guaranteed well-formed, the first pass is wasted work. But you cannot skip it without reimplementing the parser, and the alternative — a half-filled struct on a syntax error — is worse.

Field name matching is case-insensitive in v1. encoding/json will happily populate a field UserID from the key userid. If you have two fields that differ only in case, v1 picks one of them by an implementation-defined rule.

Numbers become float64 by default. Decoding into an any gives you float64, so a 64-bit integer above 2^53 loses precision. Use json.Number (via Decoder.UseNumber()) or decode into a concrete type.

The ,string tag option is a decoding hack. It means “this field is a number in JSON but a string in Go”, and it applies to the top level of the field only.

jsontext and encoding/json/v2 are only in the tree under the experiment. If you are reading this on Go 1.25, none of it exists. And even on Go 1.28, GOEXPERIMENT=jsonv2 changes the behaviour of the v1 encoding/json package too, because the v2_*.go files replace the old ones in the same package.

Do not benchmark v1 and v2 by swapping the import path. The v1 package under the experiment is a compatibility shim over the new machinery; the timings you get are not the timings of the old implementation.

Wrapping up

The one thing to remember: encoding/json separates scanning from decoding — a hand-written byte-at-a-time state machine that only validates and reports events, and a reflection-driven walker that turns those events into Go values, with the expensive per-type analysis cached in sync.Maps.

The part people get wrong: thinking encoding/json is slow because of reflection. The reflection is not the bottleneck in most programs; the double parse and the per-byte indirect call are, and both are exactly what the v2 experiment is designed to remove.

What to go do about it: if you control the shape of your payloads, use json.Marshal on a struct with concrete field types and skip any entirely — that removes the interface allocations and the switch v.Kind() per value. If you are streaming large documents, look at json.NewEncoder today and at MarshalWrite/UnmarshalRead when the v2 experiment lands.

How Go's io.Copy Avoids Copying: sendfile, splice and the Copy Protocol

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

TL;DR: io.Copy(dst, src) does not have a loop in it that reads into a buffer and writes it out — not in the common case. It first asks whether src implements io.WriterTo or dst implements io.ReaderFrom, and if either does, it delegates the whole operation. *net.TCPConn implements both, using Linux sendfile and splice to move bytes between a file descriptor and a socket entirely inside the kernel. No user-space buffer is allocated, and no memcpy happens at all.

There is a famous Go performance folklore about io.Copy being slower than a manual read/write loop, because io.Copy allocates a 32 KB buffer. That folklore was true once and is now mostly wrong — and understanding why is a good tour of Go’s “the fast path is a method call” philosophy.

The copy protocol

 go
 
 
// src/io/io.go:405
// copyBuffer is the actual implementation of Copy and CopyBuffer.
// if buf is nil, one is allocated.
func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
	// If the reader has a WriteTo method, use it to do the copy.
	// Avoids an allocation and a copy.
	if wt, ok := src.(WriterTo); ok {
		return wt.WriteTo(dst)
	}
	// Similarly, if the writer has a ReadFrom method, use it to do the copy.
	if rf, ok := dst.(ReaderFrom); ok {
		return rf.ReadFrom(src)
	}

Two interface assertions, and a comment that says exactly what the optimisation buys: “Avoids an allocation and a copy.”

This is the whole trick. io.Copy is a protocol, not an implementation. The standard library defines two optional interfaces:

 go
 
 
// src/io/io.go:193
// WriterTo is the interface that wraps the WriteTo method.
//
// WriteTo writes data to w until there's no more data to write or
// when an error occurs. The return value n is the number of bytes
// written. Any error encountered during the write is also returned.
//
// The Copy function uses WriterTo if available.
type WriterTo interface {
	WriteTo(w Writer) (n int64, err error)
}

 go
 
 
// src/io/io.go:182
// ReaderFrom is the interface that wraps the ReadFrom method.
//
// ReadFrom reads data from r until EOF or error.
// The return value n is the number of bytes read.
// Any error except EOF encountered during the read is also returned.
//
// The [Copy] function uses [ReaderFrom] if available.
type ReaderFrom interface {
	ReadFrom(r Reader) (n int64, err error)
}

And io.Copy honours them. The order matters: WriterTo on the source wins over ReaderFrom on the destination. That is not arbitrary — the source’s WriteTo knows how to move its data most efficiently, and the destination’s ReadFrom knows how to receive it most efficiently. The source’s opinion is taken first because in practice the source is the more constrained side (a file, a socket) and the destination is more generic.

Who implements these?

A surprising number of standard library types do:

Type	Implements	Mechanism
`*bytes.Buffer`	`WriterTo`, `ReaderFrom`	`copy` on the underlying slice
`*bytes.Reader`	`WriterTo`	`copy` on the underlying slice
`*strings.Reader`	`WriterTo`	`copy` on the string
`*os.File`	`WriteTo` (via `io.Copy` on `*bytes.Reader`/file)	`sendfile` on Linux
`*net.TCPConn`	`WriteTo`, `ReadFrom`	`splice`, `sendfile`
`*net.UnixConn`	`WriteTo`, `ReadFrom`	`splice`
`*net/http.response`	`ReadFrom`	`sendfile` for file bodies

So io.Copy(dst, src) where src is an *os.File and dst is a *net.TCPConn never touches user space at all.

The TCP path: splice first, then sendfile

 go
 
 
// src/net/tcpsock_posix.go:47
func (c *TCPConn) readFrom(r io.Reader) (int64, error) {
	if n, err, handled := spliceFrom(c.fd, r); handled {
		return n, err
	}
	if n, err, handled := sendFile(c.fd, r); handled {
		return n, err
	}
	return genericReadFrom(c, r)
}

Three tiers, tried in order:

spliceFrom — pipe-to-pipe transfer between two sockets. Only works if the source is a TCP or Unix socket.
sendFile — file-to-socket. Only works if the source is a file descriptor.
genericReadFrom — the ordinary buffered copy.

The handled flag is the interesting part. It is not “did it succeed” — it is “did it do any work”. A partial success still returns handled == true, so the caller knows not to retry with the generic path and duplicate bytes.

Splice: moving bytes between sockets

splice is a Linux syscall that moves data between a pipe and a socket without a user-space buffer. But splice cannot copy socket-to-socket directly, so Go uses a pipe as a shuttle:

 go
 
 
// src/net/splice_linux.go:14
// spliceFrom transfers data from r to c using the splice system call to minimize
// copies from and to userspace. c must be a TCP connection.
// Currently, spliceFrom is only enabled if r is a TCP or a stream-oriented Unix connection.
//
// If spliceFrom returns handled == false, it has performed no work.
func spliceFrom(c *netFD, r io.Reader) (written int64, err error, handled bool) {
	var remain int64 = 1<<63 - 1 // by default, copy until EOF
	lr, ok := r.(*io.LimitedReader)
	if ok {
		remain, r = lr.N, lr.R
		if remain <= 0 {
			return 0, nil, true
		}
	}

	var s *netFD
	switch v := r.(type) {
	case *TCPConn:
		s = v.fd
	case tcpConnWithoutWriteTo:
		s = v.fd
	case *UnixConn:
		if v.fd.net != "unix" {
			return 0, nil, false
		}
		s = v.fd
	default:
		return 0, nil, false
	}

	written, handled, err = pollSplice(&c.pfd, &s.pfd, remain)
	if lr != nil {
		lr.N -= written
	}
	return written, wrapSyscallError("splice", err), handled
}

The type switch is the guard: only sockets can be spliced. Note the tcpConnWithoutWriteTo case — that is a trick to avoid infinite recursion (we will come back to it).

The actual mechanism is in internal/poll:

 go
 
 
// src/internal/poll/splice_linux.go:33
func Splice(dst, src *FD, remain int64) (written int64, handled bool, err error) {
	p, err := getPipe()
	if err != nil {
		return 0, false, err
	}
	defer putPipe(p)
	var inPipe, n int
	for err == nil && remain > 0 {
		max := maxSpliceSize
		if int64(max) > remain {
			max = int(remain)
		}
		inPipe, err = spliceDrain(p.wfd, src, max)
		// The operation is considered handled if splice returns no
		// error, or an error other than EINVAL. An EINVAL means the
		// kernel does not support splice for the socket type of src.
		// The failed syscall does not consume any data so it is safe
		// to fall back to a generic copy.
		//
		// spliceDrain should never return EAGAIN, so if err != nil,
		// Splice cannot continue.
		//
		// If inPipe == 0 && err == nil, src is at EOF, and the
		// transfer is complete.
		handled = handled || (err != syscall.EINVAL)
		if err != nil || inPipe == 0 {
			break
		}
		p.data += inPipe

		n, err = splicePump(dst, p.rfd, inPipe)
		if n > 0 {
			written += int64(n)
			remain -= int64(n)
			p.data -= n
		}
	}

Read the handled comment carefully — it is the kind of reasoning that only appears in code that has been debugged in production:

The operation is considered handled if splice returns no error, or an error other than EINVAL. An EINVAL means the kernel does not support splice for the socket type of src. The failed syscall does not consume any data so it is safe to fall back to a generic copy.

So EINVAL is the only error that permits a fallback, and the fallback is safe precisely because the failed call moved nothing. Every other error is fatal, because some data may have been consumed and a generic copy would duplicate it.

The pipe itself is pooled — getPipe/putPipe — because creating a pipe is a syscall and this is a hot path.

And spliceDrain has an invariant worth reading:

 go
 
 
// src/internal/poll/splice_linux.go:76
// spliceDrain moves data from a socket to a pipe.
//
// Invariant: when entering spliceDrain, the pipe is empty. It is either in its
// initial state, or splicePump has emptied it previously.
//
// Given this, spliceDrain can reasonably assume that the pipe is ready for
// writing, so if splice returns EAGAIN, it must be because the socket is not
// ready for reading.

That invariant is what lets the code skip a poll before every splice: if the pipe is known empty, the kernel will not block on the write side, so EAGAIN can only mean the socket was not ready.

sendfile: file to socket

For a file source, sendfile does the whole job in one syscall — the kernel moves pages from the page cache straight into the socket, with no copy into user space.

 go
 
 
// src/net/sendfile.go:17
// sendFile copies the contents of r to c using the sendfile
// system call to minimize copies.
//
// if handled == true, sendFile returns the number (potentially zero) of bytes
// copied and any non-EOF error.
//
// if handled == false, sendFile performed no work.
func sendFile(c *netFD, r io.Reader) (written int64, err error, handled bool) {
	if !supportsSendfile() {
		return 0, nil, false
	}
	var remain int64 = 0 // 0 writes the entire file
	lr, ok := r.(*io.LimitedReader)
	if ok {
		remain, r = lr.N, lr.R
		if remain <= 0 {
			return 0, nil, true
		}
	}
	// r might be an *os.File or an os.fileWithoutWriteTo.
	// Type assert to an interface rather than *os.File directly to handle the latter case.
	f, ok := r.(syscall.Conn)
	if !ok {
		return 0, nil, false
	}

	sc, err := f.SyscallConn()
	if err != nil {
		return 0, nil, false
	}

	var werr error
	err = sc.Read(func(fd uintptr) bool {
		written, werr, handled = poll.SendFile(&c.pfd, fd, remain)
		return true
	})

Note the type assertion: r.(syscall.Conn), not r.(*os.File). The comment explains why:

r might be an *os.File or an os.fileWithoutWriteTo. Type assert to an interface rather than *os.File directly to handle the latter case.

os.fileWithoutWriteTo is a wrapper that hides the WriteTo method — because os.File.WriteTo would otherwise call io.Copy, which would call TCPConn.ReadFrom, which would call sendFile again, and around we go. The sc.Read(func(fd uintptr) bool {...}) pattern is syscall.RawConn, which gives the code access to the raw file descriptor while holding the runtime lock for that descriptor — which is exactly what you need to call sendfile safely.

The platform differences are handled in internal/poll:

 go
 
 
// src/internal/poll/sendfile_unix.go:30
func SendFile(dstFD *FD, src uintptr, size int64) (n int64, err error, handled bool) {
	if goos := runtime.GOOS; goos == "linux" || goos == "android" {
		// Linux's sendfile doesn't require any setup:
		// It sends from the current position of the source file and
		// updates the position of the source after sending.
		return sendFile(dstFD, int(src), nil, size)
	}

	// Non-Linux sendfile implementations don't use the current position of the source file,
	// so we need to look up the position, pass it explicitly, and adjust it after
	// sendfile returns.
	start, err := ignoringEINTR2(func() (int64, error) {
		return syscall.Seek(int(src), 0, io.SeekCurrent)
	})
	if err != nil {
		return 0, err, false
	}

	pos := start
	n, err, handled = sendFile(dstFD, int(src), &pos, size)
	if n > 0 {
		ignoringEINTR2(func() (int64, error) {
			return syscall.Seek(int(src), start+n, io.SeekStart)
		})
	}
	return n, err, handled
}

Linux’s sendfile takes a nil offset and updates the file position itself. The BSDs want an explicit offset and do not update it, so Go has to Seek before and after. That is a syscall per copy on the BSDs — a cost the Linux path avoids entirely.

The recursion problem, and how Go solves it

There is a genuine cycle here:

io.Copy(dst, src) calls src.WriteTo(dst) if src has one.
*os.File.WriteTo calls io.Copy(dst, f).
*net.TCPConn.ReadFrom calls sendFile, which is fine.
But *net.TCPConn.WriteTo calls io.Copy(w, c) — and if w is something with a ReadFrom, that calls back into c.ReadFrom…

Go breaks the cycle with wrapper types that hide the offending method:

 go
 
 
// src/net/net.go:778
// noWriteTo can be embedded alongside another type to
// hide the WriteTo method of that other type.
type noWriteTo struct{}

// WriteTo hides another WriteTo method.
// It should never be called.
func (noWriteTo) WriteTo(io.Writer) (int64, error) {
	panic("can't happen")
}

 go
 
 
// src/net/net.go:788
// tcpConnWithoutWriteTo implements all the methods of *TCPConn other
// than WriteTo. This is used to permit WriteTo to call io.Copy
// without leading to a recursive call to WriteTo.
type tcpConnWithoutWriteTo struct {
	noWriteTo
	*TCPConn
}

And the fallback implementations use the other wrapper:

 go
 
 
// src/net/net.go:773
func genericReadFrom(c *TCPConn, r io.Reader) (n int64, err error) {
	// Use wrapper to hide existing r.ReadFrom from io.Copy.
	return io.Copy(tcpConnWithoutReadFrom{TCPConn: c}, r)
}

 go
 
 
// src/net/net.go:796
// Fallback implementation of io.WriterTo's WriteTo, when zero-copy isn't applicable.
func genericWriteTo(c *TCPConn, w io.Writer) (n int64, err error) {
	// Use wrapper to hide existing w.WriteTo from io.Copy.
	return io.Copy(w, tcpConnWithoutWriteTo{TCPConn: c})
}

The pattern is elegant: embed a struct that implements the hidden method with a panic("can't happen"), and the interface assertion in io.Copy fails because the promoted method is shadowed.

The generic fallback

If none of the fast paths apply, io.Copy falls back to a plain read/write loop with a 32 KB buffer:

 go
 
 
// src/io/io.go:417
	if buf == nil {
		size := 32 * 1024
		if l, ok := src.(*LimitedReader); ok && int64(size) > l.N {
			if l.N < 1 {
				size = 1
			} else {
				size = int(l.N)
			}
		}
		buf = make([]byte, size)
	}

The LimitedReader special case is a small nicety: if you are copying at most 100 bytes, you get a 100-byte buffer rather than a 32 KB one.

And io.CopyBuffer lets you supply your own:

 go
 
 
// src/io/io.go:391
// CopyBuffer is identical to Copy except that it stages through the
// provided buffer (if one is required) rather than allocating a
// temporary one. If buf is nil, one is allocated; otherwise if it has
// zero length, CopyBuffer panics.
//
// If either src implements [WriterTo] or dst implements [ReaderFrom],
// buf will not be used to perform the copy.

The last sentence is the caveat that trips people up: your buffer is ignored if a fast path applies. If you are benchmarking with CopyBuffer and wondering why your buffer is not being used, that is why.

`net/http` uses this too

The HTTP server’s response writer implements ReadFrom, which is why serving a static file is fast:

 go
 
 
// src/net/http/server.go
func (w *response) ReadFrom(src io.Reader) (n int64, err error) {

The server checks whether the source is a file and, if so, uses sendfile to push it straight to the socket. That is why http.FileServer can saturate a 10 Gbit link without the Go process ever touching the payload bytes.

Trade-offs

Interface assertions cost a little. Two type assertions per io.Copy call. In a tight loop calling io.Copy on non-file, non-socket readers, that is pure overhead — the assertions will fail and you pay for the buffer anyway.

The fast path is not always applicable. sendfile needs a real file descriptor. A bytes.Reader over a []byte is not one, and neither is a gzip.Reader wrapping a file. If your data is compressed in flight, the zero-copy path is gone.

Partial success is possible and handled. A sendfile that transfers half the file and then hits EAGAIN returns handled == true with a partial count. The caller must not retry from the start.

io.CopyBuffer’s buffer may be ignored. Documented, but surprising.

The handled flag is subtle. It means “did any work happen”, not “did it fully succeed”. Reading it as “did it succeed” will produce duplicated data.

Linux is the best-supported platform. sendfile on Linux needs no offset bookkeeping; the BSDs need an extra Seek before and after.

Caveats

os.File.WriteTo in Go 1.22+ is deliberately limited. The os.fileWithoutWriteTo wrapper exists because os.File’s own WriteTo would recurse. If you see WriteTo not being used on a file, that is intentional.

The splice path only works socket-to-socket. A file source goes down the sendfile path, not the splice path.

splice needs a pipe, and pipes are a limited resource. Go pools them (getPipe/putPipe), but under enough concurrency you can still hit the per-process pipe limit.

None of this applies to io.ReadAll. io.ReadAll has no fast path; it always grows a buffer.

http.ResponseWriter and io.Writer are different. Wrapping a *net.TCPConn in bufio.Writer hides the ReadFrom method, because the wrapper does not implement it. If you buffer your writes, you lose the zero-copy path.

Wrapping up

The one thing to remember: io.Copy is a dispatch, not a loop. The first thing it does is check whether the source or destination can do the transfer themselves, and if so it gets out of the way. The actual copying is somebody else’s problem, and for files and sockets that somebody is the kernel.

The part people get wrong: the handled flag. It means “did any work happen”, not “did it succeed”. Falling back to a generic copy after a partial sendfile duplicates bytes. The code is careful about this (EINVAL is the only error that permits a fallback, because it consumes no data), and your code has to be careful too if you ever call the net package’s internal helpers.

What to go do about it: if you are serving files over HTTP or proxying them, check that you are not accidentally wrapping the connection in a bufio.Writer — that hides ReadFrom and silently gives up the zero-copy path. And if you are copying from a *os.File to a *net.TCPConn by hand, just call io.Copy and let the protocol do its job.

How Go's GC Decides When to Collect: Heap Goal, Pacing and Mark Assist

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

TL;DR: Go’s GC does not collect when a counter says so; it collects when the heap goal says so. The goal is live heap × (1 + GOGC/100), capped by GOMEMLIMIT. The trigger is a point below the goal, computed from how fast you allocate versus how fast the collector can scan. Between trigger and goal, 25% of GOMAXPROCS marks in the background, and any mutator that allocates faster than the collector scans accumulates an assist debt it must repay by doing marking work itself.

Every garbage collector has to answer the same question: when do I collect? Some answer it with a timer. Some answer it with a free-list threshold. Go answers it with arithmetic on the size of the live heap, and the arithmetic is subtle enough that it deserves to be taken apart piece by piece.

The code lives in src/runtime/mgcpacer.go, and it is the same machinery behind every number you have ever seen in GODEBUG=gctrace=1 output.

The knobs

There are two user-facing knobs, and they do different jobs.

GOGC is a multiplier on the live heap. GOGC=100 means roughly “collect when the heap has grown to twice the live heap” — roughly, because stacks and globals count too (see below). GOGC=off disables automatic collection entirely.

GOMEMLIMIT is a soft limit on total memory used by the runtime. It is a limit, not a target: the collector will do whatever it takes to get under it, including running GC more often than GOGC would suggest.

The controller holds both, plus a pile of derived state:

 go
 
 
// src/runtime/mgcpacer.go:92
type gcControllerState struct {
	// Initialized from GOGC. GOGC=off means no GC.
	gcPercent atomic.Int32

	// memoryLimit is the soft memory limit in bytes.
	//
	// Initialized from GOMEMLIMIT. GOMEMLIMIT=off is equivalent to MaxInt64
	// which means no soft memory limit in practice.
	//
	// This is an int64 instead of a uint64 to more easily maintain parity with
	// the SetMemoryLimit API, which sets a maximum at MaxInt64. This value
	// should never be negative.
	memoryLimit atomic.Int64

	// heapMinimum is the minimum heap size at which to trigger GC.
	// For small heaps, this overrides the usual GOGC*live set rule.
	//
	// When there is a very small live set but a lot of allocation, simply
	// collecting when the heap reaches GOGC*live results in many GC
	// cycles and high total per-GC overhead. This minimum amortizes this
	// per-GC overhead while keeping the heap reasonably small.
	//
	// During initialization this is set to 4MB*GOGC/100. In the case of
	// GOGC==0, this will set heapMinimum to 0, resulting in constant
	// collection even when the heap size is small, which is useful for
	// debugging.
	heapMinimum uint64

The heap goal

The goal is the size the heap is allowed to reach by the end of the current cycle. It is computed at the end of the previous cycle, in commit:

 go
 
 
// src/runtime/mgcpacer.go:1290
	// Compute the next GC goal, which is when the allocated heap
	// has grown by GOGC/100 over where it started the last cycle,
	// plus additional runway for non-heap sources of GC work.
	gcPercentHeapGoal := ^uint64(0)
	if gcPercent := c.gcPercent.Load(); gcPercent >= 0 {
		gcPercentHeapGoal = c.heapMarked + (c.heapMarked+c.lastStackScan.Load()+c.globalsScan.Load())*uint64(gcPercent)/100
	}
	// Apply the minimum heap size here. It's defined in terms of gcPercent
	// and is only updated by functions that call commit.
	if gcPercentHeapGoal < c.heapMinimum {
		gcPercentHeapGoal = c.heapMinimum
	}
	c.gcPercentHeapGoal.Store(gcPercentHeapGoal)

Read that arithmetic carefully. heapMarked is the live heap as measured by the last mark phase. The goal is:

text

 heapMarked + (heapMarked + stacks + globals) * GOGC/100

The stacks and globals are in there because scanning them is work the collector has to do, and that work has to be paid for by some amount of allocation. A program with 100 MB of live heap and 20 MB of scannable stacks is not really running with a 100 MB live set; it is running with a 120 MB one, and at GOGC=100 the goal lands at 100 + (100 + 20) = 220 MB, not 200.

Then heapGoalInternal picks the smaller of the GOGC-based goal and the memory-limit-based goal, with a couple of adjustments:

 go
 
 
// src/runtime/mgcpacer.go:1000
func (c *gcControllerState) heapGoalInternal() (goal, minTrigger uint64) {
	// Start with the goal calculated for gcPercent.
	goal = c.gcPercentHeapGoal.Load()

	// Check if the memory-limit-based goal is smaller, and if so, pick that.
	if newGoal := c.memoryLimitHeapGoal(); newGoal < goal {
		goal = newGoal
	} else {

The interesting part is the else branch: when the memory limit is not the binding constraint, the goal is nudged upward to guarantee the sweeper has runway, and to guarantee a minimum distance between where the GC triggered and where it will finish.

The trigger

The trigger is where the GC actually starts. It is always strictly below the goal, and the gap between them is the “runway” — the amount of allocation the program can do between the collector starting and finishing.

 go
 
 
// src/runtime/mgcpacer.go:1239
	// Compute the trigger from our bounds and the runway stored by commit.
	var trigger uint64
	runway := c.runway.Load()
	if runway > goal {
		trigger = minTrigger
	} else {
		trigger = goal - runway
	}
	trigger = max(trigger, minTrigger)
	trigger = min(trigger, maxTrigger)
	if trigger > goal {
		print("trigger=", trigger, " heapGoal=", goal, "\n")
		print("minTrigger=", minTrigger, " maxTrigger=", maxTrigger, "\n")
		throw("produced a trigger greater than the heap goal")
	}
	return trigger, goal

The runway itself is an estimate. The controller measures, each cycle, the ratio between the bytes your program allocates per unit of CPU time and the bytes the collector scans per unit of CPU time — the “cons/mark” ratio — and multiplies it by the expected scan work to figure out how many bytes you will allocate while the collector is busy.

The bounds minTrigger and maxTrigger keep the trigger inside a sane window:

 go
 
 
// src/runtime/mgcpacer.go:1160
const (
	// These constants determine the bounds on the GC trigger as a fraction
	// of heap bytes allocated between the start of a GC (heapLive == heapMarked)
	// and the end of a GC (heapLive == heapGoal).
	//
	// The constants are obscured in this way for efficiency. The denominator
	// of the fraction is always a power-of-two for a quick division, so that
	// the numerator is a single constant integer multiplication.
	triggerRatioDen = 64

	// The minimum trigger constant was chosen empirically: given a sufficiently
	// fast/scalable allocator with 48 Ps that could drive the trigger ratio
	// to <0.05, this constant causes applications to retain the same peak
	// RSS compared to not having this allocator.
	minTriggerRatioNum = 45 // ~0.7

	// The maximum trigger constant is chosen somewhat arbitrarily, but the
	// current constant has served us well over the years.
	maxTriggerRatioNum = 61 // ~0.95
)

So the trigger sits between roughly 70% and 95% of the way from the live heap to the goal. Too early and you are allocating black in a nearly-permanent GC, which grows RSS; too late and there is no runway left when the collector needs it.

The phases

The GC moves through three phases, and the write barrier’s behaviour is a function of them:

 go
 
 
// src/runtime/mgc.go:250
const (
	_GCoff = iota // GC not running; sweeping in background, write barrier disabled
	_GCmark // GC marking roots and workbufs: allocate black, write barrier ENABLED
	_GCmarktermination // GC mark termination: allocate black, P's help GC, write barrier ENABLED
)

There is also a separate axis for how concurrent the cycle is:

 go
 
 
// src/runtime/mgc.go:667
// gcMode indicates how concurrent a GC cycle should be.
type gcMode int

const (
	gcBackgroundMode gcMode = iota // concurrent GC and sweep
	gcForceMode // stop-the-world GC now, concurrent sweep
	gcForceBlockMode // stop-the-world GC now and STW sweep (forced by user)
)

and a separate axis for what caused the cycle:

 go
 
 
// src/runtime/mgc.go:686
const (
	// gcTriggerHeap indicates that a cycle should be started when
	// the heap size reaches the trigger heap size computed by the
	// controller.
	gcTriggerHeap gcTriggerKind = iota

	// gcTriggerTime indicates that a cycle should be started when
	// it's been more than forcegcperiod nanoseconds since the
	// previous GC cycle.
	gcTriggerTime

	// gcTriggerCycle indicates that a cycle should be started if
	// we have not yet started cycle number gcTrigger.n (relative
	// to work.cycles).
	gcTriggerCycle
)

gcTriggerHeap is the normal case. gcTriggerTime is the two-minute forced collection, and gcTriggerCycle is runtime.GC().

The background mark budget: 25%

The controller dedicates a fixed fraction of the CPU to marking in the background, and makes up any shortfall with mutator assists:

 go
 
 
// src/runtime/mgcpacer.go:16
const (
	// gcGoalUtilization is the goal CPU utilization for
	// marking as a fraction of GOMAXPROCS.
	//
	// Increasing the goal utilization will shorten GC cycles as the GC
	// has more resources behind it, lessening costs from the write barrier,
	// but comes at the cost of increasing mutator latency.
	gcGoalUtilization = gcBackgroundUtilization

	// gcBackgroundUtilization is the fixed CPU utilization for background
	// marking. It must be <= gcGoalUtilization. The difference between
	// gcGoalUtilization and gcBackgroundUtilization will be made up by
	// mark assists. The scheduler will aim to use within 50% of this
	// goal.
	//
	// As a general rule, there's little reason to set gcBackgroundUtilization
	// < gcGoalUtilization. One reason might be in mostly idle applications,
	// where goroutines are unlikely to assist at all, so the actual
	// utilization will be lower than the goal. But this is moot point
	// because the idle mark workers already soak up idle CPU resources.
	// These two values are still kept separate however because they are
	// distinct conceptually, and in previous iterations of the pacer the
	// distinction was more important.
	gcBackgroundUtilization = 0.25

Twenty-five percent of GOMAXPROCS. On a 16-core box, four cores’ worth of dedicated marking. That number is turned into a worker count at the start of each cycle:

 go
 
 
// src/runtime/mgcpacer.go:398
	// Compute the background mark utilization goal. In general,
	// this may not come out exactly. We round the number of
	// dedicated workers so that the utilization is closest to
	// 25%. For small GOMAXPROCS, this would introduce too much
	// error, so we add fractional workers in that case.
	totalUtilizationGoal := float64(procs) * gcBackgroundUtilization
	dedicatedMarkWorkersNeeded := int64(totalUtilizationGoal + 0.5)
	utilError := float64(dedicatedMarkWorkersNeeded)/totalUtilizationGoal - 1
	const maxUtilError = 0.3
	if utilError < -maxUtilError || utilError > maxUtilError {
		// Rounding put us more than 30% off our goal. With
		// gcBackgroundUtilization of 25%, this happens for
		// GOMAXPROCS<=3 or GOMAXPROCS=6. Enable fractional
		// workers to compensate.
		if float64(dedicatedMarkWorkersNeeded) > totalUtilizationGoal {
			// Too many dedicated workers.
			dedicatedMarkWorkersNeeded--
		}
		c.fractionalUtilizationGoal = (totalUtilizationGoal - float64(dedicatedMarkWorkersNeeded)) / float64(procs)
	} else {
		c.fractionalUtilizationGoal = 0
	}

25% of 3 procs is 0.75, which cannot be rounded to a whole number of workers without a 30%+ error. That is what the fractional worker is for: a worker that runs on a fraction of a P’s time, self-preempting when it has used its share. idle workers are the third kind — they run only when the P has nothing else to do, and their time is essentially free because the CPU was going idle anyway.

Mark assist: the mutator pays for its own garbage

If the background workers cannot keep up, the mutator has to help. The controller computes an assist ratio — scan work per byte allocated — and the allocator charges every allocation against it:

 go
 
 
// src/runtime/mgcpacer.go:583
	// Compute the mutator assist ratio so by the time the mutator
	// allocates the remaining heap bytes up to heapGoal, it will
	// have done (or stolen) the remaining amount of scan work.
	// Note that the assist ratio values are updated atomically
	// but not together. This means there may be some degree of
	// skew between the two values. This is generally OK as the
	// values shift relatively slowly over the course of a GC
	// cycle.
	assistWorkPerByte := float64(scanWorkRemaining) / float64(heapRemaining)
	assistBytesPerWork := float64(heapRemaining) / float64(scanWorkRemaining)
	c.assistWorkPerByte.Store(assistWorkPerByte)
	c.assistBytesPerWork.Store(assistBytesPerWork)

Two numbers, reciprocals of each other. assistWorkPerByte is how much scanning one byte of allocation earns you. assistBytesPerWork is how many bytes of allocation one unit of scanning work repays.

The debt accounting lives on the goroutine. Every allocation subtracts from the debt; when the debt goes negative, the goroutine must assist:

 go
 
 
// src/runtime/malloc_stubs.go:169
func deductAssistCredit(size uintptr) {
	assistG := getg()
	if assistG.m.curg != nil {
		assistG = assistG.m.curg
	}
	assistG.gcAssistBytes -= int64(size)
	if assistG.gcAssistBytes < 0 {
		gcAssistAlloc(assistG)
	}
}

Note that gcAssistBytes is negative when you owe. The assist routine turns that negative number into an amount of work:

 go
 
 
// src/runtime/mgcmark.go:559
	// Compute the amount of scan work we need to do to make the
	// balance positive. When the required amount of work is low,
	// we over-assist to build up credit for future allocations
	// and amortize the cost of assisting.
	assistWorkPerByte := gcController.assistWorkPerByte.Load()
	assistBytesPerWork := gcController.assistBytesPerWork.Load()
	debtBytes := -gp.gcAssistBytes
	scanWork := int64(assistWorkPerByte * float64(debtBytes))
	if scanWork < gcOverAssistWork {
		scanWork = gcOverAssistWork
		debtBytes = int64(assistBytesPerWork * float64(scanWork))
	}

gcOverAssistWork is 64 KiB of scan work. If your debt is small, you do that much anyway — over-assisting on purpose, so that the next few thousand allocations do not each trigger a trip through the scheduler.

Then the assist runs, and the work done is credited back:

 go
 
 
// src/runtime/mgcmark.go:749
	// Record that we did this much scan work.
	//
	// Back out the number of bytes of assist credit that
	// this scan work counts for. The "1+" is a poor man's
	// round-up, to ensure this adds credit even if
	// assistBytesPerWork is very low.
	assistBytesPerWork := gcController.assistBytesPerWork.Load()
	gp.gcAssistBytes += 1 + int64(assistBytesPerWork*float64(workDone))

Before doing its own work, an assist tries to steal credit from the background workers’ credit pool, and if it cannot pay off its debt after working, it parks on the assist queue until the collector hands it credit.

The soft memory limit

GOMEMLIMIT puts the collector in a different regime. The goal is no longer derived from the live heap; it is derived from how much memory the runtime has mapped and how much of the limit is already spoken for:

 go
 
 
// src/runtime/mgcpacer.go:1071
	// In practice this computation looks like the following:
	//
	// goal := memoryLimit - ((mappedReady - heapFree - heapAlloc) + max(mappedReady - memoryLimit, 0))
	// ^1 ^2
	// goal -= goal / 100 * memoryLimitHeapGoalHeadroomPercent
	// ^3
	//
	// Let's break this down.
	//
	// The first term (marker 1) is everything that contributes to the memory limit and isn't
	// or couldn't become heap objects. It represents, broadly speaking, non-heap overheads.

Three adjustments: subtract the non-heap overhead, subtract any overage past the limit, and subtract a few percent of headroom so that pacing inaccuracies do not immediately push you back over. The headroom has a floor:

 go
 
 
// src/runtime/mgcpacer.go:66
	// memoryLimitMinHeapGoalHeadroom is the minimum amount of headroom the
	// pacer gives to the heap goal when operating in the memory-limited regime.
	// That is, it'll reduce the heap goal by this many extra bytes off of the
	// base calculation, at minimum.
	memoryLimitMinHeapGoalHeadroom = 1 << 20

One megabyte, because the pacer’s inputs get fuzzy on small heaps.

What to measure

The runtime exposes the numbers as metrics:

 go
 
 
// src/runtime/metrics/description.go:289
	{
		Name: "/gc/heap/goal:bytes",
		Description: "Heap size target for the end of the GC cycle.",
		Kind: KindUint64,
	},
	{
		Name: "/gc/heap/live:bytes",
		Description: "Heap memory occupied by live objects that were marked by the previous GC.",
		Kind: KindUint64,
	},

/gc/heap/goal:bytes minus /gc/heap/live:bytes is the runway you have. If the goal is barely above the live heap, your live set is growing. If the goal is huge, you are over-allocating.

GODEBUG=gctrace=1 prints the same numbers per cycle, along with the CPU time split between assists, dedicated workers, fractional workers and idle workers.

Trade-offs

What GOGC gives you: a direct, predictable trade between heap size and GC frequency. GOGC=100 means “spend memory to spend less CPU”. GOGC=50 halves the garbage-to-live ratio. GOGC=off means the program must manage its own memory.

What it costs: a larger heap means a larger live set to scan next cycle, and the scan cost is superlinear in cache behaviour even if linear in bytes.

What assists give you: the collector never has to stop the world to keep up with an allocation-heavy program. The mutator pays in latency instead, which is usually the better trade.

What it costs: assists are per-goroutine latency spikes on the allocation path, and a program that allocates in tight loops will feel them as jitter.

What the soft memory limit gives you: a ceiling on RSS that survives a change in the program’s allocation behaviour.

What it costs: the pacer becomes conservative in a way that is hard to predict, and if the limit is set too low the program spends its time in GC rather than doing work.

Caveats

GOGC is a multiplier, not a target. The heap goal is also raised by the size of your stacks and globals, and by a floor of a few megabytes. A program with a large live set and GOGC=10 still runs a big heap.

The memory limit is soft. GOMEMLIMIT is a target the runtime tries to respect; it is not a limit the OS enforces, and the runtime can exceed it if it must (the goroutine stacks of a million goroutines are not the GC’s business).

gcController.heapLive over-estimates. It counts whole spans when it updates, because it is updated when a span is fetched from an mcentral. The comment says so explicitly: “It’s better to overestimate than to underestimate because 1) this triggers the GC earlier than necessary rather than potentially too late”.

The assist ratio is approximate. The two ratio fields are updated atomically but not together, so they can be briefly skewed relative to each other. The values move slowly, so it does not matter in practice.

GODEBUG=gctrace=1 is the tool, not the metrics. The metrics tell you the goal and the live heap; the trace tells you where the CPU went.

Wrapping up

The one thing to remember: the collector starts at the trigger, not at the goal, and finishes at the goal. The gap between them is runway, and the runway is what keeps the GC from having to stop the world.

The part people get wrong: GOGC=100 does not mean “collect when the heap doubles”. It means “collect when the heap grows by 100% of the live heap plus the scannable stacks and globals”, floored at a few megabytes, and then capped by whatever GOMEMLIMIT says.

What to go do about it: turn on GODEBUG=gctrace=1 and read the “goal” number next to your actual heap size. If they are far apart, you have slack and can afford a lower GOGC. If they are close, you are running out of runway and should look at allocation rate before touching anything else.

How Go's crypto Package Uses AES-NI and SHA-NI

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

TL;DR: crypto/aes and crypto/sha256 are thin shims over crypto/internal/fips140, where a CPUID check at start-up decides whether your machine has AES-NI, SHA-NI and AVX2. If it does, an AES block is ten AESENC instructions and a SHA-256 block is sixteen SHA256RNDS2 instructions. If it does not, a table-driven fallback runs — and that fallback is not constant-time.

Go’s crypto package is fast for a boring reason: on any CPU made in the last fifteen years, the interesting arithmetic happens in a handful of instructions that do exactly what the algorithm says. There is no software AES, no bitsliced cleverness, no hand-rolled GF(2^128) arithmetic on the hot path. The CPU does it.

The interesting part is how the choice is made, and the fact that the layout of the tree changed dramatically a few releases ago.

The public packages are now shims

crypto/aes used to own the assembly. It no longer does:

 go
 
 
// src/crypto/aes/aes.go:32
// NewCipher creates and returns a new [cipher.Block].
// The key argument must be the AES key,
// either 16, 24, or 32 bytes to select
// AES-128, AES-192, or AES-256.
func NewCipher(key []byte) (cipher.Block, error) {
	k := len(key)
	switch k {
	default:
		return nil, KeySizeError(k)
	case 16, 24, 32:
		break
	}
	if boring.Enabled {
		return boring.NewAESCipher(key)
	}
	return aes.New(key)
}

aes.New is crypto/internal/fips140/aes.New. The same is true of crypto/sha256, which forwards to crypto/internal/fips140/sha256. The reason is FIPS 140-3 validation: the primitives had to be restructured into a single internal package that could be validated as a unit, with the public packages left as thin, stable API surfaces.

That restructuring also moved the assembly. There is no src/crypto/aes/cipher_amd64.s any more. The AES-NI code is at src/crypto/internal/fips140/aes/aes_amd64.s, and the SHA-NI code is at src/crypto/internal/fips140/sha256/sha256block_amd64.s.

Detecting the hardware

The dispatch decision is made from CPUID, once, at start-up. The bits are defined in src/internal/cpu/cpu_x86.go:

 go
 
 
// src/internal/cpu/cpu_x86.go:125
	_, _, ecx1, _ := cpuid(1, 0)

	X86.HasSSE3 = isSet(ecx1, cpuid_SSE3)
	X86.HasPCLMULQDQ = isSet(ecx1, cpuid_PCLMULQDQ)
	X86.HasSSSE3 = isSet(ecx1, cpuid_SSSE3)
	X86.HasSSE41 = isSet(ecx1, cpuid_SSE41)
	X86.HasSSE42 = isSet(ecx1, cpuid_SSE42)
	X86.HasPOPCNT = isSet(ecx1, cpuid_POPCNT)
	X86.HasAES = isSet(ecx1, cpuid_AES)

cpuid_AES is bit 25 of ECX from leaf 1 — the AES-NI feature bit. The SHA extensions live in the extended leaf 7 instead, which is why SHA-NI support is detected separately:

 go
 
 
// src/internal/cpu/cpu_x86.go:172
	X86.HasAVX2 = isSet(ebx7, cpuid_AVX2) && osSupportsAVX
	X86.HasBMI2 = isSet(ebx7, cpuid_BMI2)
	X86.HasERMS = isSet(ebx7, cpuid_ERMS)
	X86.HasADX = isSet(ebx7, cpuid_ADX)
	X86.HasSHA = isSet(ebx7, cpuid_SHA)

The crypto packages do not import internal/cpu directly; they go through a dependency shim so that the FIPS package’s dependency graph stays clean:

 go
 
 
// src/crypto/internal/fips140deps/cpu/cpu.go:47
	X86HasAES = cpu.X86.HasAES
	X86HasADX = cpu.X86.HasADX
	X86HasAVX = cpu.X86.HasAVX
	X86HasAVX2 = cpu.X86.HasAVX2
	X86HasBMI2 = cpu.X86.HasBMI2
	X86HasPCLMULQDQ = cpu.X86.HasPCLMULQDQ
	X86HasSHA = cpu.X86.HasSHA
	X86HasSSE41 = cpu.X86.HasSSE41
	X86HasSSSE3 = cpu.X86.HasSSSE3

And the AES package turns those bits into a single boolean, decided at compile time by build tag and at run time by the CPU:

 go
 
 
// src/crypto/internal/fips140/aes/aes_asm.go:5
//go:build (amd64 || arm64 || loong64 || ppc64 || ppc64le) && !purego

package aes

import (
	"crypto/internal/fips140deps/cpu"
	"crypto/internal/fips140deps/godebug"
	"crypto/internal/impl"
)

//go:noescape
func encryptBlockAsm(nr int, xk *uint32, dst, src *byte)

//go:noescape
func decryptBlockAsm(nr int, xk *uint32, dst, src *byte)

//go:noescape
func expandKeyAsm(nr int, key *byte, enc *uint32, dec *uint32)

var supportsAES = cpu.X86HasAES && cpu.X86HasSSE41 && cpu.X86HasSSSE3 ||
	cpu.ARM64HasAES || cpu.LOONG64HasLSX || cpu.PPC64 || cpu.PPC64le

Note the compound requirement: AES-NI alone is not enough, you also want SSSE3 and SSE4.1 for the shuffle instructions used around it. Note also the !purego tag — the purego build tag forces the generic implementation everywhere, and the FIPS module refuses to run that way at all.

impl.Register("aes", "AES-NI", &supportsAES) records the choice in a registry, which is how the crypto test suite can force the generic path and check that it agrees with the hardware path.

The AES-NI encrypt chain

Here is the whole of the hardware AES encryption for one block. This is not a paraphrase; it is the generated assembly:

 asm
 
 
// src/crypto/internal/fips140/aes/aes_amd64.s:8
// Requires: AES, SSE, SSE2
TEXT ·encryptBlockAsm(SB), NOSPLIT, $0-32
	MOVQ nr+0(FP), CX
	MOVQ xk+8(FP), AX
	MOVQ dst+16(FP), DX
	MOVQ src+24(FP), BX
	MOVUPS (AX), X1
	MOVUPS (BX), X0
	ADDQ $0x10, AX
	PXOR X1, X0
	SUBQ $0x0c, CX
	JE Lenc192
	JB Lenc128
	MOVUPS (AX), X1
	AESENC X1, X0
	MOVUPS 16(AX), X1
	AESENC X1, X0
	ADDQ $0x20, AX

Lenc192:
	MOVUPS (AX), X1
	AESENC X1, X0
	MOVUPS 16(AX), X1
	AESENC X1, X0
	ADDQ $0x20, AX

Lenc128:
	MOVUPS (AX), X1
	AESENC X1, X0
	MOVUPS 16(AX), X1
	AESENC X1, X0
	MOVUPS 32(AX), X1
	AESENC X1, X0
	MOVUPS 48(AX), X1
	AESENC X1, X0
	MOVUPS 64(AX), X1
	AESENC X1, X0
	MOVUPS 80(AX), X1
	AESENC X1, X0
	MOVUPS 96(AX), X1
	AESENC X1, X0
	MOVUPS 112(AX), X1
	AESENC X1, X0
	MOVUPS 128(AX), X1
	AESENC X1, X0
	MOVUPS 144(AX), X1

Read it as a whole and the algorithm is visible:

PXOR X1, X0 — the AddRoundKey of round zero, XORing the plaintext with the first round key.
AESENC nine times for AES-128 (ten for AES-192, thirteen for AES-256) — each one is SubBytes, ShiftRows, MixColumns and AddRoundKey in a single instruction, with one cycle of latency each and one instruction of throughput. AES-NI is pipelined: the rounds are independent given the round keys, so the CPU can start round N+1 before round N has finished.
AESENCLAST once — the final round, with no MixColumns, because MixColumns is pointless on the last round.

The branching is on nr, the round count: SUBQ $0x0c, CX then JE Lenc192 / JB Lenc128. AES-128 has 10 rounds, AES-192 has 12, AES-256 has 14. The code falls through the AES-256 case (two extra AESENCs) into the AES-192 case (two more) into the AES-128 case (nine more plus the last). One code path, three key sizes, no loops — the unrolled straight-line code is what lets the CPU’s instruction window stay full.

Decryption is the mirror image, with AESDEC and AESDECLAST.

Key expansion

The round keys are computed once, when the cipher is created. The hardware has a dedicated instruction for the trickiest part of that — AESKEYGENASSIST:

 go
 
 
// src/crypto/internal/fips140/aes/aes_amd64.s:109
// func expandKeyAsm(nr int, key *byte, enc *uint32, dec *uint32)
// Requires: AES, SSE, SSE2
TEXT ·expandKeyAsm(SB), NOSPLIT, $0-32
	MOVQ nr+0(FP), CX
	MOVQ key+8(FP), AX
	MOVQ enc+16(FP), BX
	MOVQ dec+24(FP), DX
	MOVUPS (AX), X0

	// enc
	MOVUPS X0, (BX)
	ADDQ $0x10, BX
	PXOR X4, X4
	CMPL CX, $0x0c
	JE Lexp_enc192
	JB Lexp_enc128
	MOVUPS 16(AX), X2
	MOVUPS X2, (BX)
	ADDQ $0x10, BX
	AESKEYGENASSIST $0x01, X2, X1
	CALL _expand_key_256a<>(SB)
	AESKEYGENASSIST $0x01, X0, X1
	CALL _expand_key_256b<>(SB)
	AESKEYGENASSIST $0x02, X2, X1
	CALL _expand_key_256a<>(SB)
	AESKEYGENASSIST $0x02, X0, X1
	CALL _expand_key_256b<>(SB)
	AESKEYGENASSIST $0x04, X2, X1
	CALL _expand_key_256a<>(SB)
	AESKEYGENASSIST $0x04, X0, X1
	CALL _expand_key_256b<>(SB)

AESKEYGENASSIST takes the round constant as an immediate — $0x01, $0x02, $0x04, up to $0x40 — and produces the SubWord-and-RotWord intermediate value. The rest of the expansion (the SubWord, the XOR chain, the special 256b path that mixes in the S-box output for AES-256) is hand-written SSE code.

The decryption key schedule is derived from the encryption one with AESIMC, which applies the inverse MixColumns to each round key — that is why decryption is a straight AESDEC chain with the same shape as encryption.

The assembly is generated

One more thing worth knowing: this .s file is not hand-written. It is generated by Avo, from a Go program that lives in the tree:

 go
 
 
// src/crypto/internal/fips140/aes/_asm/standard/aes_amd64.go:42
func encryptBlockAsm() {
	Implement("encryptBlockAsm")
	Attributes(NOSPLIT)
	AllocLocal(0)

	Load(Param("nr"), RCX)
	Load(Param("xk"), RAX)
	Load(Param("dst"), RDX)
	Load(Param("src"), RBX)
	MOVUPS(Mem{Base: AX}.Offset(0), X1)
	MOVUPS(Mem{Base: BX}.Offset(0), X0)
	ADDQ(Imm(16), RAX)
	PXOR(X1, X0)
	SUBQ(Imm(12), RCX)
	JE(LabelRef("Lenc192"))
	JB(LabelRef("Lenc128"))

	Label("Lenc256")
	MOVUPS(Mem{Base: AX}.Offset(0), X1)
	AESENC(X1, X0)
	MOVUPS(Mem{Base: AX}.Offset(16), X1)
	AESENC(X1, X0)
	ADDQ(Imm(32), RAX)

The generated file even says so in its first line:

 go
 
 
// src/crypto/internal/fips140/aes/aes_amd64.s:1
// Code generated by command: go run asm_amd64.go -out ../../asm_amd64.s -pkg aes. DO NOT EDIT.

Writing assembly in Go means the AES-NI sequence is type-checked, and the same trick is used for the SHA-256 AVX2 implementation, which is generated by sha256block_amd64_asm.go.

The modes: CBC, CTR and GCM

AES is a block cipher; the modes of operation are what people actually use.

CBC is done in plain Go, one block at a time, because it is inherently serial:

 go
 
 
// src/crypto/internal/fips140/aes/cbc.go:50
func cryptBlocksEncGeneric(b *Block, civ *[BlockSize]byte, dst, src []byte) {
	iv := civ[:]
	for len(src) > 0 {
		// Write the xor to dst, then encrypt in place.
		subtle.XORBytes(dst[:BlockSize], src[:BlockSize], iv)
		encryptBlock(b, dst[:BlockSize], dst[:BlockSize])

		// Move to the next block with this block as the next iv.
		iv = dst[:BlockSize]
		src = src[BlockSize:]
		dst = dst[BlockSize:]

CTR is different: it is parallelisable, because each counter block is independent. Go exploits that with eight-block and four-block assembly routines:

 go
 
 
// src/crypto/internal/fips140/aes/ctr.go:90
	for len(src) >= 8*BlockSize {
		ctrBlocks8(&c.b, (*[8 * BlockSize]byte)(dst), (*[8 * BlockSize]byte)(src), ivlo, ivhi)
		src = src[8*BlockSize:]
		dst = dst[8*BlockSize:]
		ivlo, ivhi = add128(ivlo, ivhi, 8)
	}

	// The tail can have at most 7 = 4 + 2 + 1 blocks.
	if len(src) >= 4*BlockSize {
		ctrBlocks4(&c.b, (*[4 * BlockSize]byte)(dst), (*[4 * BlockSize]byte)(src), ivlo, ivhi)
		src = src[4*BlockSize:]
		dst = dst[4*BlockSize:]
		ivlo, ivhi = add128(ivlo, ivhi, 4)
	}

and the assembly keeps four independent AES pipelines in flight, which is exactly the shape AES-NI wants:

 go
 
 
// src/crypto/internal/fips140/aes/ctr_amd64.s:187
	MOVUPS (CX), X0
	AESENC X0, X1
	AESENC X0, X2
	AESENC X0, X3
	AESENC X0, X4
	MOVUPS 16(CX), X0
	AESENC X0, X1
	AESENC X0, X2
	AESENC X0, X3
	AESENC X0, X4

GCM needs both AES and a fast GF(2^128) multiply, which is where PCLMULQDQ (carryless multiply) comes in:

 go
 
 
// src/crypto/internal/fips140/aes/gcm/gcm_asm.go:33
// Keep in sync with crypto/tls.hasAESGCMHardwareSupport.
var supportsAESGCM = cpu.X86HasAES && cpu.X86HasPCLMULQDQ && cpu.X86HasSSE41 && cpu.X86HasSSSE3 ||
	cpu.ARM64HasAES && cpu.ARM64HasPMULL

var supportsAESGCMEOR3 = supportsAESGCM && cpu.ARM64HasSHA3

On x86 that means AES-NI plus CLMUL plus SSSE3 (for the byte shuffles) plus SSE4.1. Without them, GCM falls back to a bit-by-bit GF(2^128) implementation — dramatically slower, and the reason the AES package’s doc comment is careful to note that on such systems GCM is not constant-time either.

SHA-256 with SHA-NI

SHA-256 gets two hardware paths and one software path, chosen like this:

 go
 
 
// src/crypto/internal/fips140/sha256/sha256block_amd64.go:14
var useAVX2 = cpu.X86HasAVX && cpu.X86HasAVX2 && cpu.X86HasBMI2
var useSHANI = cpu.X86HasAVX && cpu.X86HasSHA && cpu.X86HasSSE41 && cpu.X86HasSSSE3

func init() {
	impl.Register("sha256", "AVX2", &useAVX2)
	impl.Register("sha256", "SHA-NI", &useSHANI)
}

//go:noescape
func blockAVX2(dig *Digest, p []byte)

//go:noescape
func blockSHANI(dig *Digest, p []byte)

func block(dig *Digest, p []byte) {
	if useSHANI {
		blockSHANI(dig, p)
	} else if useAVX2 {
		blockAVX2(dig, p)
	} else {
		blockGeneric(dig, p)
	}
}

SHA-NI wins when available. The SHA256RNDS2 instruction performs two rounds of the compression function in one go, and the hardware also implements the message schedule partially, in SHA256MSG1 and SHA256MSG2.

The prologue shows the layout. The digest state is shuffled into two XMM registers in a big-endian-friendly arrangement, and the round constants are addressed through a pointer:

 go
 
 
// src/crypto/internal/fips140/sha256/sha256block_amd64.s:1289
// func blockSHANI(dig *Digest, p []byte)
// Requires: AVX, SHA, SSE2, SSE4.1, SSSE3
TEXT ·blockSHANI(SB), $0-32
	MOVQ dig+0(FP), DI
	MOVQ p_base+8(FP), SI
	MOVQ p_len+16(FP), DX
	SHRQ $0x06, DX
	SHLQ $0x06, DX
	CMPQ DX, $0x00
	JEQ done
	ADDQ SI, DX
	VMOVDQU (DI), X1
	VMOVDQU 16(DI), X2
	PSHUFD $0xb1, X1, X1
	PSHUFD $0x1b, X2, X2
	VMOVDQA X1, X7
	PALIGNR $0x08, X2, X1
	PBLENDW $0xf0, X7, X2
	VMOVDQA flip_mask<>+0(SB), X8
	LEAQ K256<>+0(SB), AX

roundLoop:
	// save hash values for addition after rounds
	VMOVDQA X1, X9
	VMOVDQA X2, X10

	// do rounds 0-59
	VMOVDQU (SI), X0
	PSHUFB X8, X0
	VMOVDQA X0, X3
	PADDD (AX), X0
	SHA256RNDS2 X0, X1, X2
	PSHUFD $0x0e, X0, X0
	SHA256RNDS2 X0, X2, X1

The PSHUFB X8, X0 is the byte-swap: SHA-256 is defined over big-endian words, x86 is little-endian, so the message block is flipped on the fly using a mask table.

The loop body is structured in groups of four message words. Each group does two SHA256RNDS2 instructions (four rounds), and the message schedule is advanced with SHA256MSG1 and SHA256MSG2:

 go
 
 
// src/crypto/internal/fips140/sha256/sha256block_amd64.s:1330
	SHA256MSG1 X4, X3
	VMOVDQU 32(SI), X0
	PSHUFB X8, X0
	VMOVDQA X0, X5
	PADDD 64(AX), X0
	SHA256RNDS2 X0, X1, X2
	PSHUFD $0x0e, X0, X0
	SHA256RNDS2 X0, X2, X1
	SHA256MSG1 X5, X4

The PSHUFD $0x0e, X0, X0 between the two SHA256RNDS2 instructions is the trick that makes the four-round group work: SHA256RNDS2 consumes the message schedule word it is given and produces a partial sum, and the shuffle redistributes the intermediate state so that the second instruction in the pair operates on the right half of the state.

The last four rounds are peeled out of the loop, because they are different — no message scheduling, just the final additions:

 go
 
 
// src/crypto/internal/fips140/sha256/sha256block_amd64.s:1460
	// do rounds 60-63
	VMOVDQA X6, X0
	PADDD 480(AX), X0
	SHA256RNDS2 X0, X1, X2
	PSHUFD $0x0e, X0, X0
	SHA256RNDS2 X0, X2, X1

	// add current hash values with previously saved
	PADDD X9, X1
	PADDD X10, X2

	// advance data pointer; loop until buffer empty
	ADDQ $0x40, SI
	CMPQ DX, SI
	JNE roundLoop

Sixteen SHA256RNDS2 per 64-byte block — sixty-four rounds, two rounds per instruction — plus the message schedule in hardware. On a modern x86 that is roughly a cycle per round, which is the theoretical limit for SHA-256.

The AVX2 path (blockAVX2) is the older trick: it processes four 64-byte blocks at once by transposing them into a 4x4 matrix of words and running the compression function four times in parallel with AVX2 vector operations. It is still useful on machines with AVX2 but no SHA-NI.

The pure-Go fallback, and why it matters

If the CPU has no AES-NI, the package falls back to a table-driven implementation. This is the classic T-table approach:

 go
 
 
// src/crypto/internal/fips140/aes/aes_generic.go:41
// Encrypt one block from src into dst, using the expanded key xk.
func encryptBlockGeneric(c *blockExpanded, dst, src []byte) {
	checkGenericIsExpected()
	xk := c.enc[:]

	_ = src[15] // early bounds check
	s0 := byteorder.BEUint32(src[0:4])
	s1 := byteorder.BEUint32(src[4:8])
	s2 := byteorder.BEUint32(src[8:12])
	s3 := byteorder.BEUint32(src[12:16])

	// First round just XORs input with key.
	s0 ^= xk[0]
	s1 ^= xk[1]
	s2 ^= xk[2]
	s3 ^= xk[3]

	// Middle rounds shuffle using tables.
	k := 4
	var t0, t1, t2, t3 uint32
	for r := 0; r < c.rounds-1; r++ {
		t0 = xk[k+0] ^ te0[uint8(s0>>24)] ^ te1[uint8(s1>>16)] ^ te2[uint8(s2>>8)] ^ te3[uint8(s3)]
		t1 = xk[k+1] ^ te0[uint8(s1>>24)] ^ te1[uint8(s2>>16)] ^ te2[uint8(s3>>8)] ^ te3[uint8(s0)]
		t2 = xk[k+2] ^ te0[uint8(s2>>24)] ^ te1[uint8(s3>>16)] ^ te2[uint8(s0>>8)] ^ te3[uint8(s1)]
		t3 = xk[k+3] ^ te0[uint8(s3>>24)] ^ te1[uint8(s0>>16)] ^ te2[uint8(s1>>8)] ^ te3[uint8(s2)]
		k += 4
		s0, s1, s2, s3 = t0, t1, t2, t3
	}

The four 256-entry tables (te0 through te3, in const.go) fold SubBytes, ShiftRows and MixColumns into a single table lookup per byte. It is fast — a few hundred MB/s — but the table index depends on the secret key material, so the memory access pattern leaks it through the cache.

That is why the package doc says this:

 go
 
 
// src/crypto/aes/aes.go:5
// Package aes implements AES encryption (formerly Rijndael), as defined in
// U.S. Federal Information Processing Standards Publication 197.
//
// The AES operations in this package are not implemented using constant-time algorithms.
// An exception is when running on systems with enabled hardware support for AES
// that makes these operations constant-time. Examples include amd64 systems using AES-NI
// extensions and s390x systems using Message-Security-Assist extensions.
// On such systems, when the result of NewCipher is passed to cipher.NewGCM,
// the GHASH operation used by GCM is also constant-time.
package aes

And it is why the assembly build has a tripwire: if the hardware path is available but the generic path runs anyway, the code panics rather than silently losing the constant-time property.

 go
 
 
// src/crypto/internal/fips140/aes/aes_asm.go:49
// checkGenericIsExpected is called by the variable-time implementation to make
// sure it is not used when hardware support is available. It shouldn't happen,
// but this way it's more evidently correct.
func checkGenericIsExpected() {
	if supportsAES {
		panic("crypto/aes: internal error: using generic implementation despite hardware support")
	}
}

The BoringCrypto path

There is a third implementation, and it is not Go at all. crypto/internal/boring wraps BoringSSL, and the public packages check a build-time constant before doing anything else:

 go
 
 
// src/crypto/internal/boring/doc.go:10
// Enabled reports whether BoringCrypto is available.
// When enabled is false, all functions in this package panic.
//
// BoringCrypto is only available on linux/amd64 and linux/arm64 systems.
const Enabled = available

boring.Enabled is available, which is false in the default build and true when the tree is built with the boringcrypto build tag:

 go
 
 
// src/crypto/internal/boring/boring.go:5
//go:build boringcrypto && linux && (amd64 || arm64) && !android && !msan

package boring

/*
// goboringcrypto_linux_amd64.syso references pthread functions.
#cgo LDFLAGS: "-pthread"

#include "goboringcrypto.h"
*/
import "C"
import (
	"crypto/internal/boring/sig"
	_ "crypto/internal/boring/syso"
	"crypto/internal/fips140"
	"internal/stringslite"
	"math/bits"
	"unsafe"
)

const available = true

When it is enabled, crypto/aes.NewCipher returns a BoringSSL cipher instead, and crypto/sha256.New returns a BoringSSL hash. That build is used for FIPS-certified systems that need a validated cryptographic module. It cannot be combined with the Go 1.24+ fips140 mode:

 go
 
 
// src/crypto/internal/boring/boring.go:35
func init() {
	if fips140.Enabled {
		panic("boringcrypto: cannot use GODEBUG=fips140 with GOEXPERIMENT=boringcrypto")
	}
}

So there are three worlds: the default Go implementation with hardware acceleration, the purego build with no assembly at all, and the BoringCrypto build with a C implementation underneath.

Trade-offs

What the hardware buys:

AES: roughly 1 cycle per round on a modern x86, versus roughly 10-20 cycles per round for the T-table fallback. That is a 10-20x gap, and it is why TLS throughput on a server is usually not the bottleneck.
SHA-256 with SHA-NI: about 1.5 cycles per byte, versus about 11 for the AVX2 path and about 15-20 for the generic Go implementation.
Constant time. AES-NI and SHA-NI have no data-dependent timing. The fallback does.

What it costs:

Build complexity. Every primitive has an assembly file, a generic file, and build tags to choose between them, for eight architectures.
A dispatch decision at every call. encryptBlock branches on supportsAES — a global bool, so the branch predicts perfectly, but it is a branch.
Portability. The purego tag exists because some environments (some emulators, some kernels, some reproducible-build setups) cannot tolerate platform-specific code.

Caveats

The generic fallback is not constant-time. If you are defending against a local attacker who can measure cache timings, the T-table implementation leaks. The package says so, but only in the doc comment, which most people never read.

GCM needs more than AES-NI. supportsAESGCM requires PCLMULQDQ and SSSE3 as well. A CPU with AES-NI but without CLMUL gets fast AES and slow GCM — and the constant-time guarantee for GHASH goes away too.

SHA-NI is not universal. It arrived with Ice Lake server and Alder Lake client. On older Intel and on AMD Zen 1 and 2, the AVX2 path runs instead.

purego is slower than you think. It is not “the same algorithm, less optimised” — it is a different, slower algorithm with different security properties. The FIPS module refuses to run under purego for exactly this reason:

 go
 
 
// src/crypto/internal/fips140/fips140.go:36
	// The purego tag changes too much of the implementation to claim the
	// validation still applies.
	if puregoEnabled {
		return errors.New("FIPS 140-3 mode is incompatible with the purego build tag")
	}

The assembly is generated. If you are reading aes_amd64.s and cannot follow it, read _asm/standard/aes_amd64.go instead — it is the same program in a language you already know.

BoringCrypto and fips140 are mutually exclusive. Both want to own the cryptographic implementation, and the tree panics at init if you try to have both.

crypto/aes is not where the implementation is. If you are grepping for the AES assembly, look under crypto/internal/fips140/aes/, not crypto/aes/.

Wrapping up

The one thing to remember: crypto/aes and crypto/sha256 are shims. The real implementations are in crypto/internal/fips140, and the dispatch is a pair of CPUID checks made once at start-up: AES-NI for the cipher, SHA-NI for the hash.

The part people get wrong: assuming the pure-Go fallback is equivalent. It is not constant-time, and on a machine without the hardware instructions it is one to two orders of magnitude slower — and GCM falls back to a bit-by-bit GF(2^128) multiply.

What to go do about it: run crypto/internal/impl’s registry to see what your machine actually selected, and compare crypto/aes against the purego build to see the gap on your own hardware. If you are deploying to a fleet, check the oldest CPU’s feature bits, because the fallback is where the constant-time guarantee disappears.

How Go's CPU Profiler Works: SIGPROF, the Signal Stack and 100 Hz Sampling

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

TL;DR: Go’s CPU profiler is an interval timer plus a signal handler. runtime/pprof.StartCPUProfile hardcodes 100 Hz, the runtime arms setitimer(ITIMER_PROF) with that period, and every time the timer fires the kernel raises SIGPROF on some thread. The handler runs on a dedicated 32 KB signal stack, unwinds the interrupted goroutine’s stack in place, and appends the PCs to a lock-free ring buffer. A separate goroutine drains that buffer and writes a protobuf profile.

Profiling a Go program is easy: call pprof.StartCPUProfile(f) and walk away. What that call actually sets up is a POSIX interval timer, a kernel signal, a signal handler running on a stack the runtime reserves for exactly this purpose, a stack unwinder that has to work while the world is half-frozen, and a lock-free ring buffer shared between a signal handler and an ordinary goroutine.

Every one of those pieces is in the Go tree, and every one of them is a little unusual. Let’s walk through them, based on the Go 1.28 development tree.

The 100 Hz decision

The frequency is not configurable through the public API, and the reason is written down in runtime/pprof:

 go
 
 
// src/runtime/pprof/pprof.go:885
func StartCPUProfile(w io.Writer) error {
	// The runtime routines allow a variable profiling rate,
	// but in practice operating systems cannot trigger signals
	// at more than about 500 Hz, and our processing of the
	// signal is not cheap (mostly getting the stack trace).
	// 100 Hz is a reasonable choice: it is frequent enough to
	// produce useful data, rare enough not to bog down the
	// system, and a nice round number to make it easy to
	// convert sample counts to seconds. Instead of requiring
	// each client to specify the frequency, we hard code it.
	const hz = 100

	cpu.Lock()
	defer cpu.Unlock()
	if cpu.done == nil {
		cpu.done = make(chan bool)
	}
	// Double-check.
	if cpu.profiling {
		return fmt.Errorf("cpu profiling already in use")
	}
	cpu.profiling = true
	pprof_setCPUProfileRate(hz)
	go profileWriter(w)
	return nil
}

Two things to notice. First, 100 is hardcoded — runtime.SetCPUProfileRate exists and does let you pick a rate, but runtime/pprof refuses to use it. Second, the comment tells you the real cost model: the expensive part is not the signal, it is the stack unwinding that follows it. That single sentence explains most of the design decisions below.

profileWriter is the other half of the public API, and it is the goroutine that drains the samples and turns them into a profile:

 go
 
 
// src/runtime/pprof/pprof.go:919
func profileWriter(w io.Writer) {
	b := newProfileBuilder(w)
	var err error
	for {
		if runtime.GOOS == "darwin" || runtime.GOOS == "ios" {
			// see runtime_pprof_readProfile
			time.Sleep(100 * time.Millisecond)
		}
		data, tags, eof := readProfile()
		if e := b.addCPUData(data, tags); e != nil && err == nil {
			err = e
		}
		if eof {
			break
		}
	}
	if err != nil {
		// The runtime should never produce an invalid or truncated profile.
		// It drops records that can't fit into its log buffers.
		panic("runtime/pprof: converting profile: " + err.Error())
	}
	b.build()
	cpu.done <- true
}

The signal handler and this goroutine never touch the same data structure directly. They meet in profBuf, a ring buffer designed for exactly one reader and one writer.

Arming the timer

pprof_setCPUProfileRate is a go:linknamed entry point into the runtime, which lands in setCPUProfileRate in src/runtime/cpuprof.go. That function creates the ring buffer, writes one special record into it (the sampling rate), and then calls setcpuprofilerate, which eventually reaches the OS-specific timer setup:

 go
 
 
// src/runtime/signal_unix.go:276
// setProcessCPUProfilerTimer is called when the profiling timer changes.
// It is called with prof.signalLock held. hz is the new timer, and is 0 if
// profiling is being disabled. Enable or disable the signal as
// required for -buildmode=c-archive.
func setProcessCPUProfilerTimer(hz int32) {
	if hz != 0 {
		// Enable the Go signal handler if not enabled.
		if atomic.Cas(&handlingSig[_SIGPROF], 0, 1) {
			h := getsig(_SIGPROF)
			// If no signal handler was installed before, then we record
			// _SIG_IGN here. When we turn off profiling (below) we'll start
			// ignoring SIGPROF signals. We do this, rather than change
			// to SIG_DFL, because there may be a pending SIGPROF
			// signal that has not yet been delivered to some other thread.
			// If we change to SIG_DFL when turning off profiling, the
			// program will crash when that SIGPROF is delivered. We assume
			// that programs that use profiling don't want to crash on a
			// stray SIGPROF. See issue 19320.
			// We do the change here instead of when turning off profiling,
			// because there we may race with a signal handler running
			// concurrently, in particular, sigfwdgo may observe _SIG_DFL and
			// die. See issue 43828.
			if h == _SIG_DFL {
				h = _SIG_IGN
			}
			atomic.Storeuintptr(&fwdSig[_SIGPROF], h)
			setsig(_SIGPROF, abi.FuncPCABIInternal(sighandler))
		}

		var it itimerval
		it.it_interval.tv_sec = 0
		it.it_interval.set_usec(1000000 / hz)
		it.it_value = it.it_interval
		setitimer(_ITIMER_PROF, &it, nil)
	} else {
		setitimer(_ITIMER_PROF, &itimerval{}, nil)

setitimer(ITIMER_PROF) is the crux. ITIMER_PROF counts CPU time consumed by the process (user time plus system time), not wall-clock time. So a program that spends its life blocked on a socket does not accumulate profiling ticks; a program burning CPU in a tight loop does. The timer is process-wide, and when it expires the kernel picks a thread that does not have the signal blocked and raises SIGPROF there.

That “picks a thread” is why the profiler is biased the way it is. The sample is attributed to whatever goroutine happened to be running on the thread that won the race to receive the signal.

The _SIG_IGN dance above is a lovely piece of defensive engineering: turning the timer off does not cancel an already-pending signal, so switching the handler back to SIG_DFL would let that pending signal kill the program.

The signal stack

Signals are delivered on the thread’s normal stack by default, which is a disaster for a profiler: the interrupted goroutine’s stack is already in use, and the handler needs room to walk it. Go gives every M a dedicated signal stack.

 go
 
 
// src/runtime/os_linux.go:385
// Called to initialize a new m (including the bootstrap m).
// Called on the parent thread (main thread in case of bootstrap), can allocate memory.
func mpreinit(mp *m) {
	mp.gsignal = malg(32 * 1024) // Linux wants >= 2K
	mp.gsignal.m = mp
}

And it installs it as the thread’s alternate signal stack, with SA_ONSTACK:

 go
 
 
// src/runtime/os_linux.go:478
func setsig(i uint32, fn uintptr) {
	var sa sigactiont
	sa.sa_flags = _SA_SIGINFO | _SA_ONSTACK | _SA_RESTORER | _SA_RESTART
	sigfillset(&sa.sa_mask)
	// Although Linux manpage says "sa_restorer element is obsolete and
	// should not be used". x86_64 kernel requires it. Only use it on
	// x86. Note that on 386 this is cleared when using the C sigaction
	// function via cgo; see fixSigactionForCgo.
	if GOARCH == "386" || GOARCH == "amd64" {
		sa.sa_restorer = abi.FuncPCABI0(sigreturn__sigaction)
	}
	if fn == abi.FuncPCABIInternal(sighandler) { // abi.FuncPCABIInternal(sighandler) matches the callers in signal_unix.go
		if iscgo {
			fn = abi.FuncPCABI0(cgoSigtramp)
		} else {
			fn = abi.FuncPCABI0(sigtramp)
		}
	}
	sa.sa_handler = fn
	sigaction(i, &sa, nil)
}

Note sigfillset(&sa.sa_mask): while the handler runs, every signal is blocked. That is why the runtime can rely on a single signal at a time — no reentrancy into the profiler from another signal — and it is also why the profiler’s own locking is a simple compare-and-swap rather than a mutex.

Each thread gets its own 32 KB gsignal goroutine stack, set up when the M is initialised:

 go
 
 
// src/runtime/signal_unix.go:1329
func minitSignals() {
	minitSignalStack()
	minitSignalMask()
}

// minitSignalStack is called when initializing a new m to set the
// alternate signal stack. If the alternate signal stack is not set
// for the thread (the normal case) then set the alternate signal
// stack to the gsignal stack. If the alternate signal stack is set
// for the thread (the case when a non-Go thread sets the alternate
// signal stack and then calls a Go function) then set the gsignal
// stack to the alternate signal stack. We also set the alternate
// signal stack to the gsignal stack if cgo is not used (regardless
// of whether it is already set). Record which choice was made in
// newSigstack, so that it can be undone in unminit.
func minitSignalStack() {
	mp := getg().m
	var st stackt
	sigaltstack(nil, &st)
	if st.ss_flags&_SS_DISABLE != 0 || !iscgo {
		signalstack(&mp.gsignal.stack)
		mp.newSigstack = true
	} else {
		setGsignalStack(&st, &mp.goSigStack)
		mp.newSigstack = false
	}
}

The handler: identify the goroutine, unwind the stack

The handler itself is sighandler, which handles every signal Go cares about. SIGPROF gets an early return:

 go
 
 
// src/runtime/signal_unix.go:674
	if sig == _SIGPROF {
		// Some platforms (Linux) have per-thread timers, which we use in
		// combination with the process-wide timer. Avoid double-counting.
		if !delayedSignal && validSIGPROF(mp, c) {
			sigprof(c.sigpc(), c.sigsp(), c.siglr(), gp, mp)
		}
		return
	}

gp is the G that was running when the signal arrived; mp is the M it was running on. That is the “per-thread goroutine identification”: the sample is attributed to mp.curg, and the goroutine’s pprof labels are attached to the sample as a tag pointer.

sigprof is where the stack is unwound:

 go
 
 
// src/runtime/proc.go:5801
// Called if we receive a SIGPROF signal.
// Called by the signal handler, may run during STW.
//
//go:nowritebarrierrec
func sigprof(pc, sp, lr uintptr, gp *g, mp *m) {
	if prof.hz.Load() == 0 {
		return
	}

	// If mp.profilehz is 0, then profiling is not enabled for this thread.
	// We must check this to avoid a deadlock between setcpuprofilerate
	// and the call to cpuprof.add, below.
	if mp != nil && mp.profilehz == 0 {
		return
	}
	...
	// Profiling runs concurrently with GC, so it must not allocate.
	// Set a trap in case the code does allocate.
	// Note that on windows, one thread takes profiles of all the
	// other threads, so mp is usually not getg().m.
	// In fact mp may not even be stopped.
	// See golang.org/issue/17165.
	getg().m.mallocing++

	var u unwinder
	var stk [maxCPUProfStack]uintptr
	n := 0
	...
	} else {
		u.initAt(pc, sp, lr, gp, unwindSilentErrors|unwindTrap|unwindJumpStack)
	}
	n += tracebackPCs(&u, 0, stk[n:])

Here is a genuinely surprising fact about modern Go: gentraceback is gone. It used to be the workhorse, and every blog post about Go stack unwinding still describes it. In the Go 1.28 tree there is no gentraceback function at all. It has been replaced by the unwinder type, an explicit iterator:

 go
 
 
// src/runtime/traceback.go:84
// An unwinder iterates the physical stack frames of a Go sack.
//
// Typical use of an unwinder looks like:
//
//	var u unwinder
//	for u.init(gp, 0); u.valid(); u.next() {
//		// ... use frame info in u ...
//	}
//
// Implementation note: This is carefully structured to be pointer-free because
// tracebacks happen in places that disallow write barriers (e.g., signals).
// Even if this is stack-allocated, its pointer-receiver methods don't know that
// their receiver is on the stack, so they still emit write barriers. Here we
// address that by carefully avoiding any pointers in this type. Another
// approach would be to split this into a mutable part that's passed by pointer
// but contains no pointers itself and an immutable part that's passed and
// returned by value and can contain pointers. We could potentially hide that
// we're doing that in trivial methods that are inlined into the caller that has
// the stack allocation, but that's fragile.
type unwinder struct {
	// frame is the current physical stack frame, or all 0s if
	// there is no frame.
	frame stkframe

The pointer-free design is not cosmetic. The signal handler runs with write barriers disabled (the GC may be in the middle of a stop-the-world), and the unwinder is deliberately built so it cannot allocate or trigger a barrier.

The result of the unwind is a flat array of return PCs, up to 64 frames:

 go
 
 
// src/runtime/traceback.go:645
func tracebackPCs(u *unwinder, skip int, pcBuf []uintptr) int {
	var cgoBuf [32]uintptr
	n := 0
	for ; n < len(pcBuf) && u.valid(); u.next() {
		f := u.frame.fn
		cgoN := u.cgoCallers(cgoBuf[:])

		// TODO: Why does &u.cache cause u to escape? (Same in traceback2)
		for iu, uf := newInlineUnwinder(f, u.symPC()); n < len(pcBuf) && uf.valid(); uf = iu.next(uf) {
			sf := iu.srcFunc(uf)
			if sf.funcID == abi.FuncIDWrapper && elideWrapperCalling(u.calleeFuncID) {
				// ignore wrappers
			} else if skip > 0 {
				skip--
			} else {
				// Callers expect the pc buffer to contain return addresses
				// and do the -1 themselves, so we add 1 to the call pc to
				// create a "return pc". Since there is no actual call, here
				// "return pc" just means a pc you subtract 1 from to get
				// the pc of the "call". The actual no-op we insert may or
				// may not be 1 byte.
				pcBuf[n] = uf.pc + 1
				n++
			}
			u.calleeFuncID = sf.funcID
		}

If the unwind fails — the sample landed in a JIT blob, or in C code with no Go frames — the profiler falls back to a synthetic two-frame stack of System or GC plus _ExternalCode. Those fake frames show up in go tool pprof output as runtime._System and runtime._ExternalCode, and they are a reliable signal that the time was spent outside Go.

Writing to the ring buffer

The sample is handed to cpuprof.add, which does the least it can get away with:

 go
 
 
// src/runtime/cpuprof.go:108
// add adds the stack trace to the profile.
// It is called from signal handlers and other limited environments
// and cannot allocate memory or acquire locks that might be
// held at the time of the signal, nor can it use substantial amounts
// of stack.
//
//go:nowritebarrierrec
func (p *cpuProfile) add(tagPtr *unsafe.Pointer, stk []uintptr) {
	// Simple cas-lock to coordinate with setcpuprofilerate.
	for !prof.signalLock.CompareAndSwap(0, 1) {
		// TODO: Is it safe to osyield here? https://go.dev/issue/52672
		osyield()
	}

	if prof.hz.Load() != 0 { // implies cpuprof.log != nil
		if p.numExtra > 0 || p.lostExtra > 0 || p.lostAtomic > 0 {
			p.addExtra()
		}
		hdr := [1]uint64{1}
		// Note: write "knows" that the argument is &gp.labels,
		// because otherwise its write barrier behavior may not
		// be correct. See the long comment there before
		// changing the argument here.
		cpuprof.log.write(tagPtr, nanotime(), hdr[:], stk)
	}

	prof.signalLock.Store(0)
}

No allocation, no mutex — a compare-and-swap on prof.signalLock and a copy into a preallocated ring. The ring is profBuf, and its record layout is deliberately trivial:

 go
 
 
// src/runtime/profbuf.go:358
	// Main record.
	// It has to fit in a contiguous section of the slice, so if it doesn't fit at the end,
	// leave a rewind marker (0) and start over at the beginning of the slice.
	wd := int(bw.dataCount() % uint32(len(b.data)))
	nd := countSub(br.dataCount(), bw.dataCount()) + len(b.data)
	skip := 0
	if wd+2+int(b.hdrsize)+len(stk) > len(b.data) {
		b.data[wd] = 0
		skip = len(b.data) - wd
		nd -= skip
		wd = 0
	}
	data := b.data[wd:]
	data[0] = uint64(2 + b.hdrsize + uintptr(len(stk))) // length
	data[1] = uint64(now) // time stamp
	// header, zero-padded
	i := copy(data[2:2+b.hdrsize], hdr)
	clear(data[2+i : 2+b.hdrsize])
	for i, pc := range stk {
		data[2+b.hdrsize+uintptr(i)] = uint64(pc)
	}

Each record is: a length word, a timestamp, a one-word header (the sample count), and the PCs. The buffer is sized in the source with a very human comment:

 go
 
 
// src/runtime/cpuprof.go:21
const (
	maxCPUProfStack = 64

	// profBufWordCount is the size of the CPU profile buffer's storage for the
	// header and stack of each sample, measured in 64-bit words. Every sample
	// has a required header of two words. With a small additional header (a
	// word or two) and stacks at the profiler's maximum length of 64 frames,
	// that capacity can support 1900 samples or 19 thread-seconds at a 100 Hz
	// sample rate, at a cost of 1 MiB.
	profBufWordCount = 1 << 17

19 thread-seconds of samples in a megabyte. If the reader goroutine falls behind and the ring fills up, samples are dropped and the drop count is recorded as a special “overflow” record rather than silently lost.

The three-word header

The very first record the runtime writes is not a sample — it is the sampling rate, and the reader uses it to turn sample counts into nanoseconds:

 go
 
 
// src/runtime/cpuprof.go:94
		cpuprof.on = true
		cpuprof.log = newProfBuf(1, profBufWordCount, profBufTagCount)
		hdr := [1]uint64{uint64(hz)}
		cpuprof.log.write(nil, nanotime(), hdr[:], nil)
		setcpuprofilerate(int32(hz))

That record has a zero-length stack, so it occupies three words: length (3), timestamp, and the frequency. The reader checks for exactly that shape:

 go
 
 
// src/runtime/pprof/proto.go:278
func (b *profileBuilder) addCPUData(data []uint64, tags []unsafe.Pointer) error {
	if !b.havePeriod {
		// first record is period
		if len(data) < 3 {
			return fmt.Errorf("truncated profile")
		}
		if data[0] != 3 || data[2] == 0 {
			return fmt.Errorf("malformed profile")
		}
		// data[2] is sampling rate in Hz. Convert to sampling
		// period in nanoseconds.
		b.period = 1e9 / int64(data[2])
		b.havePeriod = true
		data = data[3:]
		// Consume tag slot. Note that there isn't a meaningful tag
		// value for this record.
		tags = tags[1:]
	}

The same routine also decodes the overflow records, which is how a dropped sample shows up in the profile rather than vanishing:

 go
 
 
// src/runtime/pprof/proto.go:322
		count := data[2]
		stk := data[3:data[0]]
		data = data[data[0]:]
		tag := tags[0]
		tags = tags[1:]

		if count == 0 && len(stk) == 1 {
			// overflow record
			count = uint64(stk[0])
			stk = []uint64{
				// gentraceback guarantees that PCs in the
				// stack can be unconditionally decremented and
				// still be valid, so we must do the same.
				uint64(abi.FuncPCABIInternal(lostProfileEvent) + 1),
			}
		}
		b.m.lookup(stk, tag).count += int64(count)

(The comment mentioning gentraceback is a leftover from before the unwinder rewrite — the property it describes still holds.)

The builder then deduplicates identical stacks on the fly and finally emits the protobuf with two sample types, samples/count and cpu/nanoseconds.

The memory profile is a different animal

The memory profile does not use signals at all. It samples allocations, at a rate set by a global:

 go
 
 
// src/runtime/mprof.go:856
// MemProfileRate controls the fraction of memory allocations
// that are recorded and reported in the memory profile.
// The profiler aims to sample an average of
// one allocation per MemProfileRate bytes allocated.
//
// To include every allocated block in the profile, set MemProfileRate to 1.
// To turn off profiling entirely, set MemProfileRate to 0.
//
// The tools that process the memory profiles assume that the
// profile rate is constant across the lifetime of the program
// and equal to the current value. Programs that change the
// memory profiling rate should do so just once, as early as
// possible in the execution of the program (for example,
// at the beginning of main).
var MemProfileRate int = 512 * 1024

512 KB, by default. The decision of which allocation to sample is made with a counter kept in the mcache — the per-P allocation cache — and the next sample point is drawn from an exponential distribution so that the sampling is Poissonian rather than periodic:

 go
 
 
// src/runtime/malloc.go:2236
// nextSample returns the next sampling point for heap profiling. The goal is
// to sample allocations on average every MemProfileRate bytes, but with a
// completely random distribution over the allocation timeline; this
// corresponds to a Poisson process with parameter MemProfileRate. In Poisson
// processes, the distance between two samples follows the exponential
// distribution (exp(MemProfileRate)), so the best return value is a random
// number taken from an exponential distribution whose mean is MemProfileRate.
func nextSample() int64 {
	if MemProfileRate == 0 {
		// Basically never sample.
		return math.MaxInt64
	}
	if MemProfileRate == 1 {
		// Sample immediately.
		return 0
	}
	return int64(fastexprand(MemProfileRate))
}

The counter lives on the mcache, and the check happens on every allocation:

 go
 
 
// src/runtime/malloc.go:1449
	c.nextSample -= int64(size)
	if c.nextSample < 0 || MemProfileRate != c.memProfRate {
		profilealloc(mp, x, size)
	}

So: the CPU profile samples time using a signal; the memory profile samples bytes using a counter in the allocator cache. Different mechanisms, different biases. The memory profile counts the sampled allocation as if it represented MemProfileRate bytes, which is why pprof scales it up — a 4 KB allocation sampled at 512 KB per sample is reported as 512 KB.

Why CPU-bound goroutines dominate

Because ITIMER_PROF counts CPU time, a goroutine only gets sampled when it is actually on the CPU. A goroutine blocked on a channel, sleeping on a timer, or waiting on a mutex is invisible to the CPU profiler no matter how important it is. The profile answers “where did the CPU time go”, not “where did the program spend its time”.

That is the correct answer for a CPU profiler, but it means a program dominated by I/O will produce a profile full of runtime._System and runtime._ExternalCode frames and nothing else. For “where is my time going”, you want the execution tracer or the block profile instead.

Two more biases worth knowing:

Short goroutines are undersampled. At 100 Hz, a goroutine needs to burn roughly 10 ms of CPU to have a decent chance of appearing at all.
The signal lands on an arbitrary thread. The kernel picks a thread that does not block SIGPROF, so the sample is a snapshot of that thread’s current goroutine. This is unbiased in aggregate, but it means individual samples are attributed to a goroutine that was merely running, not necessarily the one that consumed the CPU time.

Trade-offs

What sampling buys you: near-zero steady-state overhead. The timer fires 100 times a second, each firing costs one signal delivery plus one stack unwind, and nothing else in the program changes.

What it costs:

Statistical error. A short profile is a small sample. 100 samples is 1 second of CPU time; the standard error on a 1% line is roughly 10% relative.
The unwinder is the expensive part. The runtime comment says so outright: “our processing of the signal is not cheap (mostly getting the stack trace)”.
Signal-handler constraints. The handler cannot allocate, cannot take a mutex, and cannot grow the stack. The whole unwinder design is shaped by that.
Dropped samples. If the reader goroutine cannot keep up, samples are dropped and reported as an overflow record rather than blocking the signal handler.
Frames are lost at 64. maxCPUProfStack is 64; deeper stacks are truncated, and the truncated frame is a plain function name.

Caveats

SIGPROF is a normal signal. If your program calls os/signal.Notify(c, syscall.SIGPROF), it will fight the profiler for the signal. On Unix, sigenable explicitly refuses to touch SIGPROF:

 go
 
 
// src/runtime/signal_unix.go:195
	// SIGPROF is handled specially for profiling.
	if sig == _SIGPROF {
		return
	}

c-archive and c-shared builds are different. StartCPUProfile documents that it does not work by default there, because SIGPROF goes to the host program’s handler rather than Go’s.

Linux has per-thread timers. The kernel’s timer_create timers show up as _SI_TIMER signal codes while setitimer produces _SI_KERNEL, and validSIGPROF uses that to avoid counting the same CPU time twice.

Darwin cannot block in the reader. runtime_pprof_readProfile uses a non-blocking read on Darwin and iOS, and profileWriter sleeps 100 ms between reads, because notetsleepg is not safe in a signal handler there.

Profiles are not comparable across runs unless the rate is the same — which it is, since 100 Hz is hardcoded — but they are not comparable if the program was interrupted differently or if samples were dropped.

Wrapping up

The one thing to remember: the CPU profiler is a 100 Hz setitimer(ITIMER_PROF) plus a SIGPROF handler that runs on a per-M 32 KB signal stack, unwinds the interrupted goroutine with a pointer-free unwinder, and copies the PCs into a lock-free ring buffer that a separate goroutine turns into a profile.

The part people get wrong: ITIMER_PROF counts CPU time, so the profile shows you where the CPU went, not where the wall-clock went. A program that is mostly blocked will show almost nothing, and the samples it does show will be attributed to runtime._System.

What to go do about it: turn on a CPU profile and an execution trace at the same time. The profile tells you which function is hot; the trace tells you why the goroutine that called it was asleep. And if the profile is suspiciously empty, check for a SIGPROF handler installed by a library before you go looking for a performance bug.

How Go's Benchmarking Harness Repeats Until It's Sure

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

TL;DR: A Go benchmark is not run once. The harness runs it with one iteration to check it works, then guesses an iteration count, measures how long that took, predicts a better count, and repeats until the accumulated time hits -benchtime (one second by default). b.N is what it landed on.

Every Go performance story starts the same way: someone writes a benchmark, gets a number, and the number is wrong. Not because the benchmark was a lie, but because of how the harness works. Go’s testing package does not run your function once and time it. It runs your function many times with a varying number of iterations, and the number of iterations is decided at runtime by looking at how fast your code turned out to be.

Understanding that loop is the difference between a benchmark you can trust and a benchmark that will make you quit your job.

The struct you are handed

The testing.B struct is the whole interface between your code and the harness:

 go
 
 
// src/testing/benchmark.go:94
type B struct {
	common
	importPath string // import path of the package containing the benchmark
	bstate *benchState
	N int
	previousN int // number of iterations in the previous run
	previousDuration time.Duration // total duration of the previous run
	benchFunc func(b *B)
	benchTime durationOrCountFlag
	bytes int64
	missingBytes bool // one of the subbenchmarks does not have bytes set.
	timerOn bool
	showAllocResult bool
	result BenchmarkResult
	parallelism int // RunParallel creates parallelism*GOMAXPROCS goroutines
	// The initial states of memStats.Mallocs and memStats.TotalAlloc.
	startAllocs uint64
	startBytes uint64
	// The net total of this test after being run.
	netAllocs uint64
	netBytes uint64
	// Extra metrics collected by ReportMetric.
	extra map[string]float64

	// loop tracks the state of B.Loop
	loop struct {
		// n is the target number of iterations. It gets bumped up as we go.
		// When the benchmark loop is done, we commit this to b.N so users can
		// do reporting based on it, but we avoid exposing it until then.
		n uint64
		// i is the current Loop iteration. It's strictly monotonically
		// increasing toward n.
		//
		// The high bit is used to poison the Loop fast path and fall back to
		// the slow path.
		i uint64

		done bool // set when B.Loop return false
	}
}

Two fields matter above all: N, the number of iterations the harness decided on, and timerOn, whether the clock is currently running. Everything else is bookkeeping.

previousN and previousDuration are the memory of the last attempt, and they are what makes the ramp-up converge quickly instead of crawling.

The target duration

The harness needs to know how long to spend on a benchmark. That is -benchtime, and the flag is registered here:

 go
 
 
// src/testing/benchmark.go:25
func initBenchmarkFlags() {
	matchBenchmarks = flag.String("test.bench", "", "run only benchmarks matching `regexp`")
	benchmarkMemory = flag.Bool("test.benchmem", false, "print memory allocations for benchmarks")
	flag.Var(&benchTime, "test.benchtime", "run each benchmark for duration `d` or N times if `d` is of the form Nx")
}

and the default is one second:

 go
 
 
// src/testing/benchmark.go:31
var (
	matchBenchmarks *string
	benchmarkMemory *bool

	benchTime = durationOrCountFlag{d: 1 * time.Second} // changed during test of testing package
)

One second per benchmark, not 100 nanoseconds. The 100ns figure that circulates online is not the benchtime target; the smallest unit the harness cares about is the time of a single iteration, and the point of the ramp-up is to get the total to a second.

The flag accepts two forms. A duration is a wall-clock target; an Nx form fixes the iteration count exactly:

 go
 
 
// src/testing/benchmark.go:38
type durationOrCountFlag struct {
	d time.Duration
	n int
	allowZero bool
}

func (f *durationOrCountFlag) String() string {
	if f.n > 0 {
		return fmt.Sprintf("%dx", f.n)
	}
	return f.d.String()
}

func (f *durationOrCountFlag) Set(s string) error {
	if strings.HasSuffix(s, "x") {
		n, err := strconv.ParseInt(s[:len(s)-1], 10, 0)
		if err != nil || n < 0 || (!f.allowZero && n == 0) {
			return fmt.Errorf("invalid count")
		}
		*f = durationOrCountFlag{n: int(n)}
		return nil
	}
	d, err := time.ParseDuration(s)
	if err != nil || d < 0 || (!f.allowZero && d == 0) {
		return fmt.Errorf("invalid duration")
	}
	*f = durationOrCountFlag{d: d}
	return nil
}

-benchtime=100x runs exactly 100 iterations and stops. That is what you want when you are comparing two implementations at a fixed workload, or when you want a fast smoke test in CI. -benchtime=5s gives you a longer, steadier number at the cost of a slower test run.

The ramp-up

Here is the loop that decides b.N. It is short and it is the heart of the whole thing:

 go
 
 
// src/testing/benchmark.go:327
// launch launches the benchmark function. It gradually increases the number
// of benchmark iterations until the benchmark runs for the requested benchtime.
// launch is run by the doBench function as a separate goroutine.
// run1 must have been called on b.
func (b *B) launch() {
	// Signal that we're done whether we return normally
	// or by FailNow's runtime.Goexit.
	defer func() {
		b.signal <- true
	}()

	// b.Loop does its own ramp-up logic so we just need to run it once.
	// If b.loop.n is non zero, it means b.Loop has already run.
	if b.loop.n == 0 {
		// Run the benchmark for at least the specified amount of time.
		if b.benchTime.n > 0 {
			// We already ran a single iteration in run1.
			// If -benchtime=1x was requested, use that result.
			// See https://golang.org/issue/32051.
			if b.benchTime.n > 1 {
				b.runN(b.benchTime.n)
			}
		} else {
			d := b.benchTime.d
			for n := int64(1); !b.failed && b.duration < d && n < 1e9; {
				last := n
				// Predict required iterations.
				goalns := d.Nanoseconds()
				prevIters := int64(b.N)
				n = int64(predictN(goalns, prevIters, b.duration.Nanoseconds(), last))
				b.runN(int(n))
			}
		}
	}
	b.result = BenchmarkResult{b.N, b.duration, b.bytes, b.netAllocs, b.netBytes, b.extra}
}

Read it carefully. b.duration is the accumulated duration across all the runs so far. The loop keeps going until that total reaches d (one second) or until the iteration count hits a billion.

Each time round, it asks predictN how many iterations it should try next, based on how long the previous attempt took.

 go
 
 
// src/testing/benchmark.go:301
// Don't run more than 1e9 times. (This also keeps n in int range on 32 bit platforms.)
const maxBenchPredictIters = 1_000_000_000

func predictN(goalns int64, prevIters int64, prevns int64, last int64) int {
	if prevns == 0 {
		// Round up to dodge divide by zero. See https://go.dev/issue/70709.
		prevns = 1
	}

	// Order of operations matters.
	// For very fast benchmarks, prevIters ~= prevns.
	// If you divide first, you get 0 or 1,
	// which can hide an order of magnitude in execution time.
	// So multiply first, then divide.
	n := goalns * prevIters / prevns
	// Run more iterations than we think we'll need (1.2x).
	n += n / 5
	// Don't grow too fast in case we had timing errors previously.
	n = min(n, 100*last)
	// Be sure to run at least one more than last time.
	n = max(n, last+1)
	// Don't run more than 1e9 times. (This also keeps n in int range on 32 bit platforms.)
	n = min(n, maxBenchPredictIters)
	return int(n)
}

That is a proportional controller with safety rails. Multiply first, then divide — the comment explains why, and it is a real bug class: for a benchmark that takes 50ns per iteration, dividing first gives you 0 or 1 and you lose an order of magnitude of accuracy. Then overshoot by 20% so you are more likely to overshoot the target time than undershoot it, but never grow by more than 100x in one step (in case the previous measurement was noise), and always run at least one more iteration than last time so the loop terminates.

In practice this converges in two or three rounds. A benchmark that takes 1µs per iteration gets predicted at roughly a million iterations on the first real attempt, and finishes in one or two rounds.

Note also run1, the very first run, which happens before the loop:

 go
 
 
// src/testing/benchmark.go:229
// run1 runs the first iteration of benchFunc. It reports whether more
// iterations of this benchmarks should be run.
func (b *B) run1() bool {
	if bstate := b.bstate; bstate != nil {
		// Extend maxLen, if needed.
		if n := len(b.name) + bstate.extLen + 1; n > bstate.maxLen {
			bstate.maxLen = n + 8 // Add additional slack to avoid too many jumps in size.
		}
	}
	go func() {
		// Signal that we're done whether we return normally
		// or by FailNow's runtime.Goexit.
		defer func() {
			b.signal <- true
		}()

		b.runN(1)
	}()
	<-b.signal
	if b.failed {
		fmt.Fprintf(b.w, "%s--- FAIL: %s\n%s", b.chatty.prefix(), b.name, b.output)
		return false
	}

One iteration, N=1, on its own goroutine. It is a smoke test: if your benchmark panics, fails, or prints something enormous, you find out here before the harness starts doing a million iterations of it.

What one “run” means

runN is what actually calls your function:

 go
 
 
// src/testing/benchmark.go:196
// runN runs a single benchmark for the specified number of iterations.
func (b *B) runN(n int) {
	benchmarkLock.Lock()
	defer benchmarkLock.Unlock()
	ctx, cancelCtx := context.WithCancel(context.Background())
	defer func() {
		b.runCleanup(normalPanic)
		b.checkRaces()
	}()
	// Try to get a comparable environment for each run
	// by clearing garbage from previous runs.
	runtime.GC()
	b.resetRaces()
	b.N = n
	b.loop.n = 0
	b.loop.i = 0
	b.loop.done = false
	b.ctx = ctx
	b.cancelCtx = cancelCtx

	b.parallelism = 1
	b.ResetTimer()
	b.StartTimer()
	b.benchFunc(b)
	b.StopTimer()
	b.previousN = n
	b.previousDuration = b.duration

Four things to notice.

runtime.GC() before every run. The harness tries to give each run the same conditions. That is not perfect, but it means a previous run’s garbage does not skew the next one.

b.N = n is set before your function is called. This is why for i := 0; i < b.N; i++ works: b.N is already the right number when you read it.

b.ResetTimer() then b.StartTimer(). The timer is running by default when your function is entered. The reset zeroes the accumulated duration and the allocation counters.

b.previousN = n and b.previousDuration = b.duration at the end. That is the memory the next predictN call uses.

The timer

Because the timer runs by default, anything you do before the measurement loop is measured too. The classic benchmark bug:

 go
 
 
func BenchmarkParse(b *testing.B) {
	data, _ := os.ReadFile("big.json") // this is measured!
	var v Config
	for i := 0; i < b.N; i++ {
		v = Parse(data) // so is this
	}
}

The file read happens once but is timed once — which sounds harmless until you realise that on the first iteration b.N is 1, so a single os.ReadFile is a large fraction of a one-millisecond total, and the harness then runs the whole thing again with a million iterations where the read is noise. The reported ns/op is a blend of two different things.

The fix is the timer API:

 go
 
 
// src/testing/benchmark.go:135
// StartTimer starts timing a test. This function is called automatically
// before a benchmark starts, but it can also be used to resume timing after
// a call to [B.StopTimer].
func (b *B) StartTimer() {
	if !b.timerOn {
		runtime.ReadMemStats(&memStats)
		b.startAllocs = memStats.Mallocs
		b.startBytes = memStats.TotalAlloc
		b.start = time.Now()
		b.timerOn = true
		b.loop.i &^= loopPoisonTimer
	}
}

// StopTimer stops timing a test. This can be used to pause the timer
// while performing steps that you don't want to measure.
func (b *B) StopTimer() {
	if b.timerOn {
		b.duration += time.Since(b.start)
		runtime.ReadMemStats(&memStats)
		b.netAllocs += memStats.Mallocs - b.startAllocs
		b.netBytes += memStats.TotalAlloc - b.startBytes
		b.timerOn = false
		// If we hit B.Loop with the timer stopped, fail.
		b.loop.i |= loopPoisonTimer
	}
}

Note that StopTimer also accumulates the allocation counters, so the allocation statistics exclude the paused region too. And note the poison bit: if you stop the timer inside a b.Loop() body, the harness notices and fails the benchmark, because b.Loop assumes the timer is running.

ResetTimer is the other one:

 go
 
 
// src/testing/benchmark.go:163
// ResetTimer zeroes the elapsed benchmark time and memory allocation counters
// and deletes user-reported metrics.
// It does not affect whether the timer is running.
func (b *B) ResetTimer() {
	if b.extra == nil {
		// Allocate the extra map before reading memory stats.
		// Pre-size it to make more allocation unlikely.
		b.extra = make(map[string]float64, 16)
	} else {
		clear(b.extra)
	}
	if b.timerOn {
		runtime.ReadMemStats(&memStats)
		b.startAllocs = memStats.Mallocs
		b.startBytes = memStats.TotalAlloc
		b.start = time.Now()
	}
	b.duration = 0
	b.netAllocs = 0
	b.netBytes = 0
}

“Does not affect whether the timer is running” — so ResetTimer on its own does not exclude your setup. You need b.StopTimer() before the setup and b.StartTimer() after it. This is the single most common source of meaningless benchmark numbers in Go, and the reason Go 1.24 added b.Loop.

`b.Loop()`, and why the compiler gets involved

b.Loop() is the modern form, added in Go 1.24, and it solves both the setup-exclusion problem and the “the compiler optimised my benchmark away” problem.

 go
 
 
// src/testing/benchmark.go:468
// Loop returns true as long as the benchmark should continue running.
//
// A typical benchmark is structured like:
//
//	func Benchmark(b *testing.B) {
//		... setup ...
//		for b.Loop() {
//			... code to measure ...
//		}
//		... cleanup ...
//	}
//
// Loop resets the benchmark timer the first time it is called in a benchmark,
// so any setup performed prior to starting the benchmark loop does not count
// toward the benchmark measurement. Likewise, when it returns false, it stops
// the timer so cleanup code is not measured.
//
// Within the body of a "for b.Loop() { ... }" loop, arguments to and
// results from function calls and assigned variables within the loop are kept
// alive, preventing the compiler from fully optimizing away the loop body.
// Currently, this is implemented as a compiler transformation that wraps such
// variables with a runtime.KeepAlive intrinsic call. This applies only to
// statements syntactically between the curly braces of the loop, and the loop
// condition must be written exactly as "b.Loop()".
//
// After Loop returns false, b.N contains the total number of iterations that
// ran, so the benchmark may use b.N to compute other average metrics.
//
// Prior to the introduction of Loop, benchmarks were expected to contain an
// explicit loop from 0 to b.N. Benchmarks should either use Loop or contain a
// loop to b.N, but not both. Loop offers more automatic management of the
// benchmark timer, and runs each benchmark function only once per measurement,
// whereas b.N-based benchmarks must run the benchmark function (and any
// associated setup and cleanup) several times.
func (b *B) Loop() bool {

Two huge behavioural differences from the old form.

The benchmark function runs once. With b.Loop(), the harness does not re-run your function with different N values. b.Loop does its own ramp-up internally, growing its own target count. Your setup runs once, not three times.

Setup and cleanup are excluded automatically. Loop resets the timer on its first call and stops it when it returns false.

And the compiler gets involved to stop the optimiser eating your benchmark. The implementation is a dedicated compiler pass, cmd/compile/internal/bloop:

 go
 
 
// src/cmd/compile/internal/bloop/bloop.go:143
// keepAliveAt returns a statement that is either curNode, or a
// block containing curNode followed by a call to runtime.KeepAlive for each
// node in ns. These calls ensure that nodes in ns will be live until
// after curNode's execution.
func keepAliveAt(curfunc *ir.Func, ns ir.Nodes, curNode ir.Node) ir.Node {
	if len(ns) == 0 {
		return curNode
	}

	pos := curNode.Pos()
	calls := ir.Nodes{curNode}
	for _, n := range ns {
		if n == nil || n.Sym() == nil || n.Sym().IsBlank() {
			continue
		}
		if !ir.IsAddressable(n) {
			base.FatalfAt(n.Pos(), "keepAliveAt: node %v is not addressable", n)
		}
		arg := ir.NewConvExpr(pos, ir.OCONV, types.Types[types.TUNSAFEPTR], typecheck.NodAddr(curfunc, n))
		callExpr := typecheck.Call(curfunc, pos, typecheck.LookupRuntime("KeepAlive"), ir.Nodes{arg}, false).(*ir.CallExpr)
		callExpr.IsCompilerVarLive = true
		callExpr.NoInline = true
		calls = append(calls, callExpr)
	}

	return ir.NewBlockStmt(pos, calls)
}

The pass recognises the loop by its shape, and only if it matches exactly:

 go
 
 
// src/cmd/compile/internal/bloop/bloop.go:339
// isTestingBLoop returns true if it matches the node as a
// testing.(*B).Loop. See issue #61515.
func isTestingBLoop(t ir.Node) bool {
	if t.Op() != ir.OFOR {
		return false
	}
	nFor, ok := t.(*ir.ForStmt)
	if !ok || nFor.Cond == nil || nFor.Cond.Op() != ir.OCALLFUNC {
		return false
	}
	n, ok := nFor.Cond.(*ir.CallExpr)
	if !ok || n.Fun == nil || n.Fun.Op() != ir.OMETHEXPR {
		return false
	}
	name := ir.MethodExprName(n.Fun)
	if name == nil {
		return false
	}
	if fSym := name.Sym(); fSym != nil && name.Class == ir.PFUNC && fSym.Pkg != nil &&
		fSym.Name == "(*B).Loop" && fSym.Pkg.Path == "testing" {
		// Attempting to match a function call to testing.(*B).Loop
		return true
	}
	return false
}

The loop condition must literally be b.Loop(). Write b.Loop() in a variable and the transformation does not apply, and your benchmark body is fair game for dead-code elimination.

The Loop fast path is written to be inlinable:

 go
 
 
// src/testing/benchmark.go:502
func (b *B) Loop() bool {
	// This is written such that the fast path is as fast as possible and can be
	// inlined.
	//
	// There are three cases where we'll fall out of the fast path:
	//
	// - On the first call, both i and n are 0.
	//
	// - If the loop reaches the n'th iteration, then i == n and we need
	// to figure out the new target iteration count or if we're done.
	//
	// - If the timer is stopped, it poisons the top bit of i so the slow
	// path can do consistency checks and fail.
	if b.loop.i < b.loop.n {
		b.loop.i++
		return true
	}
	return b.loopSlowPath()
}

A benchmark that uses b.Loop but returns from inside the loop without breaking it correctly is caught:

 go
 
 
// src/testing/benchmark.go:224
	if b.loop.n > 0 && !b.loop.done && !b.failed {
		b.Error("benchmark function returned without B.Loop() == false (break or return in loop?)")
	}

Allocations

b.ReportAllocs turns on the allocation reporting for one benchmark:

 go
 
 
// src/testing/benchmark.go:189
// ReportAllocs enables malloc statistics for this benchmark.
// It is equivalent to setting -test.benchmem, but it only affects the
// benchmark function that calls ReportAllocs.
func (b *B) ReportAllocs() {
	b.showAllocResult = true
}

The counting happens in StartTimer and StopTimer, using runtime.MemStats.Mallocs and runtime.MemStats.TotalAlloc, and the results are divided by b.N at the end:

 go
 
 
// src/testing/benchmark.go:569
// AllocsPerOp returns the "allocs/op" metric,
// which is calculated as r.MemAllocs / r.N.
func (r BenchmarkResult) AllocsPerOp() int64 {
	if v, ok := r.Extra["allocs/op"]; ok {
		return int64(v)
	}
	if r.N <= 0 {
		return 0
	}
	return int64(r.MemAllocs) / int64(r.N)
}

The Extra map check at the top is how ReportMetric lets you override a built-in metric — you can report your own ns/op if you know better.

The final result carries everything:

 go
 
 
// src/testing/benchmark.go:535
// BenchmarkResult contains the results of a benchmark run.
type BenchmarkResult struct {
	N int // The number of iterations.
	T time.Duration // The total time taken.
	Bytes int64 // Bytes processed in one iteration.
	MemAllocs uint64 // The total number of memory allocations.
	MemBytes uint64 // The total number of bytes allocated.

	// Extra records additional metrics reported by ReportMetric.
	Extra map[string]float64
}

SetBytes is what turns on the MB/s column:

 go
 
 
// src/testing/benchmark.go:185
// SetBytes records the number of bytes processed in a single operation.
// If this is called, the benchmark will report ns/op and MB/s.
func (b *B) SetBytes(n int64) { b.bytes = n }

`testing.AllocsPerRun`

Sometimes you want the allocation count of a single operation, outside a benchmark. That is AllocsPerRun:

 go
 
 
// src/testing/allocs.go:20
func AllocsPerRun(runs int, f func()) (avg float64) {
	if parallelStart.Load() != parallelStop.Load() {
		panic("testing: AllocsPerRun called during parallel test")
	}
	defer runtime.GOMAXPROCS(runtime.GOMAXPROCS(1))

	// Warm up the function
	f()

	// Measure the starting statistics
	var memstats runtime.MemStats
	runtime.ReadMemStats(&memstats)
	mallocs := 0 - memstats.Mallocs

	// Run the function the specified number of times
	for i := 0; i < runs; i++ {
		f()
	}

	// Read the final statistics
	runtime.ReadMemStats(&memstats)
	mallocs += memstats.Mallocs

	// Average the mallocs over the runs (not counting the warm-up).
	// We are forced to return a float64 because the API is silly, but do
	// the division as integers so we can ask if AllocsPerRun()==1
	// instead of AllocsPerRun()<2.
	return float64(mallocs / uint64(runs))
}

Four deliberate design decisions here.

It warms up first. The first call to f() is outside the measurement window. First-call costs — lazy initialisation, page faults, the allocator’s first span — are not representative.

It pins GOMAXPROCS to 1 for the duration, and restores it afterwards. Allocation counts can depend on how many Ps are running, because work gets stolen.

It calls f through a function value. f is a func() parameter, so the compiler cannot inline it into AllocsPerRun, and the allocations inside it are real allocations. The current implementation does not use a separate //go:noinline sink function; the indirect call is what keeps the measurements honest.

It returns float64 but divides as integers, so you can compare the result with == 1 exactly rather than with a tolerance. The comment calls the API “silly” and then makes the best of it.

Sub-benchmarks, `-count`, and matching

b.Run creates a sub-benchmark. The rule is that a benchmark with sub-benchmarks is not itself measured:

 go
 
 
// src/testing/benchmark.go:803
// Run benchmarks f as a subbenchmark with the given name. It reports
// whether there were any failures.
//
// A subbenchmark is like any other benchmark. A benchmark that calls Run at
// least once will not be measured itself and will be called once with N=1.
func (b *B) Run(name string, f func(b *B)) bool {

Each sub-benchmark gets its own B, its own ramp-up, and its own result. The parent’s result is then a synthetic aggregate:

 go
 
 
// src/testing/benchmark.go:874
// add simulates running benchmarks in sequence in a single iteration. It is
// used to give some meaningful results in case func Benchmark is used in
// combination with Run.
func (b *B) add(other BenchmarkResult) {
	r := &b.result
	// The aggregated BenchmarkResults resemble running all subbenchmarks as
	// in sequence in a single benchmark.
	r.N = 1
	r.T += time.Duration(other.NsPerOp())

The names are matched by a regexp matcher that understands / as a path separator, so -bench=X/Y selects only the Y sub-benchmark of X:

 go
 
 
// src/testing/match.go:55
func newMatcher(matchString func(pat, str string) (bool, error), patterns, name, skips string) *matcher {
	var filter, skip filterMatch
	if patterns == "" {
		filter = simpleMatch{} // always partial true
	} else {
		filter = splitRegexp(patterns)
		if err := filter.verify(name, matchString); err != nil {
			fmt.Fprintf(os.Stderr, "testing: invalid regexp for %s\n", err)
			os.Exit(1)
		}
	}

-count is the flag that makes the harness run the whole thing more than once:

 go
 
 
// src/testing/testing.go:461
	count = flag.Uint("test.count", 1, "run tests and benchmarks `n` times")

and the benchmark side honours it:

 go
 
 
// src/testing/benchmark.go:739
// processBench runs bench b for the configured CPU counts and prints the results.
func (s *benchState) processBench(b *B) {
	for i, procs := range cpuList {
		for j := uint(0); j < *count; j++ {
			runtime.GOMAXPROCS(procs)
			benchName := benchmarkName(b.name, procs)

			// If it's chatty, we've already printed this information.
			if b.chatty == nil {
				fmt.Fprintf(b.w, "%-*s\t", s.maxLen, benchName)
			}
			// Recompute the running time for all but the first iteration.
			if i > 0 || j > 0 {
				b = &B{

Note that each -count repetition starts from a fresh B, so the ramp-up runs again and the numbers are independent samples rather than one long accumulation. That is what you want for a statistical comparison: five independent runs, look at the spread, not one run with a huge N.

There is a similar loop for tests themselves:

 go
 
 
// src/testing/testing.go:2717
func runTests(modulePath, importPath string, matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
	ok = true
	for _, procs := range cpuList {
		runtime.GOMAXPROCS(procs)
		for i := uint(0); i < *count; i++ {

and the same cpuList loop drives go test -cpu=1,4,8.

Parallel benchmarks

RunParallel splits b.N across goroutines:

 go
 
 
// src/testing/benchmark.go:950
func (b *B) RunParallel(body func(*PB)) {
	if b.N == 0 {
		return // Nothing to do when probing.
	}
	// Calculate grain size as number of iterations that take ~100µs.
	// 100µs is enough to amortize the overhead and provide sufficient
	// dynamic load balancing.
	grain := uint64(0)
	if b.previousN > 0 && b.previousDuration > 0 {
		grain = 1e5 * uint64(b.previousN) / uint64(b.previousDuration)
	}
	if grain < 1 {
		grain = 1
	}
	// We expect the inner loop and function call to take at least 10ns,
	// so do not do more than 100µs/10ns=1e4 iterations.
	if grain > 1e4 {
		grain = 1e4

The grain is a work-stealing quantum: each goroutine grabs grain iterations at a time from a shared atomic counter, so a goroutine that finishes early can take more work. 100 microseconds is the sweet spot — long enough that the atomic counter contention is negligible, short enough that the load stays balanced.

A note on `testlog`

While we are in the testing package: there is a side channel that most people never see. internal/testlog exists so that cmd/go can see which environment variables and files a test consulted, which is what makes test caching correct:

 go
 
 
// src/internal/testlog/log.go:5
// Package testlog provides a back-channel communication path
// between tests and package os, so that cmd/go can see which
// environment variables and files a test consults.
package testlog

The logger is swapped in atomically, because test startup races with goroutines started during init:

 go
 
 
// src/internal/testlog/log.go:23
// logger is the current logger Interface.
// We use an atomic.Pointer in case test startup
// is racing with goroutines started during init.
// That must not cause a race detector failure,
// although it will still result in limited visibility
// into exactly what those goroutines do.
var logger atomic.Pointer[Interface]

It is a small thing, but it is a nice example of atomic.Pointer being the right tool: the interface value is published once, at startup, and read concurrently from arbitrary goroutines.

Trade-offs

What the ramp-up buys you. A measurement over a million iterations is stable to a fraction of a percent. A measurement over one iteration is dominated by scheduler noise, cache state and frequency scaling. The proportional controller gets you to the same place in two or three rounds rather than doubling until you get there.

What it costs. Your benchmark function is called several times, with different N. That means any setup inside the function happens several times, and if the setup has side effects (writing a file, appending to a global) you will be surprised. b.Loop() fixes this by running the function once.

Why -benchtime is one second. Long enough to drown out noise, short enough that go test -bench=. over a whole package finishes in a reasonable time. The ramp-up means the time is spent measuring, not waiting: the harness runs iterations back to back until the total is a second.

Why -count exists. Because a single sample of a noisy measurement is not evidence. Five samples and a look at the spread is.

Why the harness forces a runtime.GC() between runs. Comparability. Each run starts from as close to the same heap state as the harness can manage.

Caveats

The timer is on by default. Setup code before your measurement loop is timed unless you explicitly stop the timer. This is the number one cause of meaningless benchmark results.

b.N changes between runs of the same function. Your function is called with several different values of b.N. If you cache something in a package variable keyed on b.N, or if you branch on b.N, your benchmark is measuring something different each time.

b.Loop() requires the exact literal form. The compiler transformation only matches for b.Loop() { ... }. Any other spelling loses the keep-alive protection and the timer management.

b.Loop() and a b.N loop must not be mixed. The harness checks, but only after the fact, and the error message is a b.Error rather than a compile error.

Benchmarks are not tests of correctness. go test -bench does not check that your code returns the right answer. A benchmark that computes garbage faster is still a fast benchmark.

RunParallel reports wall time for the whole benchmark, not the sum of the per-goroutine times, and it explicitly forbids StartTimer, StopTimer, ResetTimer and Run inside the body.

The ramp-up is per benchmark, per -cpu value, per -count repetition. go test -bench=. -cpu=1,4,8 -count=5 runs your benchmark 15 times, each with its own ramp-up. That is a lot of wall-clock time, and it is why people narrow the benchmark selection when they are iterating.

Wrapping up

The one thing to remember: b.N is not given to you, it is decided by the harness at run time by measuring how fast your code turned out to be. Your benchmark must therefore be a function of b.N, and it must do the same work every iteration, or the number you get back is not a per-operation cost.

The part people get wrong: the timer is running when your function is entered. Unless you stop it, your file read, your map construction and your regex compilation are all inside the measurement, and your ns/op is a blend of setup and work.

What to go do about it: rewrite your benchmarks to use for b.Loop() { ... }. It excludes setup and cleanup, runs the function exactly once, and the compiler keeps your loop body alive so the optimiser cannot delete it. Then run with -benchmem -count=5 and compare the spread, not a single number.

Go 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

unsafe.Pointer and //go:linkname: The Escape Hatches That Break Abstraction

unsafe.Pointer: the type system, optional

The modern intrinsics

checkptr: the runtime’s unsafe sanity checker

//go:linkname: calling things you were not invited to call

The hall of shame

The linker enforces who may pull what

Dead code elimination and method pruning

Trade-offs

Caveats

Wrapping up

Further reading

unique.Make and the Weak Pointer Map: Canonicalizing Strings Without Leaking

The API is three methods

Two levels of dispatch

The canonical map is a hash trie, not a Go map

The leaf holds a weak pointer

Insert, prune, and register the cleanup

Deleting the entry

The clone trick

What Handle.Value() guarantees

Trade-offs

Caveats

Wrapping up

Further reading

sync.Pool: Per-P Caches, a Victim Generation and Why Items Vanish

The contract first

The struct

Put and Get

Pinning: why items do not migrate between Ps

The lock-free chain

The head/tail trick

Pushing

Popping from the head

Popping from the tail

The slow path: stealing and the victim cache

The two-generation rule

Why a victim cache at all?

Trade-offs

Caveats

Wrapping up

Further reading

sync.Map: Two Maps, A Miss Counter and Why Read-Mostly Wins

The old design: two maps and a miss counter

What replaced it: a hash trie

Initialisation is lazy and one-time

The read path takes no locks

The write path: double-checked locking on one node

Range walks the tree

Why read-mostly still wins

Trade-offs

Caveats

Wrapping up

The `maps` package inherits it

What `Handle.Value()` guarantees

`Put` and `Get`

`defer` inside the loop body

`recover` inside the loop body

The `default` case

`reflect.Select` is the same function

packEface: turning a Value back into an `any`