Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Concurrency and Context

Go sync.Map type

Reference for Go sync.Map: Load, Store, LoadOrStore, LoadAndDelete, Swap, CompareAndSwap, Range and Clear, when it beats a mutex-guarded map, and its pitfalls.

sync.Map is a map that many goroutines can read and write at the same time without any extra locking. Its zero value is ready to use, and it must not be copied after first use. Keys and values are stored as any, so you lose compile-time type checking and have to use type assertions when you read.

A plain map guarded by a sync.Mutex or RWMutex is the right default. sync.Map is tuned for two narrow patterns: keys written once and read many times (caches that only grow), and goroutines that work on disjoint sets of keys.

Go
var m sync.Map
m.Store("answer", 42)
v, ok := m.Load("answer")

Try it

Go Store, Load and LoadOrStore

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Many goroutines, one map

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
type Map struct { /* unexported */ }

func (m *Map) Load(key any) (value any, ok bool)
func (m *Map) Store(key, value any)
func (m *Map) LoadOrStore(key, value any) (actual any, loaded bool)
func (m *Map) LoadAndDelete(key any) (value any, loaded bool)
func (m *Map) Delete(key any)
func (m *Map) Swap(key, value any) (previous any, loaded bool)
func (m *Map) CompareAndSwap(key, old, new any) (swapped bool)
func (m *Map) CompareAndDelete(key, old any) (deleted bool)
func (m *Map) Range(f func(key, value any) bool)
func (m *Map) Clear()
Method Description
Load Returns the value for a key and whether it was present.
Store Sets the value for a key.
LoadOrStore Returns the existing value if there is one (loaded is true); otherwise stores and returns the given value.
LoadAndDelete Removes the key and returns the value it had.
Delete Removes the key; does nothing if absent.
Swap Stores a new value and returns the previous one (added in Go 1.20).
CompareAndSwap, CompareAndDelete Change or remove the entry only if its current value equals old (Go 1.20).
Range Calls f for each entry until f returns false.
Clear Removes all entries (Go 1.23).

Errors and panics. Keys must be comparable; using a slice or map as a key panics at run time. CompareAndSwap and CompareAndDelete also panic if the stored value is not comparable.

Usage notes

  • No generics. Every read gives you any; assert the type yourself (v.(int)). For typed access, wrap the map in a small struct with typed methods.
  • Range is not a snapshot. It sees each key at most once but may or may not see entries added or removed while it runs. The iteration order is unspecified, so sort keys when you need stable output.
  • It is not a drop-in replacement for map plus mutex. Operations that need to touch several keys atomically, or that need len, are awkward. There is no Len method; you count with Range.
  • LoadOrStore may run the "compute" step twice. If you compute an expensive value before calling it, several goroutines can each compute one and only one wins. Store a lazily initialized object (for example one wrapped in sync.Once) when the work must happen once.
  • Never copy a sync.Map after use; go vet reports it.
  • Performance: it shines for read-mostly or disjoint-key workloads. With frequent writes to the same keys, a mutex-guarded map is often faster and always simpler to reason about.