Go Reference ยท Concurrency and Context
The Go sync/atomic package
Overview of Go's sync/atomic package: typed atomics (Int64, Bool, Pointer, Value), Add, Load, Store, Swap, CompareAndSwap, And/Or, and when to use them over a mutex.
The sync/atomic package provides low-level operations that read or modify a single memory word indivisibly, so several goroutines can touch it without a lock and without a data race. It is the tool for counters, flags, and for publishing an immutable snapshot of some data.
Since Go 1.19 the preferred API is the set of typed values: atomic.Int32, Int64, Uint32, Uint64, Uintptr, Bool, Pointer[T] and Value. They carry their own alignment guarantees and cannot be accidentally read non-atomically. The older function style (atomic.AddInt64(&x, 1)) still works.
var hits atomic.Int64 hits.Add(1) fmt.Println(hits.Load())
Try it
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.
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
type Int64 struct { /* ... */ } func (x *Int64) Load() int64 func (x *Int64) Store(val int64) func (x *Int64) Add(delta int64) (new int64) func (x *Int64) Swap(new int64) (old int64) func (x *Int64) CompareAndSwap(old, new int64) (swapped bool) func (x *Int64) And(mask int64) (old int64) // Go 1.23 func (x *Int64) Or(mask int64) (old int64) // Go 1.23 type Pointer[T any] struct { /* ... */ } func (x *Pointer[T]) Load() *T func (x *Pointer[T]) Store(val *T) func (x *Pointer[T]) Swap(new *T) (old *T) func (x *Pointer[T]) CompareAndSwap(old, new *T) (swapped bool)
| Type | Description |
|---|---|
Int32, Int64, Uint32, Uint64, Uintptr |
Integer atomics with Load, Store, Add, Swap, CompareAndSwap, And, Or. |
Bool |
Load, Store, Swap, CompareAndSwap. |
Pointer[T] |
Atomic pointer to a T; no Add. |
Value |
Holds any value of one consistent concrete type; adds Load, Store, Swap, CompareAndSwap. |
Panics and edge cases. Value.Store(nil) panics, and storing a value of a different concrete type than the first one panics. A zero Value returns nil from Load. Decrement with Add(-1); for unsigned types use Add(^uint64(0)).
Usage notes
- One word at a time. An atomic makes a single operation indivisible. It does not make a sequence like "read, decide, then write another variable" safe. Use a mutex when several fields must change together.
- Memory ordering. Go's atomics are sequentially consistent: an atomic store is visible to every goroutine that later loads the same value, and the writes before it are visible too. That is what makes the snapshot pattern work.
- Snapshot pattern. Build a new immutable struct, then
Storeits pointer. ReadersLoadonce and use the result freely. Never mutate the struct after publishing it. - Don't mix atomic and plain access to the same variable; the plain access is still a data race (
go run -racewill flag it). - Do not copy a typed atomic after first use;
go vetwarns. Struct fields of atomic types are best placed so the struct is not copied. - Alignment: the typed
Int64/Uint64are safe on 32-bit platforms, unlike rawint64fields passed to the function API. - Cost: much cheaper than a mutex when uncontended, but heavily contended atomics still bounce cache lines between cores.