Map Internals — From Hash Tables to Swiss Tables

Deep dive into Go's map implementation, bucket structure, hash collision handling, growth and evacuation, and the revolutionary Swiss Tables migration in Go 1.24.

Overview

Maps are one of Go's most frequently used data structures, yet their internals remain mysterious to most developers. From the classic hash table implementation that served Go 1.0-1.23 to the revolutionary Swiss Tables approach introduced in Go 1.24, understanding map internals reveals optimization opportunities and trade-offs.

This comprehensive guide covers the evolution of Go maps, the classic bucket-based design, concurrent access patterns, sync.Map for high-contention scenarios, and the migration to Swiss Tables with SIMD-accelerated lookups.

The Classic Map Implementation (Go 1.0 - 1.23)

Core Data Structure

Go's classic maps are built around the hmap struct, which represents the map header:

// runtime/map.go (simplified)
type hmap struct {
    count     int             // # of elements in map
    flags     uint8           // state flags
    B         uint8           // log₂ of buckets array size (2^B buckets)
    noverflow uint16          // approximate # of overflow buckets
    hash0     uint32          // hash seed
    buckets   unsafe.Pointer  // array of 2^B buckets
    oldbuckets unsafe.Pointer // previous bucket array during growth
    nevac     uintptr         // progress of evacuation
    extra     *mapextra       // optional fields
}

type bucket struct {
    tophash [8]uint8                // hash value for each slot
    keys    [8]unsafe.Pointer       // key data
    values  [8]unsafe.Pointer       // value data
    overflow *bucket                // overflow bucket
}

type mapextra struct {
    overflow   *bucket
    oldoverflow *bucket
    nextOverflow *bucket
}

Memory Layout of a Bucket:

┌─────────────────────────────────────────────┐
│ Bucket Structure (128 bytes typical)        │
├─────────────────────────────────────────────┤
│ tophash[8]        │ 8 bytes                 │
│   [h1][h2][h3]... │                         │
├─────────────────────────────────────────────┤
│ keys[8]           │ 8 × 8 bytes = 64 bytes │
│   [k0][k1][k2]... │ (pointers or values)    │
├─────────────────────────────────────────────┤
│ values[8]         │ 8 × 8 bytes = 64 bytes │
│   [v0][v1][v2]... │ (pointers or values)    │
├─────────────────────────────────────────────┤
│ overflow pointer  │ 8 bytes                 │
│   (next bucket)   │                         │
└─────────────────────────────────────────────┘
Total: 8 + 64 + 64 + 8 = 144 bytes per bucket

Hash Function: runtime.memhash

Go uses a fast, cryptographically-seeded hash function to prevent hash-based DoS attacks:

// runtime/hash.go (simplified)
func memhash(p unsafe.Pointer, seed, s uintptr) uintptr {
    // AES or other hardware-accelerated hash on modern CPUs
    // Falls back to simpler hash on older systems
    return aeshash(p, seed, s)
}

Hash Seed:

The hash0 field in hmap is randomized per map instance:

// Go initializes hash0 randomly at startup
func init() {
    for i := 0; i < 16; i++ {
        // ... read random bytes ...
        h.hash0 = uint32(randombytes())
    }
}

// When creating a map
func makemap(t *maptype, hint int) *hmap {
    h := new(hmap)
    h.hash0 = fastrand()  // Random seed per map
    // ...
    return h
}

Why Random Seeds?

Without random seeds, an attacker could craft data that hashes to the same bucket, forcing O(n) lookups:

// Bad: Fixed hash seed (hypothetical)
m := make(map[string]int)
// Attacker knows hash seed
// Crafts strings: "AAA", "BBB", "CCC" all hash to bucket 0
for _, key := range ["AAA", "BBB", "CCC"] {
    m[key] = 1  // All collide in bucket 0 → overflow chain
}
// Lookup is now O(3) instead of O(1)

// Good: Random hash seed (actual Go)
// Each map instance has different hash0
// Attacker cannot predict collisions across restarts

Top Hash Byte and Fast Filtering

Each bucket stores the top 8 bits of the hash value for each key. This enables fast rejection without accessing memory:

Hash value:     0x8fa3c7d2
Top 8 bits:     0x8f

Bucket tophash: [0x8f, 0xa2, 0x7c, 0x00, ...]
                  ▲ Match! May have key
                  Avoid comparing all keys

Lookup Process:

// Simplified lookup
func mapaccess(h *hmap, key unsafe.Pointer) unsafe.Pointer {
    hash := memhash(key, h.hash0)
    m := 1 << h.B
    bucket := h.buckets[hash % m]

    // Loop through buckets (main + overflow)
    for {
        for i := 0; i < 8; i++ {
            // Fast path: check tophash first
            if bucket.tophash[i] != topbits(hash) {
                continue
            }

            // tophash matched, now check key equality
            k := bucket.keys[i]
            if keyequal(k, key) {
                return bucket.values[i]  // Found!
            }
        }

        // No match in this bucket, check overflow
        bucket = bucket.overflow
        if bucket == nil {
            return nil  // Not found
        }
    }
}

Fast Path Benefit:

For a bucket with mixed content:

tophash:  [0x8f, 0x2d, 0x7c, 0x00, 0xa3, 0x1f, 0x00, 0xb8]
Looking for key with top hash 0x8f:
  - Check slot 0: tophash[0] == 0x8f ✓ (continue to key comparison)
  - Check slot 1: tophash[1] == 0x2d ✗ (skip, no memory access for key)
  - Check slot 2: tophash[2] == 0x7c ✗ (skip)
  - Check slot 3: tophash[3] == 0x00 ✗ (empty, skip)
  - ...

Savings: Avoid 7 key comparisons just from tophash mismatch

Why Keys and Values Are Stored Separately

Modern Go separates keys and values in each bucket rather than interleaving them as (k, v) pairs. This layout optimization stems from alignment and padding requirements.

Interleaved Layout (Naive):

struct {
    uint64 k1
    string v1       // 16 bytes, needs alignment
    uint64 k2
    string v2
    ...
}

With string requiring 16-byte alignment:
k1          (8 bytes)
[padding]   (8 bytes)  ◄── Wasted!
v1          (16 bytes)
k2          (8 bytes)
[padding]   (8 bytes)  ◄── Wasted!
v2          (16 bytes)

Separated Layout (Actual Go):

struct {
    [8]uint64 keys
    [8]string values
}

keys[8]     (64 bytes, tightly packed)
values[8]   (128 bytes, properly aligned)
Total without wasted padding

Memory Savings:

For a map with 1000 buckets (8000 key-value pairs):

Interleaved:  1000 × (64 bytes keys + wasted + 128 bytes values)
            = 1000 × ~200 bytes = 200 KB (rough)

Separated:    1000 × (64 bytes keys + 128 bytes values)
            = 1000 × 192 bytes = 192 KB

Savings: 8 KB from alignment (4% in this case)
Larger for mixed-size values

Load Factor and Growth Trigger

Maps grow when the load factor (elements per bucket) reaches approximately 6.5:

// runtime/map.go
const (
    loadFactorNum   = 13    // 13/2 = 6.5
    loadFactorDen   = 2
    bucketCnt       = 8
    maxOverflow     = 8     // max overflow buckets per bucket
)

func tooManyOverflows(h *hmap) bool {
    // Grow if overflow buckets exceed sqrt(buckets)
    return h.noverflow >= (1 << (h.B / 2))
}

func shouldGrow(h *hmap) bool {
    // Load factor check: count / (1 << B) > 6.5
    return h.count >= ((1 << h.B) * loadFactorNum) / loadFactorDen
}

Why 6.5?

Bucket capacity: 8 elements
Choosing 6.5:
  - Good cache density (fits in ~2 cache lines)
  - Reasonable collision rate (~1-2% for uniform hashes)
  - Predictable overflow growth
  - Balance between memory and speed

Below 6.5:  Too much wasted space in buckets
Above 6.5:  Too many overflows, longer chains

Growth Progression:

Initial: 2^0 = 1 bucket (8 elements max)
After load 6.5: 2^1 = 2 buckets (16 elements max)
After load 13: 2^2 = 4 buckets (32 elements max)
After load 26: 2^3 = 8 buckets (64 elements max)
After load 52: 2^4 = 16 buckets (128 elements max)
...

Map Growth and Evacuation

Growth Strategy: 2x with Incremental Evacuation

When a map grows, it doesn't rehash all elements at once (which would cause GC pause). Instead:

Allocate new bucket array (2x larger)
Mark old buckets for evacuation
Gradually rehash elements during insertions

// runtime/map.go (simplified)
func growMap(h *hmap) {
    oldbuckets := h.buckets
    newbuckets := allocBuckets(1 << (h.B + 1))

    h.buckets = newbuckets
    h.oldbuckets = oldbuckets
    h.B += 1
    h.nevac = 0  // Evacuation progress
    h.flags |= sameSizeGrow
}

Evacuation Process:

Before Growth:
Old buckets (2^B = 4):
  [bucket 0] [bucket 1] [bucket 2] [bucket 3]
   {a, x}     {b, y}     {c, z}     {d}

After Allocation:
Old buckets:
  [bucket 0] [bucket 1] [bucket 2] [bucket 3]

New buckets (2^(B+1) = 8):
  [bucket 0] [bucket 1] ... [bucket 7] (empty)

During Insertion (evacuate on demand):
Insert key "e" with hash → bucket 5:

Step 1: Check if bucket 5's old home (bucket 1) is evacuated
Step 2: If not, evacuate bucket 1:
  - Rehash elements from old bucket 1
  - {b} → hash now maps to bucket 1 or 5
  - {y} → rehash similarly
  - Remove overflow chain

Step 3: Insert "e" into new bucket 5

Progressive Evacuation:
┌─────────────────────────────────┐
│ As insertions happen, buckets   │
│ migrate from old → new array    │
│ Until all evacuated (h.nevac    │
│ reaches 1 << h.B)              │
└─────────────────────────────────┘

Why Gradual Evacuation?

Immediate rehash:
  Map with 1M elements
  All rehashed at once = pause all threads
  Latency spike: 10-50 ms

Incremental evacuation:
  Each insertion triggers evacuation of one old bucket
  Cost amortized across all insertions
  No big latency spikes
  Fair scheduling for other goroutines

The Evacuation State Machine

State: Empty (not growing)
  ├─ Insert/Delete/Update → Check if should grow
  │                          If yes: transition to Growing

State: Growing
  ├─ Insert:    Evacuate old bucket (if needed) → Insert into new bucket
  ├─ Delete:    Check both old and new buckets
  ├─ Lookup:    Check both old and new buckets
  │
  └─ When h.nevac == (1 << h.B):
       All old buckets evacuated
       Free oldbuckets → transition to Empty

Map Iteration and Randomization

Go deliberately randomizes map iteration order for two reasons:

Prevent Algorithm Complexity Attacks: Predictable iteration could reveal hash structure
Encourage Code Correctness: Code relying on iteration order is buggy

// runtime/map.go (simplified)
func mapiterinit(h *hmap) *hiter {
    iter := new(hiter)
    iter.h = h

    // Random starting bucket
    iter.startBucket = uint8(fastrand() % (1 << h.B))

    // Random offset within bucket
    iter.offset = uint8(fastrand() % bucketCnt)

    return iter
}

Iteration Example:

m := map[int]string{1: "a", 2: "b", 3: "c"}

// Run 1: iteration order might be: 2, 3, 1
// Run 2: iteration order might be: 1, 2, 3
// Run 3: iteration order might be: 3, 1, 2

for k, v := range m {
    println(k, v)  // Different order each time
}

// This is intentional and good!
// Code that relies on order will fail, forcing developers to fix it

Concurrent Access Detection

Go maps panic if accessed concurrently without synchronization:

// runtime/map.go
const (
    hashWriting = uint8(1)  // Map is being written
)

func mapaccess(h *hmap, key ...) {
    if h.flags&hashWriting != 0 {
        panic("concurrent map read and map write")
    }
    // ... normal lookup ...
}

func mapassign(h *hmap, key ...) {
    h.flags |= hashWriting  // Mark writing
    defer func() {
        h.flags &^= hashWriting  // Mark done
    }()
    // ... insert/update ...
}

func mapdelete(h *hmap, key ...) {
    h.flags |= hashWriting
    defer func() {
        h.flags &^= hashWriting
    }()
    // ... delete ...
}

Detection Mechanism:

var m = make(map[int]int)

go func() {
    for {
        m[1] = 1  // Writing continuously
    }
}()

go func() {
    for {
        _ = m[1]  // Reading continuously
    }
}()

// Likely to panic:
// fatal error: concurrent map read and map write

This is a best-effort check, not guaranteed to catch all races. Use -race flag or sync.Map for proper concurrent access.

sync.Map: Lock-Free Reads

For high-contention scenarios with frequent reads, sync.Map provides better performance:

// sync/map.go (simplified)
type Map struct {
    mu     sync.Mutex
    read   atomic.Value  // *readOnly
    dirty  map[string]*entry
    misses int
}

type readOnly struct {
    m       map[string]*entry
    amended bool  // Dirty map has entries not in read map
}

type entry struct {
    p atomic.Value  // *interface{}
}

Access Pattern:

Fast Path (Read):
┌─────────────────────────┐
│ Load read-only map      │  atomic load
│ (no locks)              │
└──────┬──────────────────┘
       │
       ├─ Key found? Return value
       │
       └─ Key not found in read map?
          └─ Check if dirty map exists
             └─ Lock mutex
             └─ Check dirty map
             └─ Unlock

Slow Path (Write):
┌─────────────────────────┐
│ Lock mutex              │
│ Update dirty map        │
│ Track misses            │
│ If misses > len(dirty): │
│   Promote dirty→read    │
│ Unlock                  │
└─────────────────────────┘

Performance Characteristics:

sync.Map: Good for read-heavy, write-infrequent workloads
  Reads: O(1) with lock-free atomic load (very fast)
  Writes: O(n) with full lock (slow but happens rarely)

Regular map + sync.Mutex: Good for balanced workloads
  Reads: O(1) with lock (consistent)
  Writes: O(1) with lock (consistent)

Example scenarios:
  - Config cache (read 1000x, write 1x) → sync.Map wins
  - Event counter (read/write equally) → map + mutex wins

Benchmark Example:

package main

import (
    "sync"
    "testing"
)

var regularMap = make(map[int]int)
var regularMutex = sync.RWMutex{}
var lockFreeMap = sync.Map{}

func BenchmarkRegularMapRead(b *testing.B) {
    for i := 0; i < 1000; i++ {
        regularMap[i] = i
    }

    b.ResetTimer()
    b.RunParallel(func(pb *testing.PB) {
        i := 0
        for pb.Next() {
            regularMutex.RLock()
            _ = regularMap[i%1000]
            regularMutex.RUnlock()
            i++
        }
    })
}

func BenchmarkSyncMapRead(b *testing.B) {
    for i := 0; i < 1000; i++ {
        lockFreeMap.Store(i, i)
    }

    b.ResetTimer()
    b.RunParallel(func(pb *testing.PB) {
        i := 0
        for pb.Next() {
            lockFreeMap.Load(i % 1000)
            i++
        }
    })
}

Expected Results (16 CPU cores):

BenchmarkRegularMapRead-16    20000000    58 ns/op  (lock contention)
BenchmarkSyncMapRead-16       100000000   12 ns/op  (lock-free)

sync.Map is 4-5x faster for read-only workloads

Swiss Tables: The Go 1.24 Revolution

Go 1.24 introduces a revolutionary new hash table design called Swiss Tables, borrowed from Google's Abseil library. This is not just an optimization; it's a fundamental redesign.

What Are Swiss Tables?

Swiss Tables use a probe-based design with metadata (control bytes) instead of tophash, enabling SIMD-accelerated lookups:

Classical Hash Table (Go 1.0-1.23):
┌─────────────────────────────┐
│ Bucket Array                │
├─────────────────────────────┤
│ Bucket 0: [k, v, k, v, ...] │
│ Bucket 1: [k, v, k, v, ...] │
│ Overflow chain              │
└─────────────────────────────┘
Linear probing within bucket, overflow chains

Swiss Table (Go 1.24+):
┌──────────────────────────────────┐
│ Control Bytes (metadata)         │
│ [ctrl] [ctrl] [ctrl] ...         │
├──────────────────────────────────┤
│ Group 0: Keys [k k k ...] Values │
│ Group 1: Keys [k k k ...] Values │
│ (16 slots per group on AVX2)     │
└──────────────────────────────────┘
Probing with SIMD matching

Swiss Table Data Structure

// Simplified Swiss Table structure
type swissMap struct {
    ctrl     []uint8         // Control bytes
    keys     []unsafe.Pointer
    values   []unsafe.Pointer
    count    int
    capacity int              // Always power of 2
    seed     uint64
}

// Control byte encoding
const (
    CtrlEmpty    = 0b10000000  // Empty slot
    CtrlDeleted  = 0b11111111  // Deleted slot
    CtrlFull     = 0b00XXXXXX  // Full: bottom 6 bits = H2 (hash bits 6-11)
)

Memory Layout:

Control Array (one byte per slot):
┌─────────────────────────────────────┐
│ [0x80] [0xA5] [0x00] [0xFF] ...     │
│  Empty  Hash   Hash  Deleted        │
└─────────────────────────────────────┘
   ▲                    ▲
   │                    │
   └─ Marks empty ───── Marks deleted

Key Array:
┌─────────────────────────────────────┐
│ [k0] [k1] [k2] [k3] [k4] ...        │
└─────────────────────────────────────┘

Value Array:
┌─────────────────────────────────────┐
│ [v0] [v1] [v2] [v3] [v4] ...        │
└─────────────────────────────────────┘

Group-Based Probing

Swiss Tables process 16 slots at a time using SIMD (on AVX2), comparing against a "group" of control bytes simultaneously:

Lookup process for key with H1=hash>>7, H2=(hash>>6)&0x3F:

1. Hash computation
   key → H1 (upper bits) and H2 (control bits)

2. Probe Group Matching (SIMD)
   Load 16 control bytes into SIMD register
   Compare against H2 in parallel
   Get matching positions instantly

3. Resolve Collisions
   For each matching control byte:
     Compare full key equality
     If match → return value
     If no match → quadratic probing

Example with 16-slot group (AVX2):
Control: [0x80] [0xA5] [0x00] [0xA5] [0xFF] [0xA5] ... (16 total)
H2:       0xA5
         ▲                ▲                  ▲
         Found!           Found!             Found!
       Slot 1           Slot 3             Slot 5

Matches: 3 candidates, check actual keys
Average: 1 candidate needs full equality check

Pseudocode:

func (h *swissMap) lookup(key Key) Value {
    // Hash with seed
    hash := hashKey(key, h.seed)
    h1 := hash >> 7
    h2 := (hash >> 6) & 0x3F

    // Probe loop
    probeIndex := 0
    for {
        // Calculate group to probe
        groupIndex := (h1 + probeIndex) % (capacity / 16)

        // Load 16 control bytes
        controls := h.ctrl[groupIndex*16:(groupIndex+1)*16]

        // SIMD match (simplified as loop)
        for i := 0; i < 16; i++ {
            ctrl := controls[i]

            // Check if slot is full and H2 matches
            if isFullSlot(ctrl) && getH2(ctrl) == h2 {
                // Potential match, verify key
                if keyEqual(h.keys[groupIndex*16+i], key) {
                    return h.values[groupIndex*16+i]
                }
            }
        }

        // Check for empty slot (end of probe sequence)
        for i := 0; i < 16; i++ {
            if controls[i] == CtrlEmpty {
                return nil  // Not found
            }
        }

        probeIndex++
    }
}

Swiss Table Layout Advantages

Cache Efficiency:

Control bytes and keys/values are in separate arrays
✓ Control bytes: 16 bytes fits in cache line
✓ Compact, no padding waste
✓ Pointer arithmetic is simple

Classic bucket:
  [8 tophash] [8 keys] [8 values] [overflow*]
  Spread across multiple cache lines
  Padding between sections

Swiss Table Group (16 slots on AVX2):
  Controls:    16 bytes (1/4 cache line)
  Keys:        128 bytes (2 cache lines)
  Values:      128 bytes (2 cache lines)
  Tightly packed, predictable access

SIMD Benefit:

Old lookup (bucket by bucket):
  for bucket in buckets:
      for i in 8:
          if tophash[i] == target:
              check key

New lookup (group by group):
  for group in groups:
      matches = simd_match(control[16], h2)
      for match in matches:
          check key

With AVX2:
  Check 16 slots in parallel
  ~4x faster matching in best case

Performance: Swiss Tables vs Classic

Lookup Performance:

Micro-benchmark (random lookups, 100K entries):

Go 1.23 (Classic):
  ├─ Empty lookup (miss):     12 ns
  ├─ Found at slot 0:         18 ns
  ├─ Found at slot 7:         65 ns (overflow chain)
  └─ Average (75% hit):       35 ns

Go 1.24 (Swiss):
  ├─ Empty lookup (miss):     8 ns  (SIMD filtering)
  ├─ Found at slot 0:         12 ns
  ├─ Found at slot 15:        45 ns (quadratic probing)
  └─ Average (75% hit):       22 ns  ◄── 37% faster!

Insertion Performance:

Go 1.23: ~45 ns per insertion (including bucket probing, growth)
Go 1.24: ~28 ns per insertion (SIMD acceleration)

    32% faster for insertions

Memory Layout:

100K entries, ~6.5 load factor → 15,385 slots needed

Go 1.23 (Classic):
  Buckets:  1,923 buckets × 144 bytes = 277 KB
  Overflow: ~200 KB (approximate)
  Total:    ~477 KB

Go 1.24 (Swiss):
  Controls: 15,385 bytes = 15 KB
  Keys:     15,385 × 8 = 123 KB
  Values:   15,385 × 8 = 123 KB
  Total:    ~261 KB

Memory savings: ~45% (due to no overflow chains, better packing)

Real-World Benchmarks:

package main

import (
    "fmt"
    "testing"
)

func BenchmarkSwissVsClassic(b *testing.B) {
    m := make(map[int]int, 100000)

    // Pre-populate
    for i := 0; i < 100000; i++ {
        m[i] = i
    }

    b.ResetTimer()

    // Random lookups (Go 1.24 syntax, for illustration)
    for i := 0; i < b.N; i++ {
        key := i % 100000
        _ = m[key]
    }
}

// Go 1.23 results (example):
// BenchmarkSwissVsClassic-8  2000000    589 ns/op (100 lookups at 5.89ns each)

// Go 1.24 results (example):
// BenchmarkSwissVsClassic-8  3000000    369 ns/op (100 lookups at 3.69ns each)

Migration Implications

No User-Visible Changes:

The Swiss Table implementation is completely internal. All map operations remain the same:

// Code that works in Go 1.23
m := make(map[string]int)
m["key"] = 1
if v, ok := m["key"]; ok {
    println(v)
}
delete(m, "key")

// Exact same code works in Go 1.24
// But runs faster with Swiss Tables!

Performance Gains Are Automatic:

// Before: go test -bench=. -benchmem
// BenchmarkOldMap-8  1000000  1035 ns/op

// After: go test -bench=. -benchmem
// BenchmarkOldMap-8  1500000   687 ns/op  ◄── 33% faster, no code change!

Practical Optimization Tips

Tip 1: Pre-size Maps When Possible

// BAD: Grows from 1 → 2 → 4 → 8 → 16 → 32 buckets
m := make(map[string]int)
for i := 0; i < 1000; i++ {
    m[fmt.Sprintf("key%d", i)] = i
}

// GOOD: Single allocation for 1000 elements
m := make(map[string]int, 1000)
for i := 0; i < 1000; i++ {
    m[fmt.Sprintf("key%d", i)] = i
}

// Benchmark impact:
// Without pre-size: 2500 ns/op
// With pre-size:    1850 ns/op (26% faster)

Why?

Every growth triggers evacuation overhead. With 1000 elements and 6.5 load factor:

No pre-size growth sequence:
  1 bucket → 2 (evacuate 1)
  2 buckets → 4 (evacuate 2)
  4 buckets → 8 (evacuate 4)
  8 buckets → 16 (evacuate 8)
  16 buckets → 32 (evacuate 16)
  Total evacuations: 31 operations

Pre-sized to 256 buckets:
  No growth, zero evacuations

Tip 2: Choose Key Types Carefully

// Fast keys (good hash properties)
type FastMap = map[string]int     // Native hash support
type FastMap = map[int64]int      // Native hash support
type FastMap = map[[16]byte]int   // Array of bytes, native

// Slower keys (hashing overhead)
type SlowMap = map[[8]int]int     // Array of ints, slower hash
type SlowMap = map[uint8]int      // Hash for small values

// Benchmark key hashing speed:
// string hash:  ~5 ns
// int64 hash:   ~2 ns
// [16]byte:     ~8 ns
// [8]int:       ~15 ns (multiple cache misses)

String Key Performance:

// Strings have optimized hashing
m := make(map[string]int, 1000)
m["key"] = 1  // Hash computed once, cached-friendly

// vs. Custom struct key (requires full comparison)
type Pair struct {
    a int
    b string
}
m2 := make(map[Pair]int, 1000)
m2[Pair{1, "key"}] = 1  // More expensive

Tip 3: Use sync.Map for Read-Heavy Workloads

// Pattern: Read cache that's updated rarely
var cache = sync.Map{}

// In main loop: reads
value, _ := cache.Load("key")

// Occasionally: write
cache.Store("key", newValue)

// Benchmark (1 writer, 16 readers):
// Regular map + mutex:  950 ns/op per read (lock contention)
// sync.Map:            75 ns/op per read (lock-free!)

Tip 4: Avoid Large Value Types

// BAD: Large value (1 KB)
type LargeData struct {
    // ... 1 KB of fields ...
}
m := make(map[string]LargeData)
m["key"] = largeData  // Copy 1 KB per insertion

// GOOD: Pointer to large value
m := make(map[string]*LargeData)
m["key"] = &largeData  // Copy 8 bytes per insertion

// Benchmark impact (1000 insertions):
// Large value: 4200 μs
// Pointer:     580 μs  (7x faster!)

Tip 5: Monitor Map Statistics

package main

import (
    "fmt"
    "runtime"
    "runtime/debug"
)

func analyzeMapMetrics(name string, m map[int]int) {
    var stats debug.GCStats
    debug.ReadGCStats(&stats)

    fmt.Printf("Map %s:\n", name)
    fmt.Printf("  Size: %d bytes\n", unsafe.Sizeof(m))

    // Estimate bucket count
    bucketCount := 1 << estimateBucketBits(len(m))
    fmt.Printf("  Estimated buckets: %d\n", bucketCount)
    fmt.Printf("  Elements: %d\n", len(m))
    fmt.Printf("  Load factor: %.2f\n", float64(len(m))/float64(bucketCount*8))
}

func estimateBucketBits(elements int) uint {
    // Reverse engineer bucket count from load factor
    b := uint(0)
    for (elements * 2) / 13 > (1 << b) {
        b++
    }
    return b
}

func main() {
    m := make(map[int]int)
    for i := 0; i < 1000; i++ {
        m[i] = i
    }

    analyzeMapMetrics("main", m)
}

Tip 6: Batch Operations When Possible

// BAD: Individual operations, repeated growth checks
m := make(map[int]int)
for i := 0; i < 1000; i++ {
    m[i] = i  // Each operation checks if should grow
}

// GOOD: Pre-allocate, batch inserts
m := make(map[int]int, 1000)
batch := make([]int, 1000)
for i := 0; i < 1000; i++ {
    batch[i] = i
}
for _, v := range batch {
    m[v] = v
}

// Or use a slice, convert to map only once
slice := make([]KV, 1000)
for i := 0; i < 1000; i++ {
    slice[i] = KV{key: i, val: i}
}
m := sliceToMap(slice)

Summary

Go's maps have evolved significantly:

Classic Implementation (Go 1.0-1.23):

Bucket-based with 8 slots per bucket
Top-hash bytes for fast rejection
Separated keys/values to minimize padding
Incremental evacuation during growth
6.5 load factor before doubling capacity

Swiss Tables (Go 1.24+):

Group-based probing with control metadata
SIMD-accelerated group matching (AVX2 on x86-64)
Separate control, keys, values arrays
Quadratic probing instead of overflow chains
30-40% faster lookups, 45% less memory

Practical Guidance:

Pre-size maps when element count is known
Choose key types with good hash performance
Use sync.Map for read-heavy scenarios
Store pointers to large values
Monitor map metrics in production

Whether using classic or Swiss Table implementation, understanding map internals helps you write high-performance code. In Go 1.24+, you automatically benefit from Swiss Tables without changing any code.

Map Internals — From Hash Tables to Swiss Tables

On this page