Skip to content
Tutorials Center
My learning

Topics

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.

Go
var hits atomic.Int64
hits.Add(1)
fmt.Println(hits.Load())

Try it

Go A lock-free counter and flag

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 Publishing a snapshot with Pointer and Value

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 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 Store its pointer. Readers Load once 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 -race will flag it).
  • Do not copy a typed atomic after first use; go vet warns. Struct fields of atomic types are best placed so the struct is not copied.
  • Alignment: the typed Int64/Uint64 are safe on 32-bit platforms, unlike raw int64 fields passed to the function API.
  • Cost: much cheaper than a mutex when uncontended, but heavily contended atomics still bounce cache lines between cores.