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

How Go Hashes Map Keys: AES-NI, wyhash and the Seed

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

TL;DR: Go hashes map keys with an AES-NI instruction sequence when the CPU has AES, SSSE3 and SSE4.1, and with a wyhash-inspired scalar function everywhere else. Both paths mix in two secrets: a process-wide key generated at startup and a fresh random seed per map, which is regenerated whenever the map empties out so an attacker cannot keep colliding keys.

Hashing is the part of a hash map that everybody assumes is magic and nobody looks at. It is also the part where a language has to make two opposing promises: a hash must be fast, because you do it on every operation, and a hash must be unpredictable, because an adversary who can predict it can turn your map into a linked list.

Go has solved this twice, and in the current tree (Go 1.28 development) both solutions live in src/internal/runtime/maps. This is a walk through them.

Which hash function, for which key

First, the key type decides the hash function, and that decision is made by the compiler, at compile time, not at runtime:

 go
 
 
// src/cmd/compile/internal/reflectdata/alg.go:23
func genhash(t *types.Type) *obj.LSym {
	return genhashSig(eqSignature(t))
}

func genhashSig(sig string) *obj.LSym {
	if len(sig) > 0 && sig[0] == sigAlign {
		_, sig = parseNum(sig[1:])
	}
	switch sig {
	case "":
		return sysClosure("memhash0")
	case string(sigMemory) + "1":
		return sysClosure("memhash8")
	case string(sigMemory) + "2":
		return sysClosure("memhash16")
	case string(sigMemory) + "4":
		return sysClosure("memhash32")
	case string(sigMemory) + "8":
		return sysClosure("memhash64")
	case string(sigMemory) + "16":
		return sysClosure("memhash128")
	case string(sigString):
		return sysClosure("strhash")
	case string(sigIface):
		return sysClosure("interhash")
	case string(sigEface):
		return sysClosure("nilinterhash")
	case string(sigFloat32):
		return sysClosure("f32hash")
	case string(sigFloat64):
		return sysClosure("f64hash")
	case string(sigFloat32) + string(sigFloat32):
		return sysClosure("c64hash")
	case string(sigFloat64) + string(sigFloat64):
		return sysClosure("c128hash")

So a map[string]int uses runtime.strhash, a map[int64]int uses runtime.memhash64, a map[struct{...}]int gets a compiler-generated function that mixes the fields, and so on. These are not the old aeshashbody / aeshashstr assembly routines you may remember from the Go 1.20 source tree; the whole hashing stack moved into the maps package, and the runtime keeps thin shims for compatibility:

 go
 
 
// src/runtime/alg.go:79
//go:nosplit
//go:linkname memhash
func memhash(p unsafe.Pointer, h, s uintptr) uintptr {
	return maps.MemHash(p, h, s)
}

//go:nosplit
func memhash64(p unsafe.Pointer, seed uintptr) uintptr {
	return maps.MemHash64(readUnaligned64(p), seed)
}

//go:nosplit
func memhash32(p unsafe.Pointer, seed uintptr) uintptr {
	return maps.MemHash32(readUnaligned32(p), seed)
}

Two secrets, not one

The most important thing to understand about Go’s hashing is that there are two independent sources of randomness, and every hash mixes both.

The first is process-wide, generated once at startup from the runtime’s bootstrap randomness source:

 go
 
 
// src/internal/runtime/maps/runtime_alg.go:36
const hashRandomBytes = goarch.PtrSize / 4 * 64

// used to seed the hash function
var aeskeysched [hashRandomBytes]byte

// used in hash{32,64}.go to seed the hash function
var hashkey [4]uintptr

// Pre-computed comparisons against MinAeshashSize, which reduces a
// load-and-compare-and-branch to a load-and-branch.
var (
	useAeshash32 bool // = MinAeshashSize <= 4
	useAeshash64 bool // = MinAeshashSize <= 8
)

hashkey is the secret for the scalar path; aeskeysched is the AES key schedule for the hardware path.

The second secret is per map, and it is what makes hash flooding impractical. Every map gets a fresh random seed when it is created:

 go
 
 
// src/internal/runtime/maps/map.go:350
func NewEmptyMap() *Map {
	m := new(Map)
	m.seed = uintptr(rand())
	// See comment in NewMap. No need to eager allocate a group.
	return m
}

rand() is the runtime’s per-M ChaCha8 generator, not math/rand:

 go
 
 
// src/runtime/rand.go:163
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--
	}
}

The seed is not permanent, either. When a map empties out, or is cleared, the seed is replaced:

 go
 
 
// src/internal/runtime/maps/map.go:695
	if m.used == 0 {
		// Reset the hash seed to make it more difficult for attackers
		// to repeatedly trigger hash collisions. See
		// https://go.dev/issue/25237.
		m.seed = uintptr(rand())
	}

That is the whole defence against hash-flooding denial of service. An attacker who submits a million colliding keys costs you a million-element lookup; but the collisions only work for the current seed, and the seed changes when the map empties, so the attacker has to keep the map non-empty to keep the collisions alive — and a non-empty map costs you memory anyway. The upstream issue is go.dev/issue/25237.

Choosing an implementation at startup

Which hash gets used is decided once, at process start, by looking at the CPU features:

 go
 
 
// src/internal/runtime/maps/runtime_alg.go:51
func AlgInit() {
	// Always intialize hashkey.
	//
	// See #78073
	for i := range hashkey {
		hashkey[i] = uintptr(bootstrapRand())
	}

	// Install AES hash algorithms if the instructions needed are present.
	if (goarch.GOARCH == "386" || goarch.GOARCH == "amd64") &&
		cpu.X86.HasAES && // AESENC
		cpu.X86.HasSSSE3 && // PSHUFB
		cpu.X86.HasSSE41 { // PINSR{D,Q}

		// In memHashAES we have global variables that should be properly aligned.
		//
		// See #12415
		if !checkMasksAndShiftsAlignment() {
			fatal("maps: global variables for AES hashing are not properly aligned!")
		}
		initAlgAES()

		if memHashUsesVAES && !cpu.X86.HasAVX {
			// We are using intrinsics hash implementation.
			// Override the UseAeshash in this case, since it uses VAES (AVX) instructions.
			// While assembly implementation used AES-NI instructions,
			// simd intrinsics only provide access to AVX ones.
			MinAeshashSize = ^uintptr(0)
		}
	} else if goarch.GOARCH == "arm64" && cpu.ARM64.HasAES {
		initAlgAES()
	}

	useAeshash32 = 4 >= MinAeshashSize
	useAeshash64 = 8 >= MinAeshashSize
}

Three CPU features are required: AESENC for the encryption rounds, PSHUFB for the byte shuffling at the end of a short block, and PINSRD/PINSRQ to build the seed register. That is why the very first AMD Athlons and any pre-2011 x86 chip falls back to the scalar path.

AlgInit is called from runtime/proc.go during scheduler bring-up, after cpuinit and before anything can use a map.

The size threshold

The AES path is only worth taking for big enough inputs. The vector instructions have a fixed latency, and for a four-byte key that latency costs more than it saves. So there is a threshold, and it is measured, not guessed:

 go
 
 
// src/internal/runtime/maps/runtime_alg.go:14
// MinAeshashSize is the smallest key size hashed with the AES-based
// implementation. Selecting hash is a size comparison against this value.
// Setting this to MaxUintptr disables AES altogether.
//
// When support is detected, the threshold is lowered to select between the
// scalar-based fallback hash and the vector-based AES hash. This value is
// selected on a per-platform basis based on what value produces the best
// benchmark results.
//
// Scalar hashes are faster on small values because it avoids taking a trip
// into the vector unit, which hurts latency (and for very small values,
// throughput).
var MinAeshashSize uintptr = ^uintptr(0)

 go
 
 
// src/internal/runtime/maps/runtime_alg.go:88
func initAlgAES() {
	// TODO(mcy): investigate cutoffs on a per-uarch basis.
	// See memhash_bench_test.go.
	switch goarch.ArchFamily {
	case goarch.AMD64:
		// Measured on AMD Ryzen Threadripper PRO 7995WX (Zen4).
		MinAeshashSize = 9
	case goarch.ARM64:
		// Measured on Apple M1.
		// Latency crossover is at 192.
		MinAeshashSize = 16
	default:
		MinAeshashSize = 0
	}

	// Initialize with random data so hash collisions will be hard to engineer.
	key := (*[hashRandomBytes / 8]uint64)(unsafe.Pointer(&aeskeysched))
	for i := range key {
		key[i] = bootstrapRand()
	}
}

Here is the surprise: on amd64 the threshold is 9 bytes. That means the AES path is used for strings of 9 bytes or more — and not for 4-byte or 8-byte integer keys, because useAeshash32 and useAeshash64 are computed as 4 >= MinAeshashSize and 8 >= MinAeshashSize, both false when the threshold is 9.

In other words: on a modern x86 laptop, map[int64]int does not use AES-NI. It uses the scalar wyhash-style function. Integer keys are hashed with a multiply-fold, not with the AES pipeline.

The dispatch

The generic entry point is short:

 go
 
 
// src/internal/runtime/maps/memhash_aes.go:13
const memHashAESImplemented = true

func MemHash(p unsafe.Pointer, h, s uintptr) uintptr {
	if s >= MinAeshashSize {
		return memHashAES(p, h, s)
	}
	return memHashFallback(p, h, s)
}

func MemHash32(k uint32, h uintptr) uintptr {
	if useAeshash32 {
		return memHash32AES(k, h)
	}
	return memHash32Fallback(k, h)
}

func MemHash64(k uint64, h uintptr) uintptr {
	if useAeshash64 {
		return memHash64AES(k, h)
	}
	return memHash64Fallback(k, h)
}

func StrHash(s string, h uintptr) uintptr {
	return MemHash(unsafe.Pointer(unsafe.StringData(s)), h, uintptr(len(s)))
}

Note the h parameter: that is the per-map seed, threaded through from typ.Hasher(key, m.seed).

On architectures without AES at all, the same file shape exists but every AES entry point panics and everything falls back:

 go
 
 
// src/internal/runtime/maps/memhash_noaes.go:13
// AES hashing not implemented for these architectures
const memHashAESImplemented = false
const memHashUsesVAES = false

func memHash32AES(k uint32, h uintptr) uintptr {
	panic("memHash32AES not implemented")
}

func memHash64AES(k uint64, h uintptr) uintptr {
	panic("memHash64AES not implemented")
}

func memHashAES(p unsafe.Pointer, h, s uintptr) uintptr {
	panic("memHashAES not implemented")
}

func MemHash(p unsafe.Pointer, h, s uintptr) uintptr {
	return memHashFallback(p, h, s)
}

func MemHash32(k uint32, h uintptr) uintptr {
	return memHash32Fallback(k, h)
}

func MemHash64(k uint64, h uintptr) uintptr {
	return memHash64Fallback(k, h)
}

The AES hash itself

The amd64 implementation is assembly, and the first thing it does is mix the per-map seed with the per-process key schedule:

 asm
 
 
// src/internal/runtime/maps/memhash_amd64.s:7
// func memHashAES(p unsafe.Pointer, h, s uintptr) uintptr
// hash function using AES hardware instructions
TEXT ·memHashAES<ABIInternal>(SB),NOSPLIT,$0-32
	// AX: data
	// BX: hash seed
	// CX: length
	// At return: AX = return value

	// Fill an SSE register with our seeds.
	MOVQ	BX, X0				// 64 bits of per-table hash seed
	PINSRW	$4, CX, X0			// 16 bits of length
	PSHUFHW $0, X0, X0			// repeat length 4 times total
	MOVO	X0, X1				// save unscrambled seed
	PXOR	·aeskeysched(SB), X0	// xor in per-process seed
	AESENC	X0, X0				// scramble seed

	CMPQ	CX, $16
	JB	aes0to15
	JE	aes16
	CMPQ	CX, $32
	JBE	aes17to32
	CMPQ	CX, $64
	JBE	aes33to64
	CMPQ	CX, $128
	JBE	aes65to128
	JMP	aes129plus

The shape of the whole function is “one AES round to scramble the seed, then one AES round per 16 bytes of data, then fold the results together”. The seed is placed in the low 64 bits of an XMM register, the length is broadcast into the high bits, and the per-process key schedule is XORed in before the first round. Because the data is XORed with the scrambled seed before being encrypted, the hash depends on both the key bytes and the length.

The final fold for the long case looks like this:

 asm
 
 
// src/internal/runtime/maps/memhash_amd64.s:335
	PXOR	X12, X8
	PXOR	X13, X9
	PXOR	X14, X10
	PXOR	X15, X11
	PXOR	X10, X8
	PXOR	X11, X9
	PXOR	X9, X8
	// X15 must be zero on return
	PXOR	X15, X15
	MOVQ	X8, AX	// return X8
	RET

Under the goexperiment.simd build, the same algorithm is expressed with intrinsics instead of assembly, using VAES:

 go
 
 
// src/internal/runtime/maps/memhash_aes_simd.go:16
func memHash32AES(k uint32, seed uintptr) uintptr {
	var state archsimd.Uint64x2
	state = state.SetElem(0, uint64(seed)).SetElem(1, uint64(k))

	hash := state.
		AsUint8x16().
		AESEncryptOneRound(archsimd.LoadUint32x4Array((*[4]uint32)(unsafe.Pointer(&aeskeysched[0])))).
		AESEncryptOneRound(archsimd.LoadUint32x4Array((*[4]uint32)(unsafe.Pointer(&aeskeysched[16])))).
		AESEncryptOneRound(archsimd.LoadUint32x4Array((*[4]uint32)(unsafe.Pointer(&aeskeysched[32])))).
		AsUint64x2().
		GetElem(0)
	return uintptr(hash)
}

Because VAES is an AVX instruction, the runtime disables the AES path entirely on machines that have AES-NI but not AVX — you can see that override in AlgInit above.

The wyhash fallback

Everything that is not “long enough for AES” goes through a scalar function that is explicitly inspired by wyhash:

 go
 
 
// src/internal/runtime/maps/runtime_hash64.go:17
const (
	m5 = 0x1d8e4e27c47d124f
)

func memHashFallback(p unsafe.Pointer, seed, s uintptr) uintptr {
	var a, b uintptr
	seed ^= hashkey[0]
	switch {
	case s == 0:
		return seed
	case s < 4:
		a = uintptr(*(*byte)(p))
		a |= uintptr(*(*byte)(add(p, s>>1))) << 8
		a |= uintptr(*(*byte)(add(p, s-1))) << 16
	case s == 4:
		a = r4(p)
		b = a
	case s < 8:
		a = r4(p)
		b = r4(add(p, s-4))
	case s == 8:
		a = r8(p)
		b = a
	case s <= 16:
		a = r8(p)
		b = r8(add(p, s-8))
	default:
		l := s
		if l > 48 {
			seed1 := seed
			seed2 := seed
			for ; l > 48; l -= 48 {
				seed = mix(r8(p)^hashkey[1], r8(add(p, 8))^seed)
				seed1 = mix(r8(add(p, 16))^hashkey[2], r8(add(p, 24))^seed1)
				seed2 = mix(r8(add(p, 32))^hashkey[3], r8(add(p, 40))^seed2)
				p = add(p, 48)
			}
			seed ^= seed1 ^ seed2
		}
		for ; l > 16; l -= 16 {
			seed = mix(r8(p)^hashkey[1], r8(add(p, 8))^seed)
			p = add(p, 16)
		}
		a = r8(add(p, l-16))
		b = r8(add(p, l-8))
	}

	return mix(m5^s, mix(a^hashkey[1], b^seed))
}

The structure is the classic wyhash shape: read the input as two 64-bit halves (overlapping for short inputs), mix them with a single 64x64 multiply, and fold in the length. The mix helper is literally one multiply:

 go
 
 
// src/internal/runtime/maps/runtime_hash64.go:77
func mix(a, b uintptr) uintptr {
	hi, lo := bits.Mul64(uint64(a), uint64(b))
	return uintptr(hi ^ lo)
}

func r4(p unsafe.Pointer) uintptr {
	return uintptr(readUnaligned32(p))
}

func r8(p unsafe.Pointer) uintptr {
	return uintptr(readUnaligned64(p))
}

hi ^ lo of a 64x64->128 multiply is a very good avalanche for the price of one MULQ. The constant m5 is wyhash’s secret constant, and m5^s mixes the length into the final value so that "ab" and "ab\x00" do not hash the same.

Note seed ^= hashkey[0] on the very first line: the per-map seed is combined with the per-process secret before anything else happens.

On 32-bit platforms the same job is done with 32-bit halves:

 go
 
 
// src/internal/runtime/maps/runtime_hash32.go:57
func mix32(a, b uint32) (uint32, uint32) {
	c := uint64(a^uint32(hashkey[1])) * uint64(b^uint32(hashkey[2]))
	return uint32(c), uint32(c >> 32)
}

A shortcut worth knowing about

The string fast path has one more trick. For long strings, Go compares a few bytes before hashing at all, and skips the hash entirely if there is an exact match:

 go
 
 
// src/internal/runtime/maps/runtime_faststr.go:30
	// The 64 threshold was chosen based on performance of BenchmarkMapStringKeysEight,
	// where there are 8 keys to check, all of which don't quick-match the lookup key.
	// In that case, we can save hashing the lookup key. That savings is worth this extra code
	// for strings that are long enough that hashing is expensive.
	if len(key) > 64 {
		// String hashing and equality might be expensive. Do a quick check first.
		j := abi.MapGroupSlots
		for i := range abi.MapGroupSlots {
			if ctrls&(1<<7) == 0 && longStringQuickEqualityTest(key, *(*string)(slotKey)) {

Eight quick prefix comparisons, and if one of them hits, no hashing is needed at all. For a map with eight long string keys, that is the difference between hashing a 10 KB string and comparing a few dozen bytes.

Trade-offs

What the two-layer seeding buys:

Hash flooding is impractical. The per-map seed means the collisions an attacker found yesterday do not work today, and the seed rotates whenever the map empties.
The per-process secret means even a zero-seed map is not attackable. Two programs running the same binary do not produce the same hash for the same key.
The AES path is genuinely hard to invert. Three AES rounds per block with a random key schedule is not something you brute-force in a web request.

What it costs:

The hash of a key changes when the map’s seed changes. Any code that caches “hash of this key” outside the map is broken.
Two secrets means two places to get it wrong. The scalar path mixes hashkey[0..3]; the AES path mixes aeskeysched. They are separate mechanisms, and the compiler and runtime both rely on them agreeing.
The threshold is a benchmark result, not a law. MinAeshashSize = 9 on amd64 was measured on a Threadripper; a different microarchitecture might want a different number.
AES-NI is not universal. The feature bits have to be checked at startup, the key schedule has to be aligned in memory (there is an explicit runtime check for that), and the code has to be duplicated in assembly and in intrinsics.

Caveats

Do not use Go’s map hash as a content hash. It is seeded per map and per process; two runs of the same program will produce different values for the same key. If you need a stable hash, use hash/maphash (which is explicitly a stable hash) or crypto/sha256.

maphash.Hash and map keys use different mechanisms. maphash gives you a Seed you can keep and reuse, deliberately stable across a program’s lifetime. The map’s internal seed is not exposed and rotates.

The AES path is not used for small keys. If you were expecting AES-NI to be doing the work for map[int]int or map[int64]int, it is not — the threshold on amd64 is 9 bytes, and integer keys fall to the scalar path.

NaN keys are special. Float keys get a random hash component, because NaN is never equal to itself and would otherwise create unbounded chains:

 go
 
 
// src/runtime/alg.go:118
func f32hash(p unsafe.Pointer, h uintptr) uintptr {
	f := *(*float32)(p)
	switch {
	case f == 0:
		return trimHash(c1 * (c0 ^ h)) // +0, -0
	case f != f:
		return trimHash(c1 * (c0 ^ h ^ uintptr(rand()))) // any kind of NaN
	default:
		return memhash(p, h, 4)
	}
}

The hash seed is not a defence against a determined attacker who can keep the map full. The protection is a cost trade: to keep the collisions working, the attacker has to keep a large non-empty map alive, which costs you memory. It raises the cost of the attack; it does not make it impossible.

Wasm uses 32-bit hashes. The hash size is fixed at compile time per platform, and on Wasm it is 4 bytes rather than 8.

Wrapping up

The one thing to remember: every map key hash mixes in two secrets — a process-wide key generated at startup and a per-map random seed — and the seed is replaced whenever the map empties or is cleared. That is why the same key hashes differently in two different maps, and differently again in the same map after a Clear.

The part people get wrong: assuming AES-NI hashes everything. On amd64 the AES path only kicks in at 9 bytes, so integer keys use the scalar wyhash-style multiply-fold function, and the AES key schedule is only one of the two secrets in play.

What to go do about it: if you are writing code that depends on hash values, use hash/maphash explicitly rather than relying on the map’s internal hash. If you are benchmarking, remember that the map’s hash cost depends on the key size: a map[string] with long keys can skip hashing entirely on a prefix match, while a map[int64] never uses AES at all.

Go's Maps Are Swiss Tables: Groups of 8 Slots, Match Bytes and a Tombstone

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

TL;DR: Go’s map is a Swiss table. Slots live in groups of eight, and each group carries one 64-bit control word whose bytes are either “empty”, “deleted”, or the low seven bits of the key’s hash. A lookup compares all eight control bytes in one operation, so eight probe steps happen at once, and the table refuses to fill past 7/8 so there is always an empty slot to stop the probe sequence.

Every language needs a hash map, and every hash map is a compromise between three things: how fast a lookup is, how fast an insert is, and how much memory the table burns while sitting there doing nothing.

Go’s built-in map used to be a plain open-addressed table with buckets of eight slots and a tophash byte per slot. Then, in Go 1.24, it was rewritten around Abseil’s “Swiss Table” design, and the rewrite moved a lot of code out of the runtime and into a standalone package. This is a walk through that implementation, based on reading the Go 1.28 development tree (src/internal/runtime/maps).

The vocabulary

The package documents its own terms up front, and the terminology is worth internalising because every other file uses it:

 go
 
 
// src/internal/runtime/maps/map.go:23
// - Slot: A storage location of a single key/element pair.
// - Group: A group of abi.MapGroupSlots (8) slots, plus a control word.
// - Control word: An 8-byte word which denotes whether each slot is empty,
// deleted, or used. If a slot is used, its control byte also contains the
// lower 7 bits of the hash (H2).
// - H1: Upper 57 bits of a hash.
// - H2: Lower 7 bits of a hash.
// - Table: A complete "Swiss Table" hash table. A table consists of one or
// more groups for storage plus metadata to handle operation and determining
// when to grow.
// - Map: The top-level Map type consists of zero or more tables for storage.
// The upper bits of the hash select which table a key belongs to.
// - Directory: Array of the tables used by the map.
//
// At its core, the table design is similar to a traditional open-addressed
// hash table. Storage consists of an array of groups, which effectively means
// an array of key/elem slots with some control words interspersed. Lookup uses
// the hash to determine an initial group to check. If, due to collisions, this
// group contains no match, the probe sequence selects the next group to check
// (see below for more detail about the probe sequence).
//
// The key difference occurs within a group. In a standard open-addressed
// linear probed hash table, we would check each slot one at a time to find a
// match. A swiss table utilizes the extra control word to check all 8 slots in
// parallel.
//
// Each byte in the control word corresponds to one of the slots in the group.
// In each byte, 1 bit is used to indicate whether the slot is in use, or if it
// is empty/deleted. The other 7 bits contain the lower 7 bits of the hash for
// the key in that slot. See [ctrl] for the exact encoding.
//
// During lookup, we can use some clever bitwise manipulation to compare all 8
// 7-bit hashes against the input hash in parallel (see [ctrlGroup.matchH2]).
// That is, we effectively perform 8 steps of probing in a single operation.
// With SIMD instructions, this could be extended to 16 slots with a 16-byte
// control word.
//
// Since we only use 7 bits of the 64 bit hash, there is a 1 in 128 (~0.7%)
// probability of false positive on each slot, but that's fine: we always need
// double check each match with a standard key comparison regardless.

That last paragraph is the whole trick in one sentence. The control byte is a filter, not a proof. A group of eight slots holds eight hashes; if you could compare all eight against your hash in one CPU operation, then in the common case a lookup becomes “one comparison, and then at most a couple of real key comparisons to confirm”.

The control byte

The encoding is three states, and the constants say so:

 go
 
 
// src/internal/runtime/maps/group.go:14
const (
	// Maximum load factor prior to growing.
	//
	// 7/8 is the same load factor used by Abseil, but Abseil defaults to
	// 16 slots per group, so they get two empty slots vs our one empty
	// slot. We may want to reevaluate if this is best for us.
	maxAvgGroupLoad = 7

	ctrlEmpty ctrl = 0b10000000
	ctrlDeleted ctrl = 0b11111110

	bitsetLSB = 0x0101010101010101
	bitsetMSB = 0x8080808080808080
	bitsetL7B = 0x7f7f7f7f7f7f7f7f
	bitsetEmpty = bitsetLSB * uint64(ctrlEmpty)
)

And the byte layout is documented right above the ctrl type:

 go
 
 
// src/internal/runtime/maps/group.go:115
// Each slot in the hash table has a control byte which can have one of three
// states: empty, deleted, and full. They have the following bit patterns:
//
//	 empty: 1 0 0 0 0 0 0 0
//	deleted: 1 1 1 1 1 1 1 0
//	 full: 0 h h h h h h h // h represents the H2 hash bits
//
// TODO(prattmic): Consider inverting the top bit so that the zero value is empty.
type ctrl uint8

So a group looks like this:

 text
 
 
 control word (one uint64, eight bytes, one per slot)

 byte: 0x05 0x7f 0x80 0x12 0x80 0x33 0x80 0x00
 full full empty full empty full empty full
 H2=5 H2=127 empty H2=18 empty H2=51 empty H2=0
 | | | | |
 v v v v v
 slots: [k0] [k1] [ -- ] [k3] [ -- ] [k5] [ -- ] [k7]
 [e0] [e1] [e3] [e5] [e7]

“Full” is the only state with bit 7 clear. “Empty” is 0b10000000 exactly. “Deleted” is 0b11111110 — nearly all ones, deliberately, so that it can never be confused with a real H2 value.

Finding “all slots whose H2 equals mine” is one expression on a 64-bit word:

 go
 
 
// src/internal/runtime/maps/group.go:151
// matchH2 returns the set of slots which are full and for which the 7-bit hash
// matches the given value. May return false positives.
func (g ctrlGroup) matchH2(h uintptr) bitset {
	return ctrlGroupMatchH2(g, h)
}

// Portable implementation of matchH2.
//
// Note: On AMD64, this is an intrinsic implemented with SIMD instructions. See
// note on bitset about the packed intrinsified return value.
func ctrlGroupMatchH2(g ctrlGroup, h uintptr) bitset {
	v := uint64(g) ^ (bitsetLSB * uint64(h))
	if goarch.IsArm64 == 1 {
		v = ^v
		return bitset((v&bitsetL7B + bitsetLSB) & (v & bitsetMSB))
	}
	// NB: This generic matching routine produces false positive matches when
	// h is 2^N and the control bytes have a seq of 2^N followed by 2^N+1. For
	// example: if ctrls==0x0302 and h=02, we'll compute v as 0x0100. When we
	// subtract off 0x0101 the first 2 bytes we'll become 0xffff and both be
	// considered matches of h. The false positive matches are not a problem,
	// just a rare inefficiency. Note that they only occur if there is a real
	// match and never occur on ctrlEmpty, or ctrlDeleted. The subsequent key
	// comparisons ensure that there is no correctness issue.
	return bitset(((v - bitsetLSB) &^ v) & bitsetMSB)
}

The magic is ((v - bitsetLSB) &^ v) & bitsetMSB. XOR the control word with the broadcast hash byte to make matching bytes zero, then subtract a broadcast 0x01 — a borrow propagates up through a run of zero bytes and the MSB mask picks out the byte where the borrow landed. On AMD64 and ARM64 this whole thing is a single SIMD instruction sequence; on other platforms it is the portable arithmetic above.

The Map struct

The top-level object is small, and the compiler mirrors it exactly, so the runtime and the compiler can never disagree about the layout:

 go
 
 
// src/internal/runtime/maps/map.go:213
// Note: changes here must be reflected in cmd/compile/internal/reflectdata/map.go:MapType.
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 directory of tables.
	//
	// Normally dirPtr points to an array of table pointers
	//
	// dirPtr *[dirLen]*table
	//
	// The length (dirLen) of this array is `1 << globalDepth`. Multiple
	// entries may point to the same table. See top-level comment for more
	// details.
	//
	// Small map optimization: if the map always contained
	// abi.MapGroupSlots or fewer entries, it fits entirely in a
	// single group. In that case dirPtr points directly to a single group.
	//
	// dirPtr *group
	//
	// In this case, dirLen is 0. used counts the number of used slots in
	// the group. Note that small maps never have deleted slots (as there
	// is no probe sequence to maintain).
	dirPtr unsafe.Pointer
	dirLen int

	// The number of bits to use in table directory lookups.
	globalDepth uint8

	// The number of bits to shift out of the hash for directory lookups.
	// On 64-bit systems, this is 64 - globalDepth.
	globalShift uint8

	// writing is a flag that is toggled (XOR 1) while the map is being
	// written. Normally it is set to 1 when writing, but if there are
	// multiple concurrent writers, then toggling increases the probability
	// that both sides will detect the race.
	writing uint8

	// tombstonePossible is false if we know that no table in this map
	// contains a tombstone.
	tombstonePossible bool

	// clearSeq is a sequence counter of calls to Clear. It is used to
	// detect map clears during iteration.
	clearSeq uint64
}

dirPtr is doing double duty: it points at a []*table directory for a real map, or straight at a single group for a small map. dirLen == 0 is the sentinel that says “small”.

Small maps: one group, no directory

A map with eight or fewer entries never needs a directory, a table, or a probe sequence. It is a single group, and the whole lookup is one control word match:

 go
 
 
// src/internal/runtime/maps/map.go:465
func (m *Map) getWithKeySmall(typ *abi.MapType, hash uintptr, key unsafe.Pointer) (unsafe.Pointer, unsafe.Pointer, bool) {
	g := groupReference{
		data: m.dirPtr,
	}

	match := g.ctrls().matchH2(h2(hash))

	for match != 0 {
		i := match.first()

		slotKey := g.key(typ, i)
		if typ.IndirectKey() {
			slotKey = *((*unsafe.Pointer)(slotKey))
		}

		if typ.Key.Equal(key, slotKey) {
			slotElem := g.elem(typ, i)
			if typ.IndirectElem() {
				slotElem = *((*unsafe.Pointer)(slotElem))
			}
			return slotKey, slotElem, true
		}

		match = match.removeFirst()
	}

	// No match here means key is not in the map.
	// (A single group means no need to probe or check for empty).
	return nil, nil, false
}

Creating one is free, too — no allocation at all until the first assignment:

 go
 
 
// src/internal/runtime/maps/map.go:350
func NewEmptyMap() *Map {
	m := new(Map)
	m.seed = uintptr(rand())
	// See comment in NewMap. No need to eager allocate a group.
	return m
}

Inserting into a small map is the same idea with a fallback for the full case:

 go
 
 
// src/internal/runtime/maps/map.go:586
	// There can't be deleted slots, small maps can't have them
	// (see deleteSmall). Use matchEmptyOrDeleted as it is a bit
	// more efficient than matchEmpty.
	match = g.ctrls().matchEmptyOrDeleted()
	if match == 0 {
		// No empty slot found. Need to grow the map.
		return nil
	}

	i := match.first()

	slotKey := g.key(typ, i)
	if typ.IndirectKey() {
		kmem := newobject(typ.Key)
		*(*unsafe.Pointer)(slotKey) = kmem
		slotKey = kmem
	}
	typedmemmove(typ.Key, slotKey, key)

	slotElem := g.elem(typ, i)
	if typ.IndirectElem() {
		emem := newobject(typ.Elem)
		*(*unsafe.Pointer)(slotElem) = emem
		slotElem = emem
	}

	g.ctrls().set(i, ctrl(h2(hash)))
	m.used++

	return slotElem
}

Wait — small maps never have deleted slots, yet the code says “use matchEmptyOrDeleted as it is a bit more efficient than matchEmpty”. Because the deleted marker 0b11111110 has bit 7 set, it is caught by the same mask as empty, and in a small map no slot is ever in that state, so the cheaper bit test is safe.

The 7/8 load factor

The table refuses to be full, because an empty slot is the terminator of every probe sequence:

 go
 
 
// src/internal/runtime/maps/table.go:114
// maxGrowthLeft is the number of inserts we can do before
// resizing, starting from an empty table.
func (t *table) maxGrowthLeft() uint16 {
	if t.capacity == 0 {
		// No real reason to support zero capacity table, since an
		// empty Map simply won't have a table.
		panic("table must have positive capacity")
	} else if t.capacity <= abi.MapGroupSlots {
		// If the map fits in a single group then we're able to fill all of
		// the slots except 1 (an empty slot is needed to terminate find
		// operations).
		//
		// TODO(go.dev/issue/54766): With a special case in probing for
		// single-group tables, we could fill all slots.
		return t.capacity - 1
	} else {
		if t.capacity > math.MaxUint16/maxAvgGroupLoad {
			panic("overflow")
		}
		return (t.capacity * maxAvgGroupLoad) / abi.MapGroupSlots
	}

}

Seven usable slots per group of eight. That is the “7/8” in the name of the design, and it is why growthLeft counts down as you insert.

Looking up in a full map

Now the real path. Pick a table with the high bits of the hash, pick a group with the next bits, and walk a quadratic probe sequence:

 go
 
 
// src/internal/runtime/maps/table.go:193
	seq := makeProbeSeq(h1(hash), t.groups.lengthMask)
	h2Hash := h2(hash)
	for ; ; seq = seq.next() {
		g := t.groups.group(typ, seq.offset)

		match := g.ctrls().matchH2(h2Hash)

		for match != 0 {
			i := match.first()

			slotKey := g.key(typ, i)
			if typ.IndirectKey() {
				slotKey = *((*unsafe.Pointer)(slotKey))
			}
			if typ.Key.Equal(key, slotKey) {
				slotElem := g.elem(typ, i)
				if typ.IndirectElem() {
					slotElem = *((*unsafe.Pointer)(slotElem))
				}
				return slotKey, slotElem, true
			}
			match = match.removeFirst()
		}

		match = g.ctrls().matchEmpty()
		if match != 0 {
			// Finding an empty slot means we've reached the end of
			// the probe sequence.
			return nil, nil, false
		}
	}
}

Three steps: match the control word, confirm with a real key comparison, and if the group has an empty slot, stop — the key is not in the map.

The probe sequence itself is triangular-numbered, which is the classic quadratic probing trick:

 go
 
 
// src/internal/runtime/maps/table.go:1337
type probeSeq struct {
	mask uint64
	offset uint64
	index uint64
}

func makeProbeSeq(hash uintptr, mask uint64) probeSeq {
	return probeSeq{
		mask: mask,
		offset: uint64(hash) & mask,
		index: 0,
	}
}

func (s probeSeq) next() probeSeq {
	s.index++
	s.offset = (s.offset + s.index) & s.mask
	return s
}

The comment above the type explains why this visits every group exactly once: the triangular numbers (i^2 + i)/2 are a bijection modulo any power of two, which is why the number of groups must be a power of two.

Putting, and why tombstones exist

Insertion is the same walk with one extra rule: if the group is full but the table has room, remember the first tombstone you passed and reuse it instead of consuming new capacity:

 go
 
 
// src/internal/runtime/maps/table.go:304
		// No existing slot for this key in this group. Is this the end
		// of the probe sequence?
		match = g.ctrls().matchEmptyOrDeleted()
		if match == 0 {
			continue // nothing but filled slots. Keep probing.
		}
		i := match.first()
		if g.ctrls().get(i) == ctrlDeleted {
			// There are some deleted slots. Remember
			// the first one, and keep probing.
			if firstDeletedGroup.data == nil {
				firstDeletedGroup = g
				firstDeletedSlot = i
			}
			continue
		}
		// We've found an empty slot, which means we've reached the end of
		// the probe sequence.

		// If we found a deleted slot along the way, we can
		// replace it without consuming growthLeft.
		if firstDeletedGroup.data != nil {
			g = firstDeletedGroup
			i = firstDeletedSlot
			t.growthLeft++ // will be decremented below to become a no-op.
		}

		// If we have no space left, first try to remove some tombstones.
		if t.growthLeft == 0 {
			t.pruneTombstones(typ, m)
		}

		// If there is room left to grow, just insert the new entry.
		if t.growthLeft > 0 {
			slotKey := g.key(typ, i)
			if typ.IndirectKey() {
				kmem := newobject(typ.Key)
				*(*unsafe.Pointer)(slotKey) = kmem
				slotKey = kmem
			}
			typedmemmove(typ.Key, slotKey, key)

			slotElem := g.elem(typ, i)
			if typ.IndirectElem() {
				emem := newobject(typ.Elem)
				*(*unsafe.Pointer)(slotElem) = emem
				slotElem = emem
			}

			g.ctrls().set(i, ctrl(h2Hash))
			t.growthLeft--
			t.used++
			m.used++

			t.checkInvariants(typ, m)
			return slotElem, true
		}

		t.rehash(typ, m)
		return nil, false
	}
}

Now the reason tombstones exist. Suppose you delete a key from a group that has no empty slot. If you marked that slot empty, then a later lookup for some other key whose probe sequence passes through this group would stop there and conclude “not found” — even though the key it wants is further along the sequence. So you must not create an empty slot in the middle of a probe sequence. You write a tombstone instead:

 go
 
 
// src/internal/runtime/maps/table.go:520
				// Only a full group can appear in the middle
				// of a probe sequence (a group with at least
				// one empty slot terminates probing). Once a
				// group becomes full, it stays full until
				// rehashing/resizing. So if the group isn't
				// full now, we can simply remove the element.
				// Otherwise, we create a tombstone to mark the
				// slot as deleted.
				var tombstone bool
				if g.ctrls().matchEmpty() != 0 {
					g.ctrls().set(i, ctrlEmpty)
					t.growthLeft++
				} else {
					g.ctrls().set(i, ctrlDeleted)
					tombstone = true
				}

A tombstone is a slot that is occupied (so probing walks past it) but never matches any hash (so nothing is ever found in it). Tombstones do count against the load factor, which is why the table eventually has to be cleaned up — pruneTombstones walks the probe sequence of every live key to find the tombstones that are genuinely unreachable and reclaim them.

Growing

Growth is not a simple “make it bigger” because the probe sequence depends on the number of groups: reordering slots to match a new probe sequence would break iteration. So the whole table is replaced.

 go
 
 
// src/internal/runtime/maps/table.go:1205
// Replaces the table with one larger table or two split tables to fit more
// entries. Since the table is replaced, t is now stale and should not be
// modified.
func (t *table) rehash(typ *abi.MapType, m *Map) {
	// TODO(prattmic): SwissTables typically perform a "rehash in place"
	// operation which recovers capacity consumed by tombstones without growing
	// the table by reordering slots as necessary to maintain the probe
	// invariant while eliminating all tombstones.
	//
	// However, it is unclear how to make rehash in place work with
	// iteration. Since iteration simply walks through all slots in order
	// (with random start offset), reordering the slots would break
	// iteration.
	//
	// As an alternative, we could do a "resize" to new groups allocation
	// of the same size. This would eliminate the tombstones, but using a
	// new allocation, so the existing grow support in iteration would
	// continue to work.

	newCapacity := 2 * t.capacity
	if newCapacity <= maxTableCapacity {
		t.grow(typ, m, newCapacity)
		return
	}

	t.split(typ, m)
}

Doubling stops at maxTableCapacity (1024 slots). Past that, the table is split in two and the map grows a directory level instead. That is extendible hashing: the high bits of the hash select a directory entry, and the directory points at a table.

 text
 
 
 directory (globalDepth = 2)

 +----+
 | 00 | --\
 +----+ +--> table (localDepth = 1)
 | 01 | --/
 +----+
 | 10 | ------> table (localDepth = 2)
 +----+
 | 11 | ------> table (localDepth = 2)
 +----+

Multiple directory entries may point at the same table, which is why a directory of size four can hold three tables. This is what makes growth incremental: instead of rehash-ing the entire map, one table grows at a time, and the work per insert is bounded.

The doubling itself copies every live entry into a fresh table:

 go
 
 
// src/internal/runtime/maps/table.go:1286
// grow the capacity of the table by allocating a new table with a bigger array
// and uncheckedPutting each element of the table into the new table (we know
// that no insertion here will Put an already-present value), and discard the
// old table.
func (t *table) grow(typ *abi.MapType, m *Map, newCapacity uint16) {
	newTable := newTable(typ, uint64(newCapacity), t.index, t.localDepth)

	if t.capacity > 0 {
		for i := uint64(0); i <= t.groups.lengthMask; i++ {
			g := t.groups.group(typ, i)
			for j := uintptr(0); j < abi.MapGroupSlots; j++ {
				if (g.ctrls().get(j) & ctrlEmpty) == ctrlEmpty {
					// Empty or deleted
					continue
				}

				key := g.key(typ, j)
				if typ.IndirectKey() {
					key = *((*unsafe.Pointer)(key))
				}

				elem := g.elem(typ, j)
				if typ.IndirectElem() {
					elem = *((*unsafe.Pointer)(elem))
				}

				hash := typ.Hasher(key, m.seed)

				newTable.uncheckedPutSlot(typ, hash, key, elem)
			}
		}
	}

	newTable.checkInvariants(typ, m)
	m.replaceTable(newTable)
	t.index = -1
}

Note that every key is rehashed during a grow. That is not an oversight: the hash is seeded per map, and the seed can change (see below), so the old hash values are not reusable.

Clearing

Clear is not free — it walks the tables and zeroes the groups that have anything in them:

 go
 
 
// src/internal/runtime/maps/map.go:755
// Clear deletes all entries from the map resulting in an empty map.
func (m *Map) Clear(typ *abi.MapType) {
	if m == nil || m.Used() == 0 && !m.tombstonePossible {
		return
	}

	if m.writing != 0 {
		fatal("concurrent map writes")
	}
	m.writing ^= 1 // toggle, see comment on writing

	if m.dirLen == 0 {
		m.clearSmall(typ)
	} else {
		var lastTab *table
		for i := range m.dirLen {
			t := m.directoryAt(uintptr(i))
			if t == lastTab {
				continue
			}
			t.Clear(typ)
			lastTab = t
		}
		m.used = 0
		m.tombstonePossible = false
		// TODO: shrink directory?
	}
	m.clearSeq++

	// Reset the hash seed to make it more difficult for attackers to
	// repeatedly trigger hash collisions. See https://go.dev/issue/25237.
	m.seed = uintptr(rand())

	if m.writing == 0 {
		fatal("concurrent map writes")
	}
	m.writing ^= 1
}

Two things worth noting. The directory is not shrunk, only cleared — a Clear on a map with a big directory leaves the directory allocated. And the seed is replaced, so the same keys will hash differently after a clear.

Iteration starts at a random slot

Go randomises map iteration order on purpose, so that code cannot accidentally depend on it. The iterator picks a random offset within the table and a random offset within the directory:

 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
}

 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 random numbers: one picks where in the slot space to start, one picks where in the directory to start. The iterator also holds on to the old table when the map grows underneath it, so it can re-look-up each key in the new table to return the latest value — that is the “entries modified during iteration must return their latest value” rule from the spec, and it is why iteration has to re-hash keys.

Trade-offs

What the Swiss table buys over a plain open-addressed map:

One control-word comparison covers eight slots. A lookup does one 64-bit (or SIMD) comparison instead of eight byte comparisons.
Fewer false key comparisons. The H2 filter means the expensive Equal call happens rarely — the code comments estimate fewer than 1/8 false positives per find.
Cheap small maps. Up to eight entries live in one group with no directory, no table, and (for an empty map) no allocation at all.
Incremental growth. A map that outgrows one table splits it and grows the directory instead of rehashing everything, so an insert never pays for a whole-map resize.

What it costs:

Tombstones. Deleting from a full group leaves a slot that is neither empty nor reusable, and it counts against the load factor.
Rehashing on grow. Every key is hashed again when a table is rebuilt.
A more complex invariant. “Empty terminates the probe sequence” means delete, insert, and prune all have to agree with each other.
A bigger control word per group. One extra byte per slot (8 bytes per 8 slots) on top of the key and element data.

Caveats

The load factor is a hard 7/8. A table can never be completely full. That is not a tuning knob you can change; it is a correctness requirement of the probe algorithm.

A nil map read is fine, a nil map write panics. The runtime’s mapassign path checks for a nil map explicitly and panics with “assignment to entry in nil map”. A make(map[K]V) is not the same thing as a nil map.

Maps are not safe for concurrent use. The writing flag is a cheap sanity check that detects the most obvious races, not a lock. Two goroutines writing to the same map is a data race and the runtime will eventually crash with “concurrent map writes”.

Iteration order is random and can change between runs. Worse, the Go spec explicitly allows entries added during iteration to be returned, and entries deleted during iteration to be skipped. If you need a stable order, sort the keys.

Clear keeps the directory. The tables are emptied but the directory is not shrunk, so a map that was once huge stays shaped like it.

The seed is regenerated when the map empties out. After a delete that takes the map to zero entries, the seed is replaced. That means the hash of a given key changes over the life of the map, which is exactly why growing a table has to rehash every key.

Wrapping up

The one thing to remember: a Go map is a table of groups of eight slots, each group carrying a control word where every byte is either empty, deleted, or seven bits of the key’s hash. Lookups compare that word against the hash of the key in one shot, and only the survivors get a real key comparison.

The part people get wrong: the “deleted” state. Deleting a key from a full group cannot write an empty marker, because an empty marker would cut the probe sequence short and make later lookups fail. It writes a tombstone instead, and tombstones are why the table has to be pruned or grown eventually.

What to go do about it: if you are building a map-heavy workload, stop thinking about “the map” as one object and start thinking about the table that holds your keys. Pre-sizing with make(map[K]V, n) avoids repeated doubling; keeping keys small keeps them stored inline instead of indirectly; and if you are iterating, remember you are getting a snapshot of a moving target.

Maps 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

How Go Hashes Map Keys: AES-NI, wyhash and the Seed

Which hash function, for which key

Two secrets, not one

Choosing an implementation at startup

The size threshold

The dispatch

The AES hash itself

The wyhash fallback

A shortcut worth knowing about

Trade-offs

Caveats

Wrapping up

Further reading

Go's Maps Are Swiss Tables: Groups of 8 Slots, Match Bytes and a Tombstone

The vocabulary

The control byte

The Map struct

Small maps: one group, no directory

The 7/8 load factor

Looking up in a full map

Putting, and why tombstones exist

Growing

Clearing

Iteration starts at a random slot

Trade-offs

Caveats

Wrapping up

Further reading

The `maps` package inherits it