Deep Dive into Go's sync.Map: Implementation, Usage, and Performance

Go’s sync.Map provides a thread‑safe map for concurrent workloads, offering the usual Store , Load , Delete , and Range operations plus several composite methods.

The implementation uses two layers: a read‑only map ( read ) that can be accessed without locking, and a mutable dirty map protected by a mutex. Each key is stored in an entry object whose value can be nil (logically deleted), expunged (physically deleted), or a normal pointer.

Store forwards to Swap , which atomically replaces the value for a key. The core of Swap is:

func (m *Map) Swap(key, value any) (previous any, loaded bool) { /* ... */ }

It first tries to update the value in the read map; if the key is missing it acquires the lock, updates the dirty map, and may promote dirty to read after enough misses.

Load reads from the read map without locking. If the key is absent and the map is marked amended , it falls back to the dirty map under a lock, increments the miss counter, and may promote the dirty map to read when misses reach the dirty map size.

func (m *Map) Load(key any) (value any, ok bool) { /* ... */ }

Delete simply calls LoadAndDelete , which removes the key from the dirty map (or marks it as nil in the entry) and records a miss.

func (m *Map) Delete(key any) { m.LoadAndDelete(key) }

Range iterates over the current read map. If the map is amended, it locks, promotes dirty to read, clears the dirty map, and then walks the entries, invoking the user‑provided function for each key/value pair.

func (m *Map) Range(f func(key, value any) bool) { /* ... */ }

Clear empties both read and dirty maps, resetting the miss counter.

func (m *Map) Clear() { /* ... */ }

The composite methods LoadOrStore , CompareAndSwap , and CompareAndDelete combine lookup and mutation in a single atomic step, using the same read‑first, lock‑fallback pattern.

Overall, sync.Map trades extra memory for lock‑free reads, but operations that promote the dirty map (e.g., many misses, Range , or Clear ) can cause performance degradation, so profiling is recommended for critical paths.