Go Map Implementation Details

Below are some commonly‐noted issues and points of potential confusion or inaccuracy in that description of Go’s map implementation. (These largely reflect Go’s current runtime behavior; details can and do change between Go releases.)

1. Over-simplification of bucket structure
   The description says:

   Internally, a hash table is an array of buckets, and each bucket is a pointer to an array of key-value pairs.
   In modern Go (1.9+), a bucket is actually a struct containing:

   • An array (of length 8) for keys
   • A parallel array (of length 8) for values
   • A small top‐hash array (of length 8) that stores the top bits of each key's hash
   • A pointer to any overflow bucket (if there are more than 8 entries that fall into one bucket).

   So rather than each bucket simply being a “pointer to an array,” a bucket includes all of that storage inlined, plus optional overflow buckets when there isn’t enough room.

2. Fixed size of eight elements (implementation detail)
   While it’s correct that Go’s runtime currently uses 8 key/value slots per bucket, that is (strictly speaking) an implementation detail and not guaranteed by the language specification. It happens to be 8 in the reference implementation, but the spec doesn’t require that it remain 8 forever. Relying on it in production code is unwise.

3. Hash function “stability”
   Go’s map implementation does indeed use a hash function so that the same key consistently ends up in the same bucket (within a single run of the program). However:

   • Go does randomize the hash seed on each program run to mitigate DoS attacks. This means that the exact bucket for a key can differ between runs (though it’s stable within a single run).
   • When a map grows or shrinks, a key might be moved to a different bucket (due to the way Go does incremental rehashing during map resizing).

4. Insertion, lookup, deletion steps
   The high-level description that “each operation is done by associating a key with an array index via a hash function” glosses over some details like:

   • The map’s load factor, which triggers growth and bucket splitting.
   • Collision resolution, which happens partly by storing the “top hash” bits in each bucket and by chaining with overflow buckets.

5. Order is not guaranteed
   Though the text says the map is an “unordered collection,” it’s sometimes worth emphasizing that the iteration order of Go maps is intentionally randomized between program runs (and can even change across successive iterations in the same run, in older versions). Users should never rely on any iteration order.

---

Summary of Key Points

• Buckets are not just pointers to key/value arrays; they include inlined arrays plus overflow pointers.
• Eight slots per bucket is an implementation detail; it happens to be 8 now but isn’t guaranteed.
• Hashing is stable for a given run but depends on a random seed (so it’s not consistent across runs).
• Resizing and collision resolution details are more complex than simply “mapping a key to an index.”
• Unordered means truly no stable order between runs (and sometimes even within a run).

Here’s a high‐level (but more detailed) rundown of how Go’s runtime looks up a key in a map and finds the correct bucket:

---

1. Compute the hash of the key

When you do something like m[key], the runtime first computes a hash value for the key. For most built‐in types (strings, ints, etc.), Go uses built‐in hashing functions in the runtime. This hash is a large unsigned integer (e.g., 64 bits on many architectures).

---

2. Determine which bucket array to use (handling grow phases)

A Go map may be in the middle of growing (or shrinking). Internally, an hmap struct can have two sets of buckets:

• buckets – the new (or current) bucket array
• oldbuckets – the old bucket array (used during incremental resizing)

Go does incremental rehashing to avoid big latency spikes. If the map is currently growing, there is a field nevacuate that indicates how many of the old buckets have been “evacuated” to the new array. The logic is something like:

1. Extract the low B bits from the hash (B is the current number of bucket bits in the map). This is your bucket index.
2. If the map is in the middle of growth and the bucket index is less than nevacuate, use the old bucket array (oldbuckets). If it’s greater or equal to nevacuate, use the new bucket array (buckets).

(If the map isn’t growing, it just uses buckets.)

---

3. Compute the bucket index

Once we’ve decided which bucket array to use, the bucket index is simply:

bucketIndex = hash & (2^B - 1)

where B is the current number of bits used for indexing. This masks out the lower B bits of the hash and picks the correct bucket pointer.

---

4. Inspect the tophash array and compare keys

Each bucket in Go:

• Stores up to 8 key/value pairs “in place,” side by side
• Has a small tophash array (8 bytes) that stores the “top bits” of the hash for each of those 8 slots
• May have an overflow pointer if more than 8 pairs landed in the same bucket

The runtime then:

1. Looks at the bucket’s tophash array.
   • If the top bits in the tophash slot don’t match the top bits of our key’s hash, we skip that slot.
   • If the top bits do match, we compare the actual key in that slot for full equality.
2. If the key isn’t found in that bucket’s 8 slots, we follow any overflow pointers to additional buckets and repeat the process.

---

5. Return the value or zero value if not found

• If we find a key that matches exactly, we return the corresponding value.
• If we exhaust the bucket’s slots and all overflow buckets without a match, the key does not exist, and we return the zero value for the map’s element type (e.g. "" for string, 0 for int, etc.).

---

Summary

1. Hash the key.
2. Pick bucket array (new vs. old) if the map is growing.
3. Mask off the lower B bits of the hash to index into the bucket array.
4. Check the tophash in up to 8 slots, then any overflow buckets.
5. Compare the key for a match if the top hash bits line up.

That’s essentially how Go’s runtime finds the right bucket and looks up a value in a map.

In Go’s map implementation, the total number of buckets is always a power of two (specifically $2^B$ for some integer $B$). To select one bucket out of $2^B$, you need an integer in the range $[0, 2^B - 1]$. By doing:

$$\text{bucketIndex} = \text{hash} \;\&\; (2^B - 1),$$

you “mask out” (i.e., keep) exactly the lower $B$ bits of the hash. In binary form, $2^B - 1$ is $B$ ones (for example, if $B=3$, then $2^3 - 1 = 7$ is 0b111).

Why it’s necessary:

1. Selecting an index within the range – A power‐of‐two table of size $2^B$ means valid indices go from 0 to $2^B - 1$. The bitwise AND with $(2^B - 1)$ ensures the resulting bucket index is always in that range.

2. Fast computation – Masking lower bits is a very efficient operation on modern CPUs. It avoids more expensive modulo arithmetic when the table size is a power of two.

3. Consistent mapping – Go’s map grows by doubling (increasing $B$ by 1 at a time). Extracting the lower $B$ bits lets the runtime distribute keys evenly across buckets and split them incrementally as $B$ changes.