Acquire / Release — Middle Level¶

Table of Contents¶

1. Introduction
2. Recap from Junior
3. Glossary
4. Mental Model: Synchronizes-With
5. Publication Patterns at Scale
6. Lazy Init Beyond sync.Once
7. Read-Mostly State with atomic.Pointer[T]
8. Hot-Reload Configuration
9. Worker Lifecycle Signals
10. Caching with Single-Flight Behaviour
11. Read-Copy-Update (RCU) Pattern
12. Compare-and-Swap as Publication
13. Sequential Consistency vs Acq/Rel — When the Difference Bites
14. Designing the API of a Concurrent Struct
15. Pitfalls and Anti-Patterns
16. Cost Models
17. Testing Concurrent Publication
18. Stress Testing and the Race Detector
19. Profiling Hot Atomics
20. When Atomics Aren't Enough
21. Cheat Sheet
22. Self-Assessment
23. Summary
24. Further Reading
25. Related Topics
26. Diagrams

Introduction¶

Focus: "Now that I know the primitives, how do I compose them into real systems?"

At the junior level you learned that publication needs a release on the producer and an acquire on the consumer, on the same location. You learned the six primitives (mutex, RWMutex, atomic, channel, sync.Once, WaitGroup) and their idiomatic uses.

At the middle level we move from "primitives in isolation" to "patterns in a real service." A real service has:

• A configuration that may reload at runtime.
• A pool of workers with start/stop signals.
• Caches that must invalidate atomically.
• Snapshots that must be consistent across multiple fields.
• Hot paths where atomics matter for performance.

We will design six recurring patterns that you will see in every nontrivial Go service. Each pattern is motivated by a problem, implemented step-by-step, and benchmarked. By the end, you should be able to look at a concurrent data structure and reason: "Where is the release? Where is the acquire? What does it publish?"

You should also understand when the simple patterns break down — when a single atomic.Pointer is insufficient and you need something stronger.

Recap from Junior¶

The contract:

• A release on location L publishes all prior writes (by the same goroutine).
• An acquire on the same L observes those writes (if it observed the released value).
• Together they form a synchronizes-with edge.

The primitives:

• sync.Mutex, sync.RWMutex: Lock = acquire, Unlock = release.
• sync.Once.Do: both, around the user function.
• sync.WaitGroup: Done = release, Wait = acquire.
• chan send/recv: send = release, recv = acquire.
• close(chan) = release; <-chan (closed) = acquire.
• sync/atomic ops: every operation is acq-rel, sequentially consistent.

Idioms:

• atomic.Pointer[T] for one-shot or read-mostly publication.
• sync.Once for lazy init.
• close(chan) for one-shot broadcast.

Move on if those feel automatic. If not, re-read junior.md.

Glossary¶

Mental Model: Synchronizes-With¶

Think of every release-acquire pair as drawing an arrow:

G1: ... ─ release(L) ────┐
                         │ "synchronizes-with"
G2: ... ── acquire(L) ──◄┘

Every operation in G1 sequenced-before the release is now happens-before every operation in G2 sequenced-after the acquire.

Multiple arrows compose. If G1 publishes to L1, G2 acquires L1 and publishes to L2, G3 acquires L2 — then G3 sees everything G1 wrote, transitively.

G1: write x = 5;  release(L1)
                       ↓ s-w
G2:                acquire(L1);  write y = x + 1;  release(L2)
                                                       ↓ s-w
G3:                                                acquire(L2);  read x, read y

G3 sees x = 5 and y = 6, because:

• G1 happens-before G2 (via L1).
• G2 happens-before G3 (via L2).
• Therefore G1 happens-before G3 (transitivity).

This chaining is why programs with many synchronization points still have a coherent global view.

Publication Patterns at Scale¶

A publication pattern solves: "How do I share a value between goroutines safely?" We'll examine six patterns, ordered by complexity.

Pattern 1: one-shot publication¶

The simplest case. One goroutine builds, one or many goroutines consume, no updates.

var current atomic.Pointer[Config]

// Producer (once at startup):
current.Store(loadConfig())

// Consumers (anywhere):
cfg := current.Load()
use(cfg)

Use when: configuration loaded at startup, used forever.

Pattern 2: one-shot signal¶

ready := make(chan struct{})

// Producer:
prepareEverything()
close(ready)

// Consumers:
<-ready
useEverything()

Use when: many consumers must wait for a one-time event.

Pattern 3: lazy init¶

var (
    once sync.Once
    db   *sql.DB
    err  error
)

func DB() (*sql.DB, error) {
    once.Do(func() { db, err = sql.Open(...) })
    return db, err
}

Use when: initialization is expensive and only needed if anyone asks.

Pattern 4: hot-reload (occasional updates)¶

var current atomic.Pointer[Config]

// Reload goroutine:
for range time.Tick(time.Minute) {
    if c, err := loadConfig(); err == nil {
        current.Store(c)
    }
}

// Consumers:
cfg := current.Load()
use(cfg)

Use when: writes are rare (seconds or minutes apart), reads are frequent.

Pattern 5: CAS-based update (concurrent writers)¶

var counter atomic.Int64

// Many goroutines:
for {
    old := counter.Load()
    new := transform(old)
    if counter.CompareAndSwap(old, new) {
        break
    }
}

Use when: many goroutines update the same value with a pure function.

Pattern 6: protected critical section¶

var (
    mu   sync.Mutex
    data State
)

func Update(f func(*State)) {
    mu.Lock()
    defer mu.Unlock()
    f(&data)
}

func Read() State {
    mu.Lock()
    defer mu.Unlock()
    return data
}

Use when: state is multi-field and mutations are non-pure (I/O, allocations).

Lazy Init Beyond sync.Once¶

sync.Once is the default. But there are situations where it falls short:

Failure modes of sync.Once¶

once.Do(f) calls f exactly once. If f panics, once considers itself done — future calls return immediately without running f. This may not be what you want.

Workaround: catch the panic inside f:

once.Do(func() {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("init panic: %v", r)
        }
    }()
    db, err = expensiveInit()
})

If f returns an error, still once considers itself done. Future callers see the same error. This is sometimes desired (don't retry a hopeless init), sometimes not (the dependency was just transiently down).

For retry-on-error, you need a different pattern:

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

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

Now Do retries the initializer until one call succeeds. Concurrent callers serialize through the mutex; successful completion is published via the atomic.

sync.OnceValue and sync.OnceValues¶

Go 1.21 added two helpers:

var GetDB = sync.OnceValue(func() *sql.DB { ... })
var GetDBWithErr = sync.OnceValues(func() (*sql.DB, error) { ... })

OnceValue returns a function that returns the cached value. OnceValues returns one that returns a pair. Both are convenient wrappers around sync.Once + storage.

Use these for ergonomic single-value lazy init. They cannot retry on error.

Generic memoizing initializers¶

For multi-key lazy init (e.g., per-tenant database connections), use a sync.Map plus per-entry sync.Once:

type Pool[K comparable, V any] struct {
    m  sync.Map // map[K]*entry[V]
    fn func(K) V
}

type entry[V any] struct {
    once sync.Once
    val  V
}

func (p *Pool[K, V]) Get(k K) V {
    v, _ := p.m.LoadOrStore(k, &entry[V]{})
    e := v.(*entry[V])
    e.once.Do(func() { e.val = p.fn(k) })
    return e.val
}

Each key gets its own sync.Once. Concurrent calls for the same key block on the same Once; concurrent calls for different keys run in parallel.

The publication semantics: every Get(k) returns a value that has had its initializer fully run, with happens-before from the initializer to the caller. sync.Map.LoadOrStore provides its own acq-rel guarantees on the entry pointer.

Read-Mostly State with atomic.Pointer[T]¶

A reader-mostly state is the workhorse pattern for caches, configurations, lookup tables, and feature flags. The shape:

type ReadMostly[T any] struct {
    p atomic.Pointer[T]
}

func (r *ReadMostly[T]) Load() *T  { return r.p.Load() }
func (r *ReadMostly[T]) Store(t *T) { r.p.Store(t) }

Reads are wait-free (a single atomic load). Writes are wait-free (a single atomic store). The catch: the referent must be treated as immutable.

Why immutability matters¶

If you Store(&v) and then mutate v, readers that already loaded &v see the mutation. That's a race even though the pointer was published atomically.

Concrete bug:

var snap atomic.Pointer[Snapshot]

go func() {
    s := &Snapshot{Count: 0}
    snap.Store(s)
    s.Count = 1 // RACE with readers that loaded s
}()

go func() {
    s := snap.Load()
    if s != nil {
        fmt.Println(s.Count)
    }
}()

Fix: never mutate *s after Store(s). To "update," allocate a new Snapshot:

old := snap.Load()
new := &Snapshot{Count: old.Count + 1}
snap.Store(new)

If multiple writers race, use CAS:

for {
    old := snap.Load()
    new := &Snapshot{Count: old.Count + 1}
    if snap.CompareAndSwap(old, new) {
        break
    }
}

When the referent has slices or maps¶

A Snapshot containing a slice or map is still immutable from a publication standpoint — as long as you don't mutate the slice or map after Store.

type Snapshot struct {
    Hosts []string
}

s := &Snapshot{Hosts: []string{"a", "b"}}
snap.Store(s)
s.Hosts = append(s.Hosts, "c") // RACE: readers see a mutated slice

To update, copy the slice:

old := snap.Load()
newHosts := make([]string, len(old.Hosts)+1)
copy(newHosts, old.Hosts)
newHosts[len(old.Hosts)] = "c"
snap.Store(&Snapshot{Hosts: newHosts})

This pattern is called copy-on-write. It's the cornerstone of RCU.

When the referent has nested pointers¶

type Snapshot struct {
    User *User
}

s := snap.Load()
s.User.Name = "Bob" // Are we mutating?

You are. Even though s is a new Snapshot, s.User may be the same *User as in the previous snapshot. Mutating *s.User mutates the previous snapshot's user too.

Fix: deep-copy when transitioning.

The general rule for atomic.Pointer[T]-published structures: every reachable byte must be immutable. If you can't enforce that, use a mutex.

Hot-Reload Configuration¶

A real example combining several patterns. We want to:

• Load configuration from disk at startup.
• Watch the file for changes.
• Atomically swap to the new configuration when it changes.
• Have readers always see some valid configuration.

package config

import (
    "encoding/json"
    "fmt"
    "os"
    "sync/atomic"
    "time"
)

type Config struct {
    MaxConn  int
    Timeout  time.Duration
    Hosts    []string
}

var (
    current atomic.Pointer[Config]
    path    = "/etc/myservice/config.json"
)

func init() {
    c, err := loadFromDisk(path)
    if err != nil {
        c = &Config{MaxConn: 100, Timeout: time.Second, Hosts: nil}
    }
    current.Store(c)
    go watchLoop()
}

func Get() *Config { return current.Load() }

func watchLoop() {
    var lastMod time.Time
    for range time.Tick(5 * time.Second) {
        info, err := os.Stat(path)
        if err != nil || !info.ModTime().After(lastMod) {
            continue
        }
        c, err := loadFromDisk(path)
        if err != nil {
            fmt.Println("config reload failed:", err)
            continue
        }
        current.Store(c)
        lastMod = info.ModTime()
    }
}

func loadFromDisk(p string) (*Config, error) {
    data, err := os.ReadFile(p)
    if err != nil {
        return nil, err
    }
    var c Config
    if err := json.Unmarshal(data, &c); err != nil {
        return nil, err
    }
    return &c, nil
}

Properties:

• Readers do a single atomic load — wait-free.
• Writes (reload events) are rare and only published if parsing succeeds.
• A read in the middle of a reload sees either the old config or the new config, never a half-parsed one — because parsing happens before Store.
• If reload fails, the old config remains; the service degrades gracefully.

Notice that we deliberately don't expose Set. The only way to update is by editing the file. This restricts the surface area for bugs.

Adding callbacks¶

If consumers need to react to reloads (e.g., re-establish DB connections), expose a channel:

var (
    current atomic.Pointer[Config]
    reload  = make(chan *Config, 1)
)

// In watchLoop, after the successful Store:
select {
case reload <- c:
default:
    // Coalesce if previous reload event not yet consumed.
}

Consumers:

go func() {
    for c := range reload {
        reconfigureDB(c)
    }
}()

The channel acts as both publication (send is release) and queue (capacity 1 with non-blocking send for coalescing).

Worker Lifecycle Signals¶

A pool of workers should start cleanly and stop cleanly. The classic anti-pattern is time.Sleep shutdowns; the right pattern uses signals.

Pattern: shutdown via closed channel¶

type Pool struct {
    stop chan struct{}
    wg   sync.WaitGroup
}

func NewPool(n int) *Pool {
    p := &Pool{stop: make(chan struct{})}
    for i := 0; i < n; i++ {
        p.wg.Add(1)
        go p.worker(i)
    }
    return p
}

func (p *Pool) worker(id int) {
    defer p.wg.Done()
    for {
        select {
        case <-p.stop:
            return
        default:
        }
        doWork(id)
    }
}

func (p *Pool) Stop() {
    close(p.stop)
    p.wg.Wait()
}

close(p.stop) is the release; every worker's <-p.stop is an acquire. After wg.Wait() returns, every worker has called Done, which is a release — so anything they wrote before exiting is visible.

sync.Once could protect against double-close:

type Pool struct {
    stop chan struct{}
    once sync.Once
    wg   sync.WaitGroup
}

func (p *Pool) Stop() {
    p.once.Do(func() { close(p.stop) })
    p.wg.Wait()
}

Pattern: shutdown via context¶

type Pool struct {
    ctx    context.Context
    cancel context.CancelFunc
    wg     sync.WaitGroup
}

func NewPool(parent context.Context, n int) *Pool {
    ctx, cancel := context.WithCancel(parent)
    p := &Pool{ctx: ctx, cancel: cancel}
    for i := 0; i < n; i++ {
        p.wg.Add(1)
        go p.worker(i)
    }
    return p
}

func (p *Pool) worker(id int) {
    defer p.wg.Done()
    for {
        select {
        case <-p.ctx.Done():
            return
        case j := <-jobs:
            handle(j)
        }
    }
}

func (p *Pool) Stop() {
    p.cancel()
    p.wg.Wait()
}

context.Context propagates cancellation through a tree of goroutines. cancel() closes the underlying channel; <-ctx.Done() is an acquire on that close. Plus, the context can carry deadlines, values, and parent cancellation.

This is the modern Go idiom for any operation that needs to be cancellable.

Caching with Single-Flight Behaviour¶

A cache miss may take milliseconds (or seconds). If 100 requests miss at the same time, you don't want 100 upstream fetches. You want one fetch and 100 deliveries.

Naive cache (broken)¶

type Cache struct {
    mu   sync.Mutex
    data map[string]string
}

func (c *Cache) Get(k string, fetch func() string) string {
    c.mu.Lock()
    v, ok := c.data[k]
    c.mu.Unlock()
    if ok {
        return v
    }
    v = fetch() // 100 callers all fetch concurrently
    c.mu.Lock()
    c.data[k] = v
    c.mu.Unlock()
    return v
}

Single-flight cache¶

type Cache struct {
    mu      sync.Mutex
    data    map[string]string
    pending map[string]*pendingFetch
}

type pendingFetch struct {
    done chan struct{}
    val  string
}

func (c *Cache) Get(k string, fetch func() string) string {
    c.mu.Lock()
    if v, ok := c.data[k]; ok {
        c.mu.Unlock()
        return v
    }
    if pf, ok := c.pending[k]; ok {
        c.mu.Unlock()
        <-pf.done
        return pf.val
    }
    pf := &pendingFetch{done: make(chan struct{})}
    if c.pending == nil {
        c.pending = map[string]*pendingFetch{}
    }
    c.pending[k] = pf
    c.mu.Unlock()

    pf.val = fetch()
    c.mu.Lock()
    if c.data == nil {
        c.data = map[string]string{}
    }
    c.data[k] = pf.val
    delete(c.pending, k)
    c.mu.Unlock()
    close(pf.done)
    return pf.val
}

The flow:

1. Take lock, check data[k]. If present, return it. Lock provides acquire.
2. Check pending[k]. If present, we have a fetch in flight. Drop the lock and wait on the channel.
3. Otherwise, mark this key as pending. Drop the lock. Fetch.
4. After fetch, store in data, remove from pending, close the channel.

close(pf.done) is a release; every waiter's <-pf.done is an acquire on it. Writes to pf.val before the close are visible to all readers.

Crucially, writing to pf.val and the close happen outside the mutex. The mutex protects only the maps; the channel close protects the pendingFetch.

For production use, just use golang.org/x/sync/singleflight — it handles errors, cancellation, and tests. But understanding the manual version is essential.

Read-Copy-Update (RCU) Pattern¶

RCU is a publication pattern from kernel development. Readers see a consistent snapshot without locking; writers allocate new versions and publish via atomic pointer swap. Old versions are reclaimed once no reader holds them.

In Go, the GC handles reclamation for you — that's a huge simplification over Linux kernel RCU.

type RCU[T any] struct {
    p atomic.Pointer[T]
}

func (r *RCU[T]) Read() *T { return r.p.Load() }

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

Update takes a pure function: it must not mutate old. It returns a new *T representing the post-update state.

Example: maintain a set of currently connected user IDs.

var users RCU[map[int]bool]

users.Update(func(old *map[int]bool) *map[int]bool {
    cp := map[int]bool{}
    if old != nil {
        for k, v := range *old {
            cp[k] = v
        }
    }
    cp[userID] = true
    return &cp
})

Readers:

if m := users.Read(); m != nil && (*m)[userID] {
    // user is connected
}

The reader holds the snapshot for as long as needed. Even if Update replaces the map during the read, the reader's snapshot is unchanged.

When RCU shines¶

• Frequent reads, infrequent writes (the typical "config" workload).
• Snapshots are small enough to allocate cheaply.
• Readers don't need to wait for writers.
• Writers don't need to wait for readers.

When RCU is wrong¶

• Frequent writes — every update allocates and copies.
• Snapshots are large (millions of entries) — copying is expensive.
• Multiple fields must update atomically across snapshots in a coordinated way.

For large mutable state, sharded mutexes or sync.Map may beat RCU.

Compare-and-Swap as Publication¶

CAS is more than a building block — it's a conditional publication. The semantics:

ok := p.CompareAndSwap(old, new)

If the current value equals old, atomically replace it with new and return true. Otherwise return false. The successful CAS is both:

• An acquire (the comparison observed the current value, which was published by whoever stored it).
• A release (the new value, and any writes to *new's referent before the CAS, are now published to subsequent acquirers).

This makes CAS the universal primitive for lock-free algorithms.

Lock-free stack¶

type Stack[T any] struct {
    top 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.top.Load()
        if s.top.CompareAndSwap(n.next, n) {
            return
        }
    }
}

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

Push: build a new node, set its next to the current top, CAS the top. If a concurrent push changed the top, retry.

Pop: read the top, CAS the top to its successor. If a concurrent pop changed the top, retry.

The publication: a successful Push CAS publishes the new node (and its val). A successful Pop CAS publishes nothing new — it just removes a node.

The ABA problem¶

Naive lock-free structures suffer from ABA: a CAS that expected A may see A again even though the value changed A → B → A in between. The structure may be corrupted.

Go's GC saves you from many ABA bugs because pointers cannot be reused while in scope. (Compare to C/C++ where you'd manage memory yourself.) But ABA still bites when you mix pointers and counters.

Workaround: add a generation counter. Use atomic.Uint64 packing {ptr, generation} together, or a struct.

We'll see lock-free queues with generation counters in senior.md.

Sequential Consistency vs Acq/Rel — When the Difference Bites¶

Go gives you sequential consistency for atomics. Is this overkill?

For most code: yes, slightly. The cost on x86 is negligible (x86 is essentially seq-cst by default). On ARM and POWER, sequential consistency costs an extra fence per store.

When does the difference matter? Two specific patterns:

The producer-consumer flag pair¶

var (
    a atomic.Int32
    b atomic.Int32
)

// Goroutine 1:
a.Store(1)
b.Store(1)

// Goroutine 2:
if b.Load() == 1 {
    // Is a.Load() guaranteed to be 1?
}

Under sequential consistency: yes.

Under pure release/acquire: no — the release on a and the release on b are independent. G2 might see b=1 without seeing a=1.

You will not write code like this in Go because Go gives you SC. But you should know the distinction for cross-language work.

Independent reads of independent writes¶

// Goroutine A: writes a
// Goroutine B: writes b
// Goroutine C: reads a then b
// Goroutine D: reads b then a

// Under SC: C and D see the writes in the same order
// Under acq/rel: C might see a first, D might see b first

This is mostly theoretical for Go programmers. But it explains why Go's choice of SC is "free safety" — you never have to ask "could readers disagree on the order?"

Designing the API of a Concurrent Struct¶

When you build a type that will be touched by multiple goroutines, you make decisions about its synchronization. Common API patterns:

Pattern: explicit lock exposed in the type¶

type Cache struct {
    Mu   sync.Mutex
    data map[string]string
}

Callers lock manually:

c.Mu.Lock()
v := c.data[k]
c.Mu.Unlock()

Pros: caller can do multi-step operations atomically. Cons: easy to forget. Avoid in new code.

Pattern: lock hidden, methods are the surface¶

type Cache struct {
    mu   sync.Mutex
    data map[string]string
}

func (c *Cache) Get(k string) (string, bool) {
    c.mu.Lock()
    defer c.mu.Unlock()
    v, ok := c.data[k]
    return v, ok
}

Pros: caller can't forget to lock. Cons: no multi-step atomicity unless you add specific methods (e.g., GetOrSet).

Pattern: copy-on-write¶

type Cache struct {
    data atomic.Pointer[map[string]string]
}

func (c *Cache) Get(k string) (string, bool) {
    m := c.data.Load()
    if m == nil {
        return "", false
    }
    v, ok := (*m)[k]
    return v, ok
}

func (c *Cache) Set(k, v string) {
    for {
        old := c.data.Load()
        cp := map[string]string{}
        if old != nil {
            for kk, vv := range *old {
                cp[kk] = vv
            }
        }
        cp[k] = v
        if c.data.CompareAndSwap(old, &cp) {
            return
        }
    }
}

Pros: reads are wait-free. Cons: writes are linear in cache size; writers race and retry.

Use when: reads dominate, writes are very rare.

Pattern: sharded locks¶

type Cache struct {
    shards [16]struct {
        mu   sync.Mutex
        data map[string]string
    }
}

func (c *Cache) shard(k string) *struct {
    mu   sync.Mutex
    data map[string]string
} {
    h := fnv.New32a()
    _, _ = h.Write([]byte(k))
    return &c.shards[h.Sum32()%16]
}

func (c *Cache) Get(k string) (string, bool) {
    s := c.shard(k)
    s.mu.Lock()
    defer s.mu.Unlock()
    if s.data == nil {
        return "", false
    }
    v, ok := s.data[k]
    return v, ok
}

Pros: writes can proceed in parallel for different shards. Cons: more memory, slightly complex.

Use when: high contention on a single mutex.

Pitfalls and Anti-Patterns¶

Anti-pattern: atomic plus plain reads¶

atomic.StoreInt32(&v, 1)
// ...
if v == 1 { ... } // RACE

Either all accesses go through sync/atomic, or none do. Mixing them is a race.

Anti-pattern: forgetting to publish¶

type Service struct {
    cache *Cache
}

s := &Service{}
go func() {
    s.cache = newCache() // RACE: no publication
}()
go func() {
    if s.cache != nil { use(s.cache) } // RACE
}()

Fix: atomic.Pointer[Cache] for cache, or initialise before spawning goroutines.

Anti-pattern: mutating a published value¶

snap.Store(s)
s.Count++ // RACE with readers

Published values are immutable. Allocate a new one.

Anti-pattern: holding a lock during slow I/O¶

mu.Lock()
defer mu.Unlock()
result := slowHTTPCall() // holds lock for seconds
cache[k] = result

This serializes all callers. Either use a separate fetch step (drop the lock during I/O) or use a single-flight pattern.

Anti-pattern: double-fetched check¶

if c.data.Load() == nil {
    c.data.Store(buildExpensive())
}

Two goroutines both see nil, both build, only one's value sticks (the other is wasted). Use sync.Once or CAS-based first-write-wins.

Anti-pattern: spinning without yield¶

for atomic.LoadInt32(&ready) == 0 {
    // burns CPU
}

If the wait may be long, use a channel or sync.Cond. If short, at least call runtime.Gosched() periodically.

Cost Models¶

Rough costs (refer to junior.md Appendix D for fuller table):

• atomic.Load: ~1 ns
• atomic.Store: ~5 ns
• atomic.CompareAndSwap: ~5–15 ns (uncontended), much higher under contention
• sync.Mutex.Lock/Unlock: ~15–25 ns uncontended
• Channel send/recv: ~100–300 ns
• Memory allocation (small object): ~25–100 ns
• Map operation (Get): ~50–200 ns
• Map operation (Set, no growth): ~100–500 ns

Implications:

• A CAS-retry loop with N retries costs ~10N ns + the cost of building the new value each retry.
• A copy-on-write update to a map with K entries costs ~K * 100 ns plus an allocation. For K=1000, that's ~100 μs per write.
• An atomic.Pointer.Load is essentially free — use it on hot paths.
• A sync.Mutex is fine for cold paths and modest contention.
• Channels are expensive — don't use them as flags if an atomic suffices.

Testing Concurrent Publication¶

Concurrency bugs are timing-dependent. Tests must be designed to catch them reliably.

Use -race always¶

go test -race -count=10 ./...

-count=10 runs each test 10 times. Race detector instrumentation makes the schedule slightly non-deterministic, increasing the chance of catching rare races.

Stress-test publication¶

func TestSnapshotPublishStress(t *testing.T) {
    var snap atomic.Pointer[Snapshot]
    var wg sync.WaitGroup

    for w := 0; w < 4; w++ {
        wg.Add(1)
        go func(seed int) {
            defer wg.Done()
            for i := 0; i < 10000; i++ {
                snap.Store(&Snapshot{X: seed*10000 + i})
            }
        }(w)
    }

    for r := 0; r < 4; r++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for i := 0; i < 10000; i++ {
                s := snap.Load()
                if s == nil {
                    continue
                }
                _ = s.X // ensure no garbage
            }
        }()
    }

    wg.Wait()
}

Run with -race -count=100. If there's a publication race, the detector will catch it within a few iterations.

Test happens-before guarantees¶

Write tests that would fail if publication were broken, e.g.:

func TestPublishOrder(t *testing.T) {
    type Pair struct{ A, B int }
    var p atomic.Pointer[Pair]

    for trial := 0; trial < 1000; trial++ {
        done := make(chan struct{})
        go func() {
            p.Store(&Pair{A: 1, B: 2})
            close(done)
        }()
        <-done
        got := p.Load()
        if got.A != 1 || got.B != 2 {
            t.Fatalf("trial %d: got %+v", trial, got)
        }
    }
}

If you remove the atomic, the test passes most of the time but fails under -race.

Stress Testing and the Race Detector¶

The race detector instruments all memory accesses with vector-clock tracking. It does not catch races that don't actually occur during the test run. Therefore:

• Vary the goroutine count.
• Vary GOMAXPROCS (e.g., test with 1, 2, and N cores).
• Run tests many times in CI.
• Use t.Parallel() to encourage real concurrent scheduling.
• Avoid timing-dependent assertions; use channels or WaitGroup for synchronization.

go test -race -cpu=1,2,4 -count=10 ./... is a useful CI invocation.

Profiling Hot Atomics¶

If you suspect a hot atomic is a bottleneck:

go test -cpuprofile=cpu.out -bench=.
go tool pprof cpu.out

In pprof, look for sync/atomic or sync.(*Mutex).Lock near the top. Contention shows up as high CPU in lock-acquire code or in retries of CAS loops.

For lock contention, also use the block profile:

import _ "net/http/pprof"
import "runtime"

func init() {
    runtime.SetBlockProfileRate(1)
}

Then go tool pprof http://localhost:6060/debug/pprof/block shows where goroutines wait on locks/channels.

Common findings:

• A sync.Mutex covering a hot read path. Switch to sync.RWMutex or atomic.Pointer[T].
• An atomic.CompareAndSwap loop with high retry count. Switch to a mutex (counterintuitively, less contention).
• A channel used as a flag. Switch to an atomic.Bool.

When Atomics Aren't Enough¶

Atomics work when:

• The shared state fits in a single word (or you can wrap it in atomic.Pointer[T]).
• The state is immutable after publication.
• Multi-step transactions aren't needed.

When you need any of these, reach for a mutex:

• Multi-field updates that must be atomic together.
• Read-modify-write of a mutable structure (e.g., appending to a slice in place).
• Coordination with multiple actors (e.g., bounded queue with both producers and consumers).
• Fairness — atomics provide none.

A mutex is often the right answer. Don't view atomics as "always better" — they trade ergonomics and correctness for performance, and the performance gain often doesn't justify the complexity.

Cheat Sheet¶

PATTERN                       PRIMITIVE                    TYPICAL COST
=======                       =========                    ============

one-shot publication          atomic.Pointer[T]            ~1 ns read
one-shot signal               close(chan)                  ~10 ns recv
lazy init                     sync.Once / sync.OnceValue   ~1 ns after init
hot-reload config             atomic.Pointer[T]            ~1 ns read
CAS counter                   atomic.Int64.Add or CAS      ~5-15 ns
critical section              sync.Mutex                   ~15-25 ns
read-mostly state             atomic.Pointer[T] + RCU      ~1 ns read
sharded state                 [N]struct{mu;state}          ~15-25 ns shard

WHEN TO REACH FOR EACH
======================

atomic.Pointer[T]: read-mostly, immutable referent
sync.Mutex:        mutable critical section, modest contention
sync.RWMutex:      read-mostly with occasional writes, larger critical section
chan:              produce/consume, signal events
sync.Once:         lazy init that runs exactly once
sync.WaitGroup:    wait for N goroutines to finish
context.Context:   cancellation through a tree

Self-Assessment¶

• I can choose between atomic.Pointer[T], sync.Mutex, and sync.RWMutex for a given workload.
• I can implement hot-reload config without locks.
• I can implement a single-flight cache.
• I can describe what RCU is and when to use it.
• I can debug a publication bug found by the race detector.
• I understand why CAS-based updates need a retry loop.
• I know when sequential consistency matters versus when acq/rel would suffice.

Summary¶

The middle level is where publication patterns become real. The primitives from junior level compose into:

• One-shot publication for startup configuration.
• Lazy init with sync.Once.
• Hot-reload via atomic.Pointer[T] swap.
• Worker lifecycle via close-signal and WaitGroup.
• Single-flight cache via mutex plus channel.
• RCU for read-mostly state.
• CAS for lock-free updates.

The key skill is picking the right pattern. Reads dominate? atomic.Pointer[T] with copy-on-write. Multi-field critical section? Mutex. Concurrent counter? atomic.Int64. Wait for an event? Channel.

Sequential consistency gives Go a slight edge over languages with explicit memory orderings: you don't need to ask "could readers disagree?" The cost is a small overhead on weakly-ordered hardware. The benefit is one fewer thing to get wrong.

Next: senior.md, where we unpack double-checked locking, seqlocks, and the formal happens-before axioms.

Further Reading¶

• golang.org/x/sync/singleflight — production single-flight implementation.
• sync.Map source — src/sync/map.go; non-trivial but readable.
• The Go memory model: https://go.dev/ref/mem.
• McKenney, "RCU: Read-Copy-Update": https://lwn.net/Articles/262464/.
• Russ Cox, "Programming Language Memory Models": https://research.swtch.com/plmm.

Related Topics¶

• sync.Map — read-mostly concurrent map.
• sync.RWMutex — reader-writer lock.
• singleflight — dedup concurrent requests.
• Context — cancellation propagation.
• Lock-free data structures (senior level).

Diagrams¶

RCU UPDATE
==========

Step 1: Reader holds snapshot 1.

Snapshot1: {A:1, B:2}  ◄── Reader1
                       ◄── Reader2

Step 2: Writer allocates Snapshot 2.

Snapshot1: {A:1, B:2}  ◄── Reader1, Reader2
Snapshot2: {A:1, B:3}  (not published yet)

Step 3: Writer publishes (atomic store).

Snapshot1: {A:1, B:2}  ◄── Reader1, Reader2
Snapshot2: {A:1, B:3}  ◄── (new readers)

Step 4: Reader3 reads.

Snapshot1: {A:1, B:2}  ◄── Reader1, Reader2
Snapshot2: {A:1, B:3}  ◄── Reader3

Step 5: Old readers finish.

Snapshot2: {A:1, B:3}  ◄── Reader3
(Snapshot1 garbage-collected once unreachable)

SYNCHRONIZES-WITH CHAIN
=======================

G1: write x = 5
    release(L1)  ───────► synchronizes-with ───────► acquire(L1)  G2
                                                      |
                                                      write y = 6
                                                      release(L2) ──► s-w ──► acquire(L2)  G3
                                                                                |
                                                                                read x: 5
                                                                                read y: 6

G3 transitively observes G1's write because of the chain of synchronizes-with edges.

Appendix A: Deeper Case Studies¶

Case Study A.1 — A configuration service for a feature-flag platform¶

Requirements:

• Tens of thousands of consumer goroutines (per-request handlers) read flag values.
• A control-plane goroutine pushes flag updates every few seconds.
• Reads must be wait-free; reads must never observe a half-applied update.
• Updates may add, remove, or modify flags.

Design:

package flags

import (
    "sync"
    "sync/atomic"
    "time"
)

type Flag struct {
    Name        string
    Enabled     bool
    Percent     int
    Variants    map[string]string
}

type Snapshot struct {
    ByName    map[string]*Flag
    Generation uint64
    UpdatedAt  time.Time
}

type Service struct {
    snap atomic.Pointer[Snapshot]
    mu   sync.Mutex // serializes updates
}

func (s *Service) Lookup(name string) (*Flag, bool) {
    snap := s.snap.Load()
    if snap == nil {
        return nil, false
    }
    f, ok := snap.ByName[name]
    return f, ok
}

func (s *Service) Generation() uint64 {
    if snap := s.snap.Load(); snap != nil {
        return snap.Generation
    }
    return 0
}

func (s *Service) Apply(updates []Flag) {
    s.mu.Lock()
    defer s.mu.Unlock()

    old := s.snap.Load()
    newMap := make(map[string]*Flag, lenOrZero(old))
    if old != nil {
        for k, v := range old.ByName {
            newMap[k] = v
        }
    }
    for _, u := range updates {
        u := u
        newMap[u.Name] = &u
    }
    next := &Snapshot{
        ByName:     newMap,
        Generation: lenOrZero(old) + 1,
        UpdatedAt:  time.Now(),
    }
    s.snap.Store(next)
}

func lenOrZero(s *Snapshot) uint64 {
    if s == nil {
        return 0
    }
    return s.Generation
}

What's happening:

• Lookup is wait-free: one atomic load, then a map read. Multiple readers don't contend with each other.
• Apply is serialized through the mutex (only one writer at a time). The mutex prevents two Apply calls from racing each other when reading the current snapshot and computing the next.
• The atomic Store publishes the new snapshot. Every reader's next Load gets the new pointer.
• The Generation counter lets metrics or caches detect "is this snapshot fresh?"
• Old snapshots are garbage-collected once no reader holds them.

This pattern scales to millions of reads per second on commodity hardware.

Case Study A.2 — A connection pool with lazy init per-host¶

Requirements:

• Many goroutines need a connection to host X.
• The first goroutine to ask for host X triggers the dial.
• Subsequent requests reuse the cached connection.
• Each host has its own pool entry; different hosts don't block each other.

Design (sketch):

package pool

import (
    "net"
    "sync"
)

type Conn = *net.TCPConn // simplified

type entry struct {
    once sync.Once
    conn Conn
    err  error
}

type Pool struct {
    m sync.Map // map[string]*entry
}

func (p *Pool) Get(host string) (Conn, error) {
    v, _ := p.m.LoadOrStore(host, &entry{})
    e := v.(*entry)
    e.once.Do(func() {
        e.conn, e.err = dial(host)
    })
    return e.conn, e.err
}

func dial(host string) (Conn, error) {
    addr, err := net.ResolveTCPAddr("tcp", host)
    if err != nil {
        return nil, err
    }
    return net.DialTCP("tcp", nil, addr)
}

The flow:

1. LoadOrStore returns either the existing *entry for the host or stores a new empty one and returns it.
2. Per-entry sync.Once ensures dial runs at most once per host.
3. Other goroutines hitting the same host block inside Once.Do until the first dial completes.
4. Different hosts have different *entrys, hence different Onces — concurrent dials proceed in parallel.

sync.Map provides the publication for the *entry pointer; sync.Once provides the publication for conn and err.

Note: this is a static per-host cache. In production you'd also need eviction, health checks, retries — but the publication story is solid.

Case Study A.3 — A log throttler¶

Requirements:

• Multiple goroutines try to log the same warning ("DB latency exceeded").
• Don't spam the log: emit once per minute.
• Counter visible in metrics.

Design:

package throttle

import (
    "sync/atomic"
    "time"
)

type Throttle struct {
    interval time.Duration
    lastNS   atomic.Int64
    skipped  atomic.Int64
}

func New(d time.Duration) *Throttle {
    return &Throttle{interval: d}
}

func (t *Throttle) Allow() bool {
    now := time.Now().UnixNano()
    last := t.lastNS.Load()
    if now-last < int64(t.interval) {
        t.skipped.Add(1)
        return false
    }
    if !t.lastNS.CompareAndSwap(last, now) {
        // someone else beat us — they win the slot.
        t.skipped.Add(1)
        return false
    }
    return true
}

func (t *Throttle) Skipped() int64 { return t.skipped.Load() }

CAS is the publication: exactly one caller per interval succeeds, the others increment skipped. No locks. Reads (e.g., Skipped()) are wait-free.

Case Study A.4 — A subscriber list¶

Requirements:

• Many subscribers register callbacks.
• A publish loop notifies all current subscribers.
• Subscribers may register/unregister mid-publish; that's fine — they may or may not be notified.

Design:

package pubsub

import (
    "sync"
    "sync/atomic"
)

type Sub struct {
    ID int
    Fn func(string)
}

type Bus struct {
    subs atomic.Pointer[[]Sub]
    mu   sync.Mutex
}

func (b *Bus) Subscribe(s Sub) {
    b.mu.Lock()
    defer b.mu.Unlock()
    cur := b.subs.Load()
    var n []Sub
    if cur != nil {
        n = append(n, *cur...)
    }
    n = append(n, s)
    b.subs.Store(&n)
}

func (b *Bus) Unsubscribe(id int) {
    b.mu.Lock()
    defer b.mu.Unlock()
    cur := b.subs.Load()
    if cur == nil {
        return
    }
    n := make([]Sub, 0, len(*cur))
    for _, s := range *cur {
        if s.ID != id {
            n = append(n, s)
        }
    }
    b.subs.Store(&n)
}

func (b *Bus) Publish(msg string) {
    cur := b.subs.Load()
    if cur == nil {
        return
    }
    for _, s := range *cur {
        s.Fn(msg)
    }
}