Your team swapped a map behind a sync.RWMutex for a sync.Map and throughput dropped. Why?

## The assumption behind the regression The swap usually comes from a reasonable-sounding chain: the map is shared, the shared map has a lock, locks are contention, `sync.Map` is the lock-free one, therefore `sync.Map` is faster. Every step is plausible and the conclusion is wrong, because `sync.Map` is a *specialised* container whose advantage is conditional, not a drop-in optimisation. ## Cost one: the API is untyped `sync.Map`'s methods take and return `any`. That has concrete runtime consequences that a typed map does not pay: - **Boxing.** Storing a value that is not already pointer-shaped means putting it in an interface, which generally allocates. A `map[int]int` stores eight bytes inline; `sync.Map` with the same data allocates behind each key and each value. - **Indirection.** Every load returns an interface that must be type-asserted, and the real value lives one pointer hop away, which is worse for cache locality than a compact typed map's contiguous storage. - **Garbage.** Those per-operation allocations become garbage-collector work, which shows up as CPU time far away from the map code and is easy to misattribute. This cost is paid on *every* operation, whatever the concurrency, and it is why a `sync.Map` version of a benchmark often shows more allocations per operation than the locked map even when the two do the same logical work. ## Cost two: the fast path is conditional The reason `sync.Map` can serve reads without taking a lock is that it maintains extra internal structure so that stable entries can be read cheaply, at the cost of bookkeeping when entries are added or changed. The published guidance names two workloads where that trade pays: 1. **Write once, read many** — a cache that only grows, where entries settle and are then read repeatedly. 2. **Disjoint key sets** — several goroutines each working on their own keys, so they rarely touch the same entries. A registry of long-lived client connections, written once when a client arrives and read on every subsequent request, fits the first shape well. A per-request scratch map, a hot counter table where every goroutine updates the same handful of keys, or a workload with a steady stream of brand-new keys fits neither: nothing settles, so you pay the bookkeeping continuously while the reads never get to be cheap. ## Cost three: the lock you removed may have been free An uncontended mutex acquisition is a couple of atomic instructions — tens of nanoseconds, no system call, no goroutine parking. If your critical section is a single map lookup and only a handful of goroutines ever collide, there was almost no contention to eliminate. You removed something nearly free and added boxing to every operation. Contention only becomes the dominant cost when many goroutines hit the same lock at once, or when the critical section is long — and the first fix for a long critical section is to make it shorter, not to change container. ## Measuring it properly ```go func BenchmarkRegistryParallel(b *testing.B) { b.ReportAllocs() b.RunParallel(func(pb *testing.PB) { for pb.Next() { // one op of your real read/write mix } }) } ``` Run it with `go test -bench=. -benchmem` and read three numbers for each implementation: ns/op, B/op and allocs/op. The details that decide whether the benchmark means anything: - **Model the real mix.** A 99%-read benchmark and a 50%-write benchmark will rank the two implementations differently. Use the ratio your service actually has. - **Model the key distribution.** Ever-growing distinct keys, a fixed hot set and a long tail behave completely differently. A uniform random key over a huge space flatters `sync.Map`'s disjoint-keys case in a way production may not. - **Use realistic parallelism.** `b.RunParallel` scales with `GOMAXPROCS`; a result at one core says nothing about a container with eight. - **Confirm the lock was the problem first.** Before changing anything, enable the mutex profile with `runtime.SetMutexProfileFraction` and look at a CPU profile. If lock waiting is not a visible share of the profile, no container swap will show up in latency, and you have spent a change budget on noise. ## The judgment to state out loud The default is a plain typed map with a lock, wrapped in a struct whose methods own the locking — it keeps types, keeps `len`, allocates less, and every reader understands it. Move to `sync.Map` when a measurement shows lock contention *and* the access pattern matches one of the two it targets. "We changed it because it sounded faster" is the answer that costs the interview; "we benchmarked both under our real mix and kept the one that won" is the one that passes. And the same discipline applies to reverting: if the profile says the swap did not help, put it back.