A bucket is a fixed-size group of key-value entries inside a Go map’s hash table. Each bucket holds eight elements. Map operations hash a key to an array index, then search the selected bucket for that key. section 3.11.1
When several keys hash to the same index, they occupy the same bucket. If that bucket becomes full, Go allocates another eight-element bucket and links it to the previous one as overflow. section 3.11.1
Why deleting entries does not release bucket storage
A map containing one million entries can grow to 262,144 buckets. Deleting every entry zeroes the bucket slots, but the bucket count remains unchanged; garbage collection can collect the entries without shrinking the map or removing its extra buckets. Consequently, the heap may fall from 461 MB to 293 MB rather than returning to its initial size. section 3.12
Keep these bucket behaviors in mind when diagnosing map behavior:
- Treat deletion as removal of entries, not reversal of map growth; a map can gain buckets but cannot shrink them. section 3.12
- Do not mistake assigning a map to a new variable for copying its buckets; both map values can reference the same underlying data. section 9.10
- Protect concurrent iteration and mutation with the mutex, or make an actual copy while locked before iterating outside the critical section. section 9.10
Figure 3.17 In case of a bucket overflow, Go allocates a new bucket and links the previous bucket to it.
Visualizes a full bucket creating and linking an eight-element overflow bucket. section 3.11.1
