When is swapping a whole map through atomic.Pointer[T] better than guarding it with a mutex?

## The pattern Copy-on-write publication splits a shared structure into an immutable value plus one atomically-swapped pointer to it. ```go type Index struct { write sync.Mutex // writers only m atomic.Pointer[map[string]Session] } ``` A reader does exactly one atomic load and then reads an ordinary Go map: ```go sess, ok := (*ix.m.Load())[id] ``` No lock is taken, no cache line is written, and readers never interfere with each other or with the writer. A writer takes the writers-only mutex (so two writers do not both copy from the same old state and lose one update), allocates a new map, copies the old entries in, applies its change, and stores the new pointer. From that instant, new readers see the new map; readers already holding the old pointer keep reading the old map, which is still perfectly valid memory and is collected once the last reader drops it. ## Why this removes contention rather than just moving it A mutex-guarded read still **writes** — it mutates the lock word, which bounces that cache line between cores. That is why a read-heavy structure guarded by a lock can flatten out as cores are added even though nothing is being modified. An atomic pointer load is a plain read of a word; many cores can hold that line shared and read it in parallel indefinitely. The contention does not move somewhere else, it stops existing on the read path. ## The rules you cannot break **1. Published state is immutable.** Once `Store` has been called, the map that was stored may never be written to again, by anyone. A writer that does `m := ix.m.Load(); (*m)[id] = sess` has just written to a map that readers are reading concurrently — a data race, and with Go maps a possible fatal "concurrent map read and map write" crash rather than a merely wrong answer. Every change allocates a new map. **2. One `Load` per logical read.** If a caller needs two entries that must be consistent with each other, it must load the pointer once and index the resulting map twice. Two separate `Load` calls can land on either side of a swap and produce a pair that never existed together. **3. No read-modify-write.** "Look up the entry, increment its counter, store it back" is not made safe by the atomic pointer. Anything of that shape belongs under the writers' mutex, or in a different structure. **4. Writers still need their own mutex.** `atomic.Pointer` gives you an atomic swap of one word; it does not stop two writers from both copying the same old map and one of them clobbering the other's change. Serialise them. ## The cost model Read cost: one atomic load, then normal map access. Effectively free, and it stays flat as cores are added. Write cost: allocating a map of n entries and copying n key/value pairs, every single time. With a thousand entries and a write every few seconds, nobody notices. With a hundred thousand entries and a write every hundred milliseconds, you have built an allocation machine that will show up as GC pressure long before it shows up as lock contention. The break-even is a ratio question, and it is worth measuring with a benchmark that models the real read/write mix rather than guessing. Staleness: a reader that loaded before the swap continues on the old snapshot for as long as it holds it. For a session index, feature flags, a routing table or a set of verification keys, that window is fine and often desirable — the reader sees one coherent version of the world. For anything where a write must be visible to the very next read, it is wrong. Memory: two copies exist during the swap, and the old one lives until the last reader releases it. Long-lived readers holding old snapshots keep old maps alive. ## When to choose it over partitioning Sharding the lock helps when writes are spread across many keys and every operation is per-key. Copy-on-write publication helps when writes are *rare* regardless of key, and reads are everywhere. They solve different shapes: if your write rate is high, sharding; if your read rate is high and writes are occasional bulk republications, the atomic swap. A structure that is rebuilt wholesale on a schedule — reload a config file, refresh a routing table every thirty seconds — is the ideal fit, because the copy you were going to make anyway *is* the new snapshot. ## Practical shape Initialise the pointer at construction so `Load` never returns nil; a nil dereference on the read path is the classic bug here. Consider storing a small struct rather than a bare map when you need several fields to change together — one `Store` then publishes all of them consistently, which is exactly the kind of multi-field invariant a single atomic word cannot otherwise give you. And keep the writer's copy loop boring: `make` with the right capacity hint, a `for k, v := range old` copy, then the change, then `Store`.