Acquire / Release — Senior Level¶

Table of Contents¶

1. Introduction
2. The Go Memory Model — Formal View
3. Happens-Before Axioms
4. Double-Checked Locking
5. Seqlocks
6. Lock-Free Queues and Stacks
7. RCU in Depth
8. Hazard Pointers vs Go's GC
9. The Cost of Sequential Consistency
10. Designing a Concurrent Library
11. Memory Reclamation Patterns
12. Wait-Free vs Lock-Free vs Obstruction-Free
13. Cache-Line and False Sharing
14. Verifying Concurrent Code
15. When to Drop to Assembly
16. Common Senior-Level Mistakes
17. Cheat Sheet
18. Summary
19. Further Reading

Introduction¶

The middle level taught you how to apply acquire/release. The senior level teaches you how to reason about it precisely. The difference is that you now design library primitives, not just consume them. You write code that other engineers will run at millions of ops/sec, and your bugs become their bugs at a scale where reproduction is statistical.

We will do three things in this file:

1. Make happens-before formal. Stop saying "the runtime guarantees..." and start citing specific axioms from the Go memory model.
2. Build hard publication patterns. Double-checked locking. Seqlocks. Lock-free queues. RCU with proper reclamation.
3. Reason about the costs. Why sequential consistency is more expensive on ARM. Why false sharing kills you. Why hazard pointers exist (and why Go barely needs them).

By the end you should be able to read a paper from the parallel-programming literature, identify the primitives it uses, and translate them into Go.

The Go Memory Model — Formal View¶

The Go memory model, as of the 2022 revision, is built on three relations:

1. Sequenced-before — total order within a goroutine, defined by source code order.
2. Synchronizes-with — edges between goroutines, established by synchronization operations.
3. Happens-before — the transitive closure of (1) and (2).

A read R of a non-atomic variable v is allowed to observe a write W if:

• R does not happen-before W, and
• there is no other write W' on v such that W happens-before W' happens-before R.

Two accesses race if they both access the same memory location, at least one is a write, and there is no happens-before relation between them.

A program with a data race has undefined behavior. The compiler is free to assume races don't happen — meaning your "lucky" race may suddenly stop working when you upgrade Go.

Sequenced-before in detail¶

Within a single goroutine, the source code order is preserved up to compiler reorderings. The compiler may reorder if and only if the reordering is invisible to the goroutine itself.

• Two reads of the same location: reordering is visible (the second might see a different value); not allowed.
• A read followed by an independent write: reordering may or may not be visible; compiler decides.
• A write followed by an independent read: reordering may or may not be visible; compiler decides.
• Two writes to the same location: reordering is invisible to the goroutine (only the last value matters); allowed.
• A write of an atomic followed by a non-atomic write: the atomic acts as a release barrier; the non-atomic write must remain after.
• A non-atomic write followed by an atomic write: the atomic acts as a release barrier; the non-atomic write must remain before.

The atomic operations are the only compiler-visible barriers in pure Go. Without them, the compiler may reorder more aggressively than you expect.

Synchronizes-with in detail¶

The Go memory model lists synchronization edges explicitly:

1. The go statement. The go f() call synchronizes-with the first instruction of f. In other words, all writes made by the parent goroutine before go f() are visible to f.

2. The goroutine exit. A goroutine's last action synchronizes-with the corresponding call to Wait on a sync.WaitGroup whose counter reached zero. (More precisely: the Done call synchronizes-with Wait.)

3. Channel send/receive. A send on a channel synchronizes-with the completion of the corresponding receive. For unbuffered channels, the send and receive synchronize together; the send happens-before the receive returns.

4. Channel close. A close(ch) call synchronizes-with the completion of every receive that observed the close.

5. Mutex Lock/Unlock. The n-th call to Unlock synchronizes-with the (n+1)-th call to Lock.

6. sync.Once.Do. The first call to Do(f) that runs f synchronizes-with the return of every other call to Do.

7. Atomic operations. The Go atomics provide sequential consistency: there is a single global total order of all atomic operations that is consistent with each goroutine's program order.

Happens-before as a partial order¶

The happens-before relation is:

• Reflexive: every event happens-before itself.
• Antisymmetric: if A hb B and B hb A then A = B.
• Transitive: if A hb B and B hb C then A hb C.

It is not total — many pairs of events are unordered. This is fine, as long as unordered pairs don't both access the same memory.

The cardinal rule¶

A read of a memory location is allowed to see a particular write if that write happens-before the read, and no intervening write also happens-before the read.

If multiple writes are unordered relative to the read, the read may see any of them — including no write at all (if there's also a write that doesn't happen-before the read).

In practice: if you publish v through a release, and you consume v through an acquire, you see v. If you mix in unsynchronized writes to v, you have a race and could see anything.

Happens-Before Axioms¶

Let's make the synchronization edges concrete with axioms.

Axiom 1: Initialization¶

The completion of init functions in a package happens-before the start of main. The start of main happens-before the start of any goroutine spawned from main.

Axiom 2: Goroutine creation¶

The execution of go f() happens-before the first action of f.

This is why this code is safe:

x := 5
go func() { fmt.Println(x) }() // sees x = 5

The write x = 5 is sequenced-before go f(), which happens-before the closure's first action.

Axiom 3: Channel send-receive on buffered channels¶

The k-th send on a channel happens-before the k-th receive completes. The receive of the k-th value from an empty unbuffered channel happens-before the k-th send completes (because the send blocks until the receive is ready).

ch := make(chan int, 1)
x := 5
ch <- 1            // synchronizes-with...
<-ch               // ...this receive

// Now x = 5 is visible to the receiver.

Axiom 4: Channel close¶

A call to close(ch) happens-before a receive that returns the zero value because the channel is closed.

done := make(chan struct{})
go func() {
    expensiveSetup()
    close(done)
}()

<-done // observes the close
// expensiveSetup's writes are now visible

Axiom 5: Mutex¶

For any given mutex m, the n-th call to m.Unlock() happens-before the (n+1)-th call to m.Lock() returns. (The lock order is determined by the runtime's actual lock acquisition sequence.)

mu.Lock()
x = 5
mu.Unlock()

// some other goroutine:
mu.Lock()
fmt.Println(x) // sees 5
mu.Unlock()

For RWMutex, every RUnlock happens-before the next Lock returns. The relationship between concurrent RLock calls is unspecified — they don't synchronize with each other.

Axiom 6: sync.Once¶

The completion of the function inside the first Do(f) call happens-before the return of every Do call.

var once sync.Once
var v *Service

once.Do(func() { v = newService() })
// Anyone else doing once.Do(...) and then reading v sees the same *Service.

Axiom 7: Atomic operations¶

There is a single total order of all atomic operations on all locations. Each goroutine's atomic operations appear in this order in their program order.

Concretely: if goroutine A does a.Store(1); b.Store(2), then every observer that sees b.Load() == 2 also (if they later load a) sees a.Load() ≥ 1. The "≥" is because some other goroutine may have stored a larger value in between.

Axiom 8: Finalizers¶

The call to runtime.SetFinalizer on an object happens-before the finalizer runs.

Mostly irrelevant for application code; matters when implementing cleanup.

Double-Checked Locking¶

Double-checked locking (DCL) is the canonical optimization for lazy init under contention. The naive version is broken in many languages; the careful version is correct in Go.

Naive (broken) version¶

type Holder struct {
    once int32
    val  *Big
    mu   sync.Mutex
}

func (h *Holder) Get() *Big {
    if atomic.LoadInt32(&h.once) == 1 {
        return h.val // RACE: h.val read non-atomically
    }
    h.mu.Lock()
    defer h.mu.Unlock()
    if h.once == 0 {
        h.val = newBig()
        atomic.StoreInt32(&h.once, 1)
    }
    return h.val
}

The bug: the fast-path read of h.val is non-atomic. Even though h.once is atomic and synchronizes with the writer's atomic.StoreInt32, the reader's h.val read may not see the writer's h.val = newBig() if the compiler hoists the read before the once-check.

Wait — does Go's memory model permit this? Let's think.

The writer does: 1. h.val = newBig() (non-atomic write) 2. atomic.StoreInt32(&h.once, 1) (atomic store; release)

The reader does: 1. atomic.LoadInt32(&h.once) == 1 (atomic load; acquire) 2. return h.val (non-atomic read)

If step 1 of the reader observed 1, then it synchronizes-with step 2 of the writer. By transitivity, step 1 of the writer (h.val = newBig()) happens-before step 2 of the reader (return h.val). So the read sees newBig().

Is this code actually correct in Go? Let's check the memory model definition: it says the read is allowed to see the write because the write happens-before the read, and no intervening write modifies h.val. Looks correct.

But wait — the race detector may flag the read of h.val. Why? Because Go's memory model also requires that data races be absent in well-formed programs. A non-atomic read concurrent with a non-atomic write is a race, even if the read can be proven to never observe the write in this run.

The Go 2022 memory model is explicit about this: "Programs that modify data being simultaneously accessed by multiple goroutines must serialize such access." Reads and writes of h.val must be synchronized.

So the careful version uses atomic.Pointer:

type Holder struct {
    val atomic.Pointer[Big]
    mu  sync.Mutex
}

func (h *Holder) Get() *Big {
    if v := h.val.Load(); v != nil {
        return v
    }
    h.mu.Lock()
    defer h.mu.Unlock()
    if v := h.val.Load(); v != nil {
        return v
    }
    v := newBig()
    h.val.Store(v)
    return v
}

Now both reads and writes of h.val are atomic. The fast path is h.val.Load() — one atomic. The slow path takes the mutex, double-checks, builds, and publishes.

The fast path is correct because: - h.val.Store(v) is a release that publishes the writes inside newBig() (which built *v). - h.val.Load() is an acquire that synchronizes with the store. - After the load returns non-nil, the writes to *v are visible.

This is exactly the pattern sync.Once implements internally. For your code, just use sync.Once. For library design where sync.Once doesn't fit, use the DCL pattern above.

Why is DCL famously broken in Java pre-5?¶

In Java before 1.5, the memory model was weaker. The classic broken DCL:

class Singleton {
    private static Singleton instance;
    public static Singleton getInstance() {
        if (instance == null) {
            synchronized (Singleton.class) {
                if (instance == null) {
                    instance = new Singleton();
                }
            }
        }
        return instance;
    }
}

The problem: new Singleton() involved allocating memory, calling the constructor, and writing the reference to instance. These could be reordered such that instance was assigned before the constructor finished. A second thread reading instance non-atomically could see a non-null but uninitialized object.

The fix (Java 5+) was to declare instance as volatile, which provides acquire/release for accesses. Java's volatile is roughly equivalent to Go's sync/atomic.

Go's DCL works correctly with atomic.Pointer[T] for the same reason: the atomic store/load act as release/acquire fences.

Spelling out the fences¶

The compiler emits:

• On x86: atomic.Store becomes XCHG (a locked instruction that's seq-cst); atomic.Load is a plain mov (because x86 loads are already acquire by default).
• On ARM64: atomic.Store becomes STLR (store with release); atomic.Load becomes LDAR (load with acquire). Plus extra fences for seq-cst.

The compiler knows these emissions, so the generated machine code preserves the ordering. Your Go source code expresses the ordering via the atomic operations. The compiler is the bridge.

Seqlocks¶

A seqlock (sequence lock) is a reader-writer synchronization mechanism that prioritizes writers. Readers don't block, but may have to retry if a write occurs during their read.

The idea:

• A writer increments a version counter, writes the data, increments the counter again.
• A reader reads the counter, reads the data, reads the counter again. If both reads of the counter match and the value is even, the read was consistent. If they differ or the counter is odd (meaning a write is in progress), retry.

type Seqlock[T any] struct {
    version atomic.Uint64
    mu      sync.Mutex // writers serialize
    data    T
}

func (s *Seqlock[T]) Write(fn func(*T)) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.version.Add(1) // odd: write in progress
    fn(&s.data)
    s.version.Add(1) // even: write complete
}

func (s *Seqlock[T]) Read() T {
    for {
        v1 := s.version.Load()
        if v1%2 != 0 {
            // writer in progress
            runtime.Gosched()
            continue
        }
        d := s.data
        v2 := s.version.Load()
        if v1 == v2 {
            return d
        }
        // retry
    }
}

Wait — the read of s.data is non-atomic. Is this a race?

Strictly under the Go memory model: yes, it's a race, because the writer is modifying s.data without synchronization with the reader. The race detector will flag it.

Seqlocks fundamentally rely on detecting and recovering from torn reads. They are not race-free in the strict memory-model sense. In Linux kernel C they work because the C memory model allows readers to consume garbage and then check whether the read was valid.

In Go, you cannot safely write seqlocks for arbitrary T. You can write a restricted version where T is a sequence of atomic-sized fields, each read atomically:

type Seqlock struct {
    version atomic.Uint64
    mu      sync.Mutex
    x, y    atomic.Int64
}

func (s *Seqlock) Write(xv, yv int64) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.version.Add(1)
    s.x.Store(xv)
    s.y.Store(yv)
    s.version.Add(1)
}

func (s *Seqlock) Read() (int64, int64) {
    for {
        v1 := s.version.Load()
        if v1%2 != 0 {
            runtime.Gosched()
            continue
        }
        x := s.x.Load()
        y := s.y.Load()
        v2 := s.version.Load()
        if v1 == v2 {
            return x, y
        }
    }
}

Now x and y are atomics. The reader's load is per-field atomic. If a writer ran between the version reads, we discard the result and retry.

Use seqlocks when:

• Read-heavy workload.
• Writes are rare and short.
• You can decompose the data into a small number of atomic fields.

Performance: reads are mostly wait-free (no contention with writers in the common case). Writers contend with each other through the mutex.

For arbitrary T, prefer atomic.Pointer[T] with copy-on-write — it's race-free and almost as fast.

Lock-Free Queues and Stacks¶

Treiber stack¶

A classic lock-free stack using CAS on the head:

type Stack[T any] struct {
    head atomic.Pointer[node[T]]
}

type node[T any] struct {
    val  T
    next *node[T]
}

func (s *Stack[T]) Push(v T) {
    n := &node[T]{val: v}
    for {
        n.next = s.head.Load()
        if s.head.CompareAndSwap(n.next, n) {
            return
        }
    }
}

func (s *Stack[T]) Pop() (T, bool) {
    for {
        top := s.head.Load()
        if top == nil {
            var zero T
            return zero, false
        }
        if s.head.CompareAndSwap(top, top.next) {
            return top.val, true
        }
    }
}

Push: build a new node, link it to the current head, CAS the head. If a concurrent operation changed head, retry.

Pop: read head, CAS head to its successor. If concurrent change, retry.

Publication. A successful Push CAS publishes the new node (and its val/next fields). A successful Pop CAS publishes nothing new — but a _ = top.val read after the CAS is safe because top was published by a prior Push.

ABA. Treiber stacks suffer from ABA in languages without GC: Push A, Pop A, Push A again (same pointer); a concurrent Pop CAS may succeed thinking it's still the original A. In Go, the GC cannot reuse a pointer while live, so ABA is much harder to trigger — but not impossible if you use sync.Pool to recycle nodes. Be careful.

Michael-Scott queue¶

A lock-free FIFO queue. Two CAS operations per enqueue/dequeue.

type Queue[T any] struct {
    head, tail atomic.Pointer[mnode[T]]
}

type mnode[T any] struct {
    val  T
    next atomic.Pointer[mnode[T]]
}

func NewQueue[T any]() *Queue[T] {
    dummy := &mnode[T]{}
    q := &Queue[T]{}
    q.head.Store(dummy)
    q.tail.Store(dummy)
    return q
}

func (q *Queue[T]) Enqueue(v T) {
    n := &mnode[T]{val: v}
    for {
        tail := q.tail.Load()
        next := tail.next.Load()
        if tail != q.tail.Load() {
            continue // tail changed, retry
        }
        if next == nil {
            if tail.next.CompareAndSwap(nil, n) {
                q.tail.CompareAndSwap(tail, n)
                return
            }
        } else {
            // help: advance tail
            q.tail.CompareAndSwap(tail, next)
        }
    }
}

func (q *Queue[T]) Dequeue() (T, bool) {
    for {
        head := q.head.Load()
        tail := q.tail.Load()
        next := head.next.Load()
        if head != q.head.Load() {
            continue
        }
        if head == tail {
            if next == nil {
                var zero T
                return zero, false // empty
            }
            q.tail.CompareAndSwap(tail, next) // help
        } else {
            val := next.val
            if q.head.CompareAndSwap(head, next) {
                return val, true
            }
        }
    }
}

This is the canonical lock-free queue from Michael and Scott (1996). The publication is via CAS on the head and tail pointers. The "helping" mechanism (where a stalled enqueue is finished by another goroutine) makes the algorithm lock-free.

For most Go code, use a buffered channel instead. Channels handle the synchronization, the memory ordering, and the wait-for-empty semantics for you. Lock-free queues are only useful when you need no blocking, ever, and channel costs are unacceptable.

Bounded SPMC ring buffer¶

A single-producer, multi-consumer ring buffer can use only atomic counters:

type Ring[T any] struct {
    buf      []atomicSlot[T]
    head     atomic.Uint64 // producer cursor
    consumed atomic.Uint64 // overall consumed count (for empty check)
    cap      uint64
}

type atomicSlot[T any] struct {
    seq atomic.Uint64
    val T
}

func NewRing[T any](cap int) *Ring[T] {
    r := &Ring[T]{buf: make([]atomicSlot[T], cap), cap: uint64(cap)}
    for i := range r.buf {
        r.buf[i].seq.Store(uint64(i))
    }
    return r
}

func (r *Ring[T]) Push(v T) bool {
    pos := r.head.Load()
    slot := &r.buf[pos%r.cap]
    if slot.seq.Load() != pos {
        return false // full
    }
    slot.val = v
    slot.seq.Store(pos + 1) // publish
    r.head.Add(1)
    return true
}

func (r *Ring[T]) Pop() (T, bool) {
    pos := r.consumed.Add(1) - 1
    slot := &r.buf[pos%r.cap]
    for slot.seq.Load() != pos+1 {
        runtime.Gosched() // wait for producer
    }
    v := slot.val
    slot.seq.Store(pos + r.cap) // mark slot reusable
    return v, true
}

This is a simplified version of Dmitry Vyukov's bounded MPMC queue (with single producer to keep it short). The sequence number on each slot tells consumers when the value is ready and producers when the slot is reusable.

The publication is at slot.seq.Store(pos + 1): the value write is sequenced-before the seq store; consumers waiting on seq == pos+1 acquire and see the value.

RCU in Depth¶

RCU (Read-Copy-Update) is a publication pattern with three rules:

1. Readers see a snapshot. They acquire it via an atomic load.
2. Writers allocate a new snapshot, copy the relevant parts, mutate the copy, publish via atomic store.
3. Old snapshots are reclaimed once no reader holds them.

In the Linux kernel, rule 3 is the hard part — kernel programmers use grace periods to wait until every CPU has passed through a context switch, ensuring no reader holds the old snapshot.

In Go, rule 3 is trivial: the GC handles reclamation. An old snapshot is freed when no reader still holds a reference. The reader's local variable IS the hazard pointer; the GC IS the grace period.

Full RCU pattern¶

type RCU[T any] struct {
    snap atomic.Pointer[T]
    mu   sync.Mutex
}

// Read returns the current snapshot. Wait-free.
func (r *RCU[T]) Read() *T {
    return r.snap.Load()
}

// Update applies fn to a copy of the current snapshot, then publishes.
// fn must not mutate its argument.
func (r *RCU[T]) Update(fn func(*T) *T) {
    r.mu.Lock()
    defer r.mu.Unlock()
    old := r.snap.Load()
    new := fn(old)
    r.snap.Store(new)
}

The mutex serializes writers so that concurrent Updates don't lose intermediates. Readers don't take the mutex.

Variants¶

Lock-free updaters: replace the mutex with CAS-retry:

func (r *RCU[T]) Update(fn func(*T) *T) {
    for {
        old := r.snap.Load()
        new := fn(old)
        if r.snap.CompareAndSwap(old, new) {
            return
        }
    }
}

Use when contention is low and fn is cheap; otherwise the mutex is better.

Versioned RCU: pair each snapshot with a version counter for readers that need to know "did this change since last time?"

Sharded RCU: shard the snapshot by key for writes to different shards to not contend.

RCU vs read-write lock¶

RCU wins when reads dominate and writes are rare. RWMutex wins when reads can't tolerate any staleness or when writes are large.

Hazard Pointers vs Go's GC¶

In C/C++, lock-free data structures must explicitly manage memory: when a node is removed, you can't free it until no reader still has a pointer. Hazard pointers solve this: each reader publishes the pointers it's "holding"; before freeing, the writer checks no hazard pointer matches.

Implementation is intricate. In Go, you can usually just rely on the GC:

top := s.head.Load()
// We now "hold" *top. GC will not free it.
val := top.val
// Done with top. GC will free when unreachable.

The local variable acts as the hazard pointer. When top goes out of scope, the GC may reclaim the node.

This is a massive simplification. Hazard pointer libraries in C++ are 500+ lines; in Go, the equivalent is "let the GC do it."

The cost: occasional GC pauses. For most concurrent code in Go, the simplicity is worth it.

When hazard pointers in Go do make sense:

• Real-time code with strict latency requirements (no GC pause allowed).
• Resource pools where sync.Pool won't help.
• Foreign-memory references (e.g., mmaped buffers).

For these, you implement explicit reference counting plus epoch-based reclamation. The complexity is genuinely high.

The Cost of Sequential Consistency¶

Go's atomics are seq-cst. On x86 this is essentially free; on ARM it costs a fence per store.

Concrete cost (rough):

On ARM, you could shave 2-3 ns per store by using release-only ordering instead of seq-cst. Go does not expose this option, on the (sound) judgment that programmer time is more valuable than 2 ns.

When would a Go program suffer from this? Only in tight atomic loops with very specific patterns. Examples:

• A producer-consumer ring buffer doing millions of stores per second.
• A lock-free hashmap with frequent CAS retries.
• A massively parallel counter increment.

For these, you might use runtime/internal/atomic (an internal-only API) or accept the cost. Don't reach for it without benchmarks proving it matters.

Designing a Concurrent Library¶

When you design a concurrent library, decide:

1. What's the unit of access? A single object? A collection? A stream?
2. What's the read/write ratio? Read-mostly? Balanced? Write-heavy?
3. What's the contention pattern? Single hot key? Many cold keys? Bursty?
4. What's the consistency requirement? Snapshot? Linearizable? Eventually consistent?
5. What's the latency budget? Microseconds? Nanoseconds?

Each combination has a canonical answer:

Library API style¶

// GOOD: synchronization is internal.
type Cache struct { /* private */ }
func New() *Cache { ... }
func (c *Cache) Get(k string) (V, bool) { ... }
func (c *Cache) Set(k string, v V)      { ... }
func (c *Cache) Snapshot() []KV         { ... }

// BAD: caller manages lock.
type Cache struct {
    Mu   sync.Mutex
    Data map[string]V
}

Document concurrency in the package comment:

// Package cache provides a concurrent, in-memory key-value store
// optimized for read-heavy workloads. All methods are safe to call
// from any goroutine. Get is wait-free; Set may block briefly under
// contention.

Document per-method:

// Get returns the value for k, or (zero, false) if missing.
// Wait-free; safe for concurrent use.
func (c *Cache) Get(k string) (V, bool) { ... }

Memory Reclamation Patterns¶

When a concurrent structure removes an element, when can it be reclaimed?

Pattern 1: GC handles it¶

Most Go code. Local variables in readers act as roots; when readers finish, the structure becomes unreachable; GC collects.

Pattern 2: Reference counting¶

For non-Go memory (mmap, C memory) or strict-latency code, use atomic ref counts:

type Refcounted struct {
    refs atomic.Int32
    data []byte
}

func (r *Refcounted) Acquire() {
    r.refs.Add(1)
}

func (r *Refcounted) Release() {
    if r.refs.Add(-1) == 0 {
        r.free()
    }
}

Drawbacks: contention on the count under high concurrency.

Pattern 3: Epoch-based reclamation¶

Each goroutine reads/writes within an "epoch." When all goroutines have advanced past epoch N, structures freed in epoch N-1 can be reclaimed.

Libraries: github.com/datawire/probedns/internal/epoch. Rarely needed; Go's GC is usually enough.

Pattern 4: Quiescent-state-based reclamation¶

Detect when no goroutine is holding any pointer to old data, then free. Implemented in some kernel codebases; not idiomatic in Go.

For Go, prefer GC unless profiling proves otherwise.

Wait-Free vs Lock-Free vs Obstruction-Free¶

Definitions:

• Wait-free: every operation completes in a bounded number of steps regardless of other goroutines.
• Lock-free: at every step, at least one goroutine makes progress.
• Obstruction-free: a goroutine makes progress if no other goroutine touches its data.

Examples:

• atomic.Load: wait-free. Always one step.
• atomic.Store: wait-free.
• atomic.CompareAndSwap: wait-free per call, but a CAS-retry loop is only lock-free.
• Treiber stack Push: lock-free (may retry).
• Michael-Scott queue: lock-free (may retry).
• Mutex: not lock-free. A holder of the mutex may be paused by the OS, blocking everyone.

Wait-free is rare and expensive. Most "lock-free" libraries are actually lock-free in the strict sense, not wait-free.

When does this matter? In real-time systems where you must guarantee a maximum latency. For most Go services, "lock-free" is a fine approximation.

Cache-Line and False Sharing¶

Modern CPUs read memory in 64-byte (or 128-byte on Apple Silicon) cache lines. Two unrelated variables in the same cache line ping-pong between CPU caches when both are written, even though they are logically independent. This is false sharing.

type Counters struct {
    A atomic.Int64 // 8 bytes
    B atomic.Int64 // 8 bytes
}

If goroutine 1 hammers A and goroutine 2 hammers B, both threads' CPUs invalidate each other's cache lines on every write. Performance collapses.

Fix: pad to a cache line:

type Counters struct {
    A atomic.Int64
    _ [56]byte // pad to 64 bytes
    B atomic.Int64
    _ [56]byte
}

Now A and B are in different cache lines.

This is critical for:

• Sharded counters (each shard in its own cache line).
• Per-P data (each P's slot in its own cache line).
• Workqueue heads and tails.

Use sync/atomic.Int64.Add with no padding, and benchmark. If you see degradation as core count rises but not as work-per-core rises, false sharing is the suspect.

runtime/internal/sys and cache line size¶

The Go runtime knows the cache line size per architecture. You can sometimes infer it from unsafe.Sizeof of certain types or by examining the assembly. For most cases, 64 bytes is a safe assumption.

Verifying Concurrent Code¶

Race detector¶

go test -race ./... should be green. Run with -count=10 to increase confidence.

Stress tests¶

func TestPublishStress(t *testing.T) {
    const goroutines = 64
    const iterations = 100000

    var s atomic.Pointer[State]
    var wg sync.WaitGroup

    for i := 0; i < goroutines; i++ {
        wg.Add(1)
        go func(seed int) {
            defer wg.Done()
            for j := 0; j < iterations; j++ {
                if j%2 == 0 {
                    s.Store(&State{X: seed*1000 + j})
                } else {
                    if st := s.Load(); st != nil && st.X == 0 {
                        t.Errorf("zero state")
                    }
                }
            }
        }(i)
    }
    wg.Wait()
}

Run with -race -count=100. Stress tests catch races that simple tests miss.

Model checking¶

Tools like TLA+ and Promela let you verify the safety/liveness of concurrent algorithms. Overkill for most Go code, but if you're implementing a novel lock-free structure, write a TLA+ spec first.

Formal proof¶

For library code, a written proof (in comments) of why publication is correct is gold:

// Publication: 
// - Writers update s via CAS on the snap pointer.
// - Readers acquire by loading snap.
// - The snap.Store in Update is a release fence; readers observe
//   the writes inside fn before snap.Store.
// - The mutex serializes writers so that two concurrent Updates
//   don't both copy and re-publish, losing one.

When to Drop to Assembly¶

Almost never. The Go compiler and runtime emit correct atomic operations for every supported architecture. Dropping to assembly is justified only when:

• You need a non-standard atomic operation (e.g., 128-bit CAS).
• You need fence elision the compiler doesn't perform.
• You're writing the runtime itself.

For 99.99% of Go code, the answer is "use sync/atomic."

If you do drop to assembly, use Go's .s files in the package and document the contract precisely.

Common Senior-Level Mistakes¶

Over-engineering with atomics¶

A sync.Mutex is fine for most cases. Don't reach for atomics unless you've profiled.

Ignoring the race detector¶

If -race reports a race, fix it. Don't silence it. Don't decide "it's harmless." Even harmless races are undefined behavior; future compilers may exploit them.

Forgetting reclamation¶

In Go you mostly don't have to worry, but for sync.Pool-recycled nodes or unsafe-allocated memory, you must.

Wrong invariants¶

A concurrent type's correctness rests on invariants that must hold during every state of every concurrent execution. If you can't articulate them in one paragraph, the type is too complex.

Premature lock-freedom¶

Lock-free code is harder to write, harder to read, and not always faster. Profile first. Mutexes are not slow; contention is slow.

Cheat Sheet¶

HAPPENS-BEFORE SOURCES IN GO
============================

go f()              hb first action of f
ch <- v             hb completion of receive
close(ch)           hb receive returning closed
mu.Unlock() (nth)   hb mu.Lock() returning (n+1)th
once.Do(f) (winner) hb every other once.Do return
atomic.Store        hb any atomic.Load that sees the value
wg.Done()           hb wg.Wait() return when counter=0

DOUBLE-CHECKED LOCKING (Go)
===========================

type Holder struct {
    val atomic.Pointer[T]
    mu  sync.Mutex
}

func (h *Holder) Get() *T {
    if v := h.val.Load(); v != nil {
        return v
    }
    h.mu.Lock()
    defer h.mu.Unlock()
    if v := h.val.Load(); v != nil {
        return v
    }
    v := build()
    h.val.Store(v)
    return v
}

LOCK-FREE STACK
===============

push: CAS head, retry on conflict
pop:  CAS head to head.next, retry on conflict

LOCK-FREE QUEUE (M-S)
=====================

enqueue: CAS tail.next from nil, then advance tail
dequeue: CAS head to head.next

RCU
===

read:   atomic.Pointer.Load()
update: mu.Lock(); old := load(); new := f(old); store(new); mu.Unlock()

Summary¶

The senior level requires you to:

• Cite specific axioms of the Go memory model.
• Implement double-checked locking, seqlocks, and lock-free structures correctly.
• Reason about happens-before chains across multiple goroutines.
• Choose between RCU, RWMutex, and sharded mutexes by workload analysis.
• Recognize cache-line effects and false sharing.
• Use the race detector and stress tests effectively.
• Know when to not go lock-free.

You can now read papers from the parallel-programming literature, translate algorithms into Go, and explain the publication contract to a teammate in one paragraph.

Next: professional.md, which maps Go's semantics to C++ and Rust, dives into runtime internals, and discusses fence elision and the cost of seq-cst per architecture.

Further Reading¶

• Go memory model: https://go.dev/ref/mem (2022 revision).
• Michael & Scott, "Simple, Fast, and Practical Non-Blocking and Blocking Concurrent Queue Algorithms" (1996).
• Treiber, "Systems Programming: Coping with Parallelism" (1986).
• McKenney et al., "RCU Usage in the Linux Kernel: One Decade Later" (2013).
• Adve & Hill, "Weak Ordering — A New Definition" (1990).
• Russ Cox, "Programming Language Memory Models" (2021).
• Boehm, "Threads Cannot Be Implemented as a Library" (2005).
• Dmitry Vyukov's blog: https://www.1024cores.net.

End of senior.md.

Appendix A: Worked Memory-Model Examples¶

A.1 — Two writes, two reads¶

var x, y int
var fx, fy atomic.Int32

// G1:
x = 1
fx.Store(1)

// G2:
y = 2
fy.Store(1)

// G3:
for fx.Load() == 0 { }
for fy.Load() == 0 { }
fmt.Println(x, y)

Question: does G3 print "1 2"?

Analysis: - x = 1 is sequenced-before fx.Store(1). - G3's fx.Load() == 1 synchronizes-with G1's fx.Store(1). - Therefore x = 1 happens-before G3's read of x. - Same for y. - G3 prints "1 2".

This is the basic publication pattern, twice.

A.2 — Race between two atomic stores¶

var fa atomic.Int32
var fb atomic.Int32

// G1:
fa.Store(1)

// G2:
fb.Store(1)

// G3:
ax := fa.Load()
bx := fb.Load()
fmt.Println(ax, bx)

Question: what does G3 print?

G3 may print any of: 0 0, 1 0, 0 1, 1 1. There is no happens-before edge between G1 and G2 and G3, except through the atomic operations themselves. G3 may observe the atomics in either order (or neither).

Under sequential consistency: all three goroutines agree on the global order of the two stores. So if G3 sees fa=1 and fb=0, then at the moment of the fb load, fb's store hadn't happened yet — consistent with a single global order.

A.3 — Independent reads of independent writes¶

var fa, fb atomic.Int32

// G1: fa.Store(1)
// G2: fb.Store(1)

// G3:
a := fa.Load()
b := fb.Load()

// G4:
b2 := fb.Load()
a2 := fa.Load()

Question: can G3 see (1, 0) and G4 see (1, 0)?

Under release/acquire only: yes. G3's view is consistent with [G2 -> G1] order; G4's view is consistent with [G1 -> G2] order.

Under sequential consistency (Go): no. There is a single global order. If G3 saw fa=1 before fb, then G4 cannot see fb=1 before fa.

This is the famous IRIW (Independent Reads of Independent Writes) test. Go's seq-cst saves you from this confusion.

A.4 — The Dekker pattern¶

var fa, fb atomic.Int32

// G1:
fa.Store(1)
if fb.Load() == 0 {
    // critical section
}

// G2:
fb.Store(1)
if fa.Load() == 0 {
    // critical section
}

Question: under what conditions can both enter the critical section?

Under sequential consistency: impossible. The four atomics form a single global order; in any order, one of the two will observe the other's flag set.

Under release/acquire only: possible. The store in G1 is release; the load in G1 is acquire. But the load might be reordered before the store on weakly ordered hardware (because acquire doesn't fence subsequent reads against preceding writes).

Go gives you seq-cst, so the Dekker pattern works as expected. You shouldn't write code like this — use a mutex — but it's good to know your atomics are strong.

A.5 — Channel happens-before chain¶

ch1 := make(chan int)
ch2 := make(chan int)
var x int

// G1:
x = 1
ch1 <- 1

// G2:
<-ch1
ch2 <- 2

// G3:
<-ch2
fmt.Println(x)

Question: does G3 print 1?

Yes. Transitivity: x = 1 happens-before send on ch1, which happens-before receive on ch1 in G2, which happens-before send on ch2, which happens-before receive on ch2 in G3, which happens-before the read of x.

This shows the power of happens-before composition.

Appendix B: Building a Concurrent Library¶

We'll design a concurrent set with lock-free contains and mutex-protected adds/removes.

Design¶

package conset

import (
    "sync"
    "sync/atomic"
)

type Set[T comparable] struct {
    data atomic.Pointer[map[T]struct{}]
    mu   sync.Mutex
}

func New[T comparable]() *Set[T] {
    return &Set[T]{}
}

func (s *Set[T]) Contains(x T) bool {
    m := s.data.Load()
    if m == nil {
        return false
    }
    _, ok := (*m)[x]
    return ok
}

func (s *Set[T]) Add(x T) {
    s.mu.Lock()
    defer s.mu.Unlock()
    old := s.data.Load()
    n := map[T]struct{}{x: {}}
    if old != nil {
        for k := range *old {
            n[k] = struct{}{}
        }
    }
    s.data.Store(&n)
}

func (s *Set[T]) Remove(x T) {
    s.mu.Lock()
    defer s.mu.Unlock()
    old := s.data.Load()
    if old == nil {
        return
    }
    if _, ok := (*old)[x]; !ok {
        return
    }
    n := map[T]struct{}{}
    for k := range *old {
        if k != x {
            n[k] = struct{}{}
        }
    }
    s.data.Store(&n)
}

func (s *Set[T]) Size() int {
    m := s.data.Load()
    if m == nil {
        return 0
    }
    return len(*m)
}

Correctness analysis¶

Contains. Single atomic load + map read. The map referent is immutable after the Store, so the read is safe.

Add. Locks for serialization. Reads the current map atomically, builds a new map, stores it atomically. Concurrent Contains calls see either the old map (without x) or the new map (with x). No partial state.

Remove. Symmetric to Add.

Size. Wait-free; may return stale size if a concurrent Add/Remove is happening, but always returns some recent size.

Publication invariants¶

The library's documentation should state:

// Set is a concurrent set safe for use from multiple goroutines.
// Contains and Size are wait-free.
// Add and Remove are serialized; concurrent Add/Remove block each
// other but do not block Contains or Size.
// The set provides snapshot semantics: a Contains call returns the
// answer for some valid past state of the set, possibly slightly
// stale relative to a concurrent Add/Remove.

Cost¶

For a set of N elements:

• Contains: O(1) average. Wait-free.
• Add: O(N) due to map copy. Serialized.
• Remove: O(N) due to map copy. Serialized.
• Size: O(1). Wait-free.

For workloads with N up to a few thousand and infrequent adds/removes (say, 100/sec), this is plenty. For larger sets or more frequent writes, switch to:

• sync.Map if reads still dominate.
• sync.RWMutex + map[T]struct{} if you need in-place mutation.
• Sharded sets if a hot key causes contention.

Appendix C: A Lock-Free Hashmap Sketch¶

A full lock-free hashmap is complex (Cliff Click's original is ~1000 lines of Java). The publication is via per-bucket linked lists.

type LFMap[K comparable, V any] struct {
    buckets []atomic.Pointer[entry[K, V]]
}

type entry[K comparable, V any] struct {
    key   K
    val   V
    next  atomic.Pointer[entry[K, V]]
}

func (m *LFMap[K, V]) bucket(k K) *atomic.Pointer[entry[K, V]] {
    h := hashFn(k)
    return &m.buckets[h%uint64(len(m.buckets))]
}

func (m *LFMap[K, V]) Get(k K) (V, bool) {
    b := m.bucket(k)
    for e := b.Load(); e != nil; e = e.next.Load() {
        if e.key == k {
            return e.val, true
        }
    }
    var zero V
    return zero, false
}

func (m *LFMap[K, V]) Put(k K, v V) {
    b := m.bucket(k)
    n := &entry[K, V]{key: k, val: v}
    for {
        // First, check if key exists; if so, this is an update.
        // (Simplified: lock-free updates of values are even harder.)
        head := b.Load()
        n.next.Store(head)
        if b.CompareAndSwap(head, n) {
            return
        }
    }
}

This sketch doesn't handle delete or resize correctly. Production lock-free hashmaps add:

• Lazy deletion via tombstones.
• Concurrent resize (the "split-ordered" trick from Shalev & Shavit).
• Hazard pointers or epoch reclamation for safe memory management (Go's GC handles this).

For most Go code, sync.Map is the answer. Lock-free hashmaps are research code.

Appendix D: Cache Coherence and Performance¶

A CPU socket has multiple cores; each core has its own L1/L2 cache; cores share an L3. Cache coherence protocols (MESI, MOESI, MESIF) keep these caches in sync.

When core A writes to a line that core B has cached:

1. A's cache line transitions to "Modified" or "Exclusive."
2. B's cache line is invalidated.
3. B's next read incurs a cache miss; the line is fetched (from A's cache or memory).

This is the cost of write contention. Even with atomics, write-heavy contention serializes cores at the cache-coherence level.

Measuring it¶

A simple benchmark:

var counter atomic.Int64

func BenchmarkCounter(b *testing.B) {
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            counter.Add(1)
        }
    })
}

Run with -cpu=1,2,4,8,16. You'll see throughput decrease with more cores, because the cache-line bouncing dominates.

Fix: shard the counter.

var counters [64]struct {
    n atomic.Int64
    _ [56]byte // pad
}

func Inc() {
    s := runtime_procPin()
    counters[s%64].n.Add(1)
    runtime_procUnpin()
}

func Sum() int64 {
    var s int64
    for i := range counters {
        s += counters[i].n.Load()
    }
    return s
}

Now each core writes to its own shard; no cache-line contention. Throughput scales linearly.

The cost of Sum is O(shards), but Sum is rare (e.g., once per scrape).

Appendix E: A Real-World Wait-Free Reader Pattern¶

Suppose you have a large read-mostly state (many MB) and want truly wait-free reads. Copy-on-write doesn't work because copying MB is slow.

Pattern: double-buffered state.

type Buffered[T any] struct {
    bufs [2]T
    idx  atomic.Uint32 // 0 or 1
    mu   sync.Mutex    // writers serialize
}

func (b *Buffered[T]) Read(fn func(*T)) {
    i := b.idx.Load() & 1
    fn(&b.bufs[i])
}

func (b *Buffered[T]) Update(fn func(*T)) {
    b.mu.Lock()
    defer b.mu.Unlock()
    next := (b.idx.Load() + 1) & 1
    b.bufs[next] = b.bufs[b.idx.Load()&1] // copy current
    fn(&b.bufs[next])
    b.idx.Add(1) // publish
}

Wait — this has a bug. The reader may be using bufs[i] while the writer is overwriting bufs[i] on the next Update.

To fix, you need a way to wait for readers to finish before reusing a buffer. That's quiescent-state-based reclamation, which is hard in user-space.

A simpler fix: triple-buffering, or RCU-style atomic.Pointer with old buffers garbage-collected.

For real wait-free reader patterns with large state, use atomic.Pointer[T] with copy-on-write and let GC handle reclamation. It's not strictly wait-free (CoW takes O(state-size)), but reads are.

If you need both wait-free reads AND wait-free writes on large state, you need hazard pointers or epoch reclamation. Most Go code doesn't need this.

Appendix F: When Sync.Once Isn't Enough¶

sync.Once is great until you need:

• Retry on error.
• Re-initialization (e.g., on config reload).
• Cancellation via context.

For these, build your own:

type RetriableOnce struct {
    mu    sync.Mutex
    done  atomic.Bool
}

func (r *RetriableOnce) Do(fn func() error) error {
    if r.done.Load() {
        return nil
    }
    r.mu.Lock()
    defer r.mu.Unlock()
    if r.done.Load() {
        return nil
    }
    if err := fn(); err != nil {
        return err
    }
    r.done.Store(true)
    return nil
}

type CancelableOnce struct {
    mu   sync.Mutex
    done atomic.Bool
}

func (r *CancelableOnce) Do(ctx context.Context, fn func(context.Context) error) error {
    if r.done.Load() {
        return nil
    }
    r.mu.Lock()
    defer r.mu.Unlock()
    if r.done.Load() {
        return nil
    }
    if err := fn(ctx); err != nil {
        return err
    }
    r.done.Store(true)
    return nil
}

Both follow the DCL pattern. The atomic Load is the fast path; the mutex is the slow path; the atomic Store publishes the result.

Appendix G: A Catalog of Memory-Model Bugs¶

G.1 — The store-before-build bug¶

ptr := &S{} // empty struct
atomic.StorePointer(&p, unsafe.Pointer(ptr)) // publish
ptr.field = 5 // RACE: write after publish

Fix: build first, publish last.

G.2 — The read-after-load bug¶

ptr := atomic.LoadPointer(&p)
field := (*S)(ptr).field // OK
ptr.next = nil // RACE: mutation of published pointer

Fix: treat published pointers as immutable.

G.3 — The split atomic bug¶

atomic.StoreInt32(&hi, h)
atomic.StoreInt32(&lo, l)

// Reader:
h := atomic.LoadInt32(&hi)
l := atomic.LoadInt32(&lo)
// (h, l) may be inconsistent

Fix: pack into a single atomic (e.g., atomic.Uint64 with high/low halves) or wrap with a mutex.

G.4 — The atomic-with-plain bug¶

atomic.StoreInt32(&x, 1)
y = 2

// Reader:
if atomic.LoadInt32(&x) == 1 {
    z = y // visible because of acq-rel on x
}

// Writer 2 (different goroutine):
y = 3 // RACE with reader's z = y

Fix: any mutable shared variable must be synchronized.

G.5 — The captured-loop bug¶

for i := 0; i < 10; i++ {
    go func() {
        ch <- i // pre-Go 1.22: captures by reference
    }()
}

Fix (pre-1.22): rebind i inside the loop. (Go 1.22+ fixed this.)

G.6 — The init-races-with-main bug¶

var cfg *Config

func init() {
    go reloadLoop() // starts before cfg is ready
}

func main() {
    cfg = load()
    // reloadLoop may have already raced
}

Fix: load cfg in init, before spawning.

G.7 — The done-without-wait bug¶

done := make(chan struct{})
go func() {
    work()
    close(done)
}()
// forgot to wait

Fix: <-done somewhere.

G.8 — The redundant-sync bug¶

mu.Lock()
defer mu.Unlock()
atomic.StoreInt32(&v, 1) // redundant: mutex provides ordering

The atomic is doing extra work. If access is always within the mutex, plain v = 1 is enough. (But: if any code reads v outside the mutex, you need the atomic.)

G.9 — The non-resetting WaitGroup bug¶

var wg sync.WaitGroup
wg.Add(3)
// ...
wg.Wait()
wg.Add(2) // potentially racy if a goroutine is still in Wait

Fix: don't reuse a WaitGroup after Wait returns. Create a new one.

G.10 — The forgotten capture in errgroup¶

g, ctx := errgroup.WithContext(parent)
for _, url := range urls {
    g.Go(func() error {
        return fetch(ctx, url) // pre-1.22: url is shared
    })
}

Fix (pre-1.22): shadow url. (Go 1.22+ fixed this.)

Appendix H: Reading Russ Cox's Memory Model Paper¶

The current Go memory model document is short but dense. Key points to internalize:

1. The model is "DRF-SC or catch fire": data-race-free programs are sequentially consistent. Programs with races have undefined behavior.

2. Atomic operations in Go are sequentially consistent. This is stronger than C/C++ release/acquire and strictly stronger than Java volatile.

3. Specific synchronization edges are enumerated; nothing else creates happens-before.

4. The compiler is free to reorder code that doesn't cross a synchronization barrier.

5. Reading and writing the same memory location concurrently without synchronization is a data race even if you "know" the timing.

Re-read https://go.dev/ref/mem at least twice. Underline every sentence with "synchronizes" or "happens-before" in it.

Appendix I: A Walk Through sync.RWMutex Internals¶

type RWMutex struct {
    w           Mutex  // writer lock
    writerSem   uint32
    readerSem   uint32
    readerCount atomic.Int32 // negative = writer waiting
    readerWait  atomic.Int32 // readers to wait for before write
}

RLock fast path:

func (rw *RWMutex) RLock() {
    if rw.readerCount.Add(1) < 0 {
        // writer waiting; slow path
        runtime_SemacquireMutex(&rw.readerSem, false)
    }
}

A single atomic Add. If a writer is queued (readerCount is negative), the reader blocks.

Lock:

func (rw *RWMutex) Lock() {
    rw.w.Lock() // exclusive writer access
    r := rw.readerCount.Add(-rwmutexMaxReaders) + rwmutexMaxReaders
    if r != 0 && rw.readerWait.Add(r) != 0 {
        runtime_SemacquireMutex(&rw.writerSem, false)
    }
}

Subtracts a large constant from readerCount to make it negative; counts current readers in readerWait; blocks if non-zero.

The publication: every RUnlock is a release; the next Lock is an acquire chained to all RUnlocks. Every Unlock is a release; the next RLock or Lock is an acquire.

Use RWMutex when you have many readers and few writers. The exact cutoff depends on your access pattern; benchmark.

Appendix J: A Word on chan Internals¶

A chan T is a pointer to a hchan struct:

type hchan struct {
    qcount   uint           // total data in queue
    dataqsiz uint           // size of circular queue
    buf      unsafe.Pointer // buffer
    elemsize uint16
    closed   uint32
    elemtype *_type
    sendx    uint
    recvx    uint
    recvq    waitq // list of recv waiters
    sendq    waitq // list of send waiters
    lock     mutex // not sync.Mutex; runtime.mutex
}

Send: 1. Lock the channel. 2. If buffer has space, copy data into buffer, unlock. 3. If receivers are waiting, hand data directly to one, unlock. 4. Otherwise, park on sendq, release lock.

The lock provides acq-rel; the data copy is sequenced inside the critical section.

Publication: anything the sender wrote before ch <- v is visible to the receiver after <-ch. The mutex ensures this.

For unbuffered channels, the send and receive synchronize directly; the sender hands the data to the receiver under the lock.

This is why channels work as publication primitives. They're literally mutex-protected hand-offs.

Appendix K: Atomicity of Floats¶

atomic package doesn't directly support floats. To atomically share a float:

var f atomic.Uint64

// Store:
f.Store(math.Float64bits(3.14))

// Load:
x := math.Float64frombits(f.Load())

Float64bits and Float64frombits are zero-cost reinterpretations of the bit pattern. The atomic operation handles the 64-bit transfer.

Same for Float32 (use Uint32).

For atomic float arithmetic (e.g., add), you'd CAS:

func AddFloat(p *atomic.Uint64, delta float64) float64 {
    for {
        old := p.Load()
        new := math.Float64bits(math.Float64frombits(old) + delta)
        if p.CompareAndSwap(old, new) {
            return math.Float64frombits(new)
        }
    }
}

The CAS retry handles concurrent updates. Float addition is not associative, so the sum may differ slightly from a serial sum, but for monitoring and metrics that's usually fine.

Appendix L: Atomicity of Structs¶

atomic.Pointer[T] is the standard way to atomically share a struct. The struct itself is treated as immutable; the pointer is the swap unit.

If you need to atomically swap a small struct without indirection, pack it into a uint64:

type State struct {
    Status uint8
    Count  uint8
    Pad    [6]byte
}

func packState(s State) uint64 {
    return uint64(s.Status) | uint64(s.Count)<<8
}

func unpackState(u uint64) State {
    return State{Status: uint8(u), Count: uint8(u >> 8)}
}

var state atomic.Uint64

func Set(s State) { state.Store(packState(s)) }
func Get() State { return unpackState(state.Load()) }

For structs that fit in a uint64 (Up to 8 bytes), this is faster than atomic.Pointer[T] because no allocation is needed.

Use it for hot-path packed state. Beyond 8 bytes, use a pointer.

Appendix M: Atomicity Across Multiple Words¶

The atomic package doesn't natively support multi-word atomicity (e.g., 16-byte CAS). On x86-64, CMPXCHG16B is available; on ARM64, CAS pairs of registers. But Go doesn't expose them in the portable API.

Workarounds:

• Pack into a pointer + use generation counter to avoid ABA.
• Use a mutex.
• Use atomic.Pointer[Pair] and accept the indirection.

If you really need 128-bit atomic operations, look at golang.org/x/sys/cpu and write assembly. Rare; most code doesn't need it.

Appendix N: A Mini Memory-Model Test Suite¶

Run these tests with -race. Each demonstrates a memory-model concept.

package memtest

import (
    "sync"
    "sync/atomic"
    "testing"
)

// Atomics establish happens-before.
func TestAtomicPublishes(t *testing.T) {
    var x int
    var done atomic.Int32

    var wg sync.WaitGroup
    wg.Add(2)
    go func() {
        defer wg.Done()
        x = 42
        done.Store(1)
    }()
    go func() {
        defer wg.Done()
        for done.Load() == 0 {
        }
        if x != 42 {
            t.Errorf("got %d", x)
        }
    }()
    wg.Wait()
}

// Channels establish happens-before.
func TestChanPublishes(t *testing.T) {
    var x int
    ch := make(chan struct{})

    go func() {
        x = 42
        close(ch)
    }()
    <-ch
    if x != 42 {
        t.Errorf("got %d", x)
    }
}

// sync.Once publishes its writes.
func TestOncePublishes(t *testing.T) {
    var once sync.Once
    var x int

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            once.Do(func() { x = 42 })
            if x != 42 {
                t.Errorf("got %d", x)
            }
        }()
    }
    wg.Wait()
}

// WaitGroup.Wait synchronizes with Done.
func TestWaitGroupPublishes(t *testing.T) {
    var x int
    var wg sync.WaitGroup

    wg.Add(1)
    go func() {
        x = 42
        wg.Done()
    }()
    wg.Wait()

    if x != 42 {
        t.Errorf("got %d", x)
    }
}

// Mutex Unlock synchronizes with the next Lock.
func TestMutexPublishes(t *testing.T) {
    var mu sync.Mutex
    var x int

    var wg sync.WaitGroup
    wg.Add(2)
    go func() {
        defer wg.Done()
        mu.Lock()
        x = 42
        mu.Unlock()
    }()
    go func() {
        defer wg.Done()
        mu.Lock()
        defer mu.Unlock()
        if x != 0 && x != 42 {
            t.Errorf("got %d", x)
        }
    }()
    wg.Wait()
}