Copy-on-Write — Professional Level¶

Table of Contents¶

1. Introduction
2. The Go Memory Model in Detail
3. Inside sync/atomic.Pointer[T]
4. Inside sync/atomic.Value
5. Codegen Across Architectures
6. Memory Ordering Primitives
7. GC Interaction With Snapshots
8. Write Barriers and Pointer Writes
9. Escape Analysis and Snapshots
10. Cache-Line Effects
11. False Sharing in COW Systems
12. RCU in the Linux Kernel Detail
13. Hazard Pointers and Epoch-Based Reclamation
14. Lock-Free Programming Subtleties
15. Weak References and Snapshot Caches
16. unsafe.Pointer for Advanced Cases
17. Assembly-Level Considerations
18. Profiling Lock-Free COW
19. Correctness Proofs and Race Conditions
20. Designing for Hardware
21. Self-Assessment
22. Summary

Introduction¶

Focus: "I can design and ship production COW systems. Now I want to understand the runtime mechanics: how atomic.Pointer[T] is compiled, what the memory model formally guarantees, how the GC interacts with retained snapshots, and the lowest-level mechanics of lock-free programming."

At the professional level, the question is no longer "what should I build?" but "why does the thing I built work?" The senior level taught the patterns; this level explains the substrate.

A professional Go engineer can read the runtime source, follow atomic.Pointer[T] from Go code through SSA IR to architecture-specific instructions, identify cache-line effects in hot paths, and reason about correctness with reference to the Go memory model. They can debug a COW failure by reading goroutine stacks and runtime.MutexProfile output. They know when unsafe.Pointer is necessary and what it costs.

This file dives into the mechanics: memory ordering, codegen, GC interaction, hardware effects, and the formal model that ties them together. Read it slowly. The material is dense but rewards careful study.

The Go Memory Model in Detail¶

The Go memory model defines when one goroutine's writes become visible to another goroutine's reads. It is the formal foundation of all concurrent Go code, including COW.

The happens-before relation¶

The model is built around the happens-before relation. An event A happens-before event B (written A → B) if, intuitively, A's effects are guaranteed to be observable by B.

The relation is established by:

1. Program order within a single goroutine: if A is written before B in source code, A → B.
2. Goroutine creation: the go statement happens-before the first instruction of the new goroutine.
3. Channel operations: a send on a channel happens-before the corresponding receive.
4. Mutex operations: the n-th Unlock on a mutex happens-before the (n+1)-th Lock.
5. sync.Once.Do: the function body happens-before any later call to Do returns.
6. sync/atomic operations: as of Go 1.19, atomics establish happens-before edges between corresponding operations on the same atomic value.

What atomic operations guarantee¶

The Go memory model treats sync/atomic operations as sequentially consistent. From the Go memory model document:

The APIs in the sync/atomic package are collectively "atomic operations" that can be used to synchronize the execution of different goroutines. If the effect of an atomic operation A is observed by atomic operation B, then A is synchronized before B. All the atomic operations executed in a program behave as though executed in some sequentially consistent order.

This is a strong guarantee. Sequential consistency means there is a single global ordering of all atomic operations that is consistent with each goroutine's program order. Concretely:

• An atomic.Store(p, v) followed by atomic.Load(p) == v in another goroutine establishes happens-before: everything before the Store happens-before everything after the Load.
• A CompareAndSwap that succeeds is both a Store and a Load: it establishes happens-before in both directions.

Why this matters for COW¶

The COW publication pattern relies on this guarantee:

// Writer
nextSnap := &Snapshot{Field: value} // (W1)
ptr.Store(nextSnap)                  // (W2)

// Reader
snap := ptr.Load()                   // (R1)
use(snap.Field)                      // (R2)

The chain: - W1 → W2 (program order). - W2 → R1 (because R1 observes the value W2 stored; atomic edge). - R1 → R2 (program order).

Therefore W1 → R2: the reader's snap.Field read sees the value the writer assigned.

Without atomic store/load, this chain breaks. Plain reads and writes have no happens-before with each other; the reader might see a partially-constructed snapshot.

Subtleties¶

• Memory model edge is per-atomic-variable. A store to one atomic.Pointer does not synchronize with a load from another.
• Non-atomic accesses inside the snapshot. Once the snapshot is published, readers access its fields with plain (non-atomic) loads. This is safe only because the snapshot is immutable — readers and writers do not race on its fields.
• Sequential consistency is stronger than acquire/release. Other languages (C++, Rust) expose finer-grained ordering. Go chose simplicity.
• The cost. Sequential consistency requires more synchronization at the hardware level — typically an MFENCE or equivalent before atomic stores on x86, more on weaker architectures.

What the memory model does NOT guarantee¶

• Order of operations on different atomic variables. Two stores to two different atomic.Pointers may appear in different orders to different observers (no, wait — the SC guarantee says they appear in the same order to all observers; this is the strength of SC).
• Visibility without synchronization. A plain write to a shared variable has no happens-before with any read; the reader may see stale or torn values forever.
• Anything about timing. The memory model is about ordering, not real-time progress.

Inside sync/atomic.Pointer[T]¶

atomic.Pointer[T] is a generic wrapper. Let's look at how it is implemented.

Source¶

In the Go source (src/sync/atomic/type.go):

// A Pointer is an atomic pointer of type *T. The zero value is a nil *T.
type Pointer[T any] struct {
    _ [0]*T // for type signature checks
    _ noCopy
    v unsafe.Pointer
}

// Load atomically loads and returns the value stored in x.
func (x *Pointer[T]) Load() *T { return (*T)(LoadPointer(&x.v)) }

// Store atomically stores val into x.
func (x *Pointer[T]) Store(val *T) { StorePointer(&x.v, unsafe.Pointer(val)) }

// Swap atomically stores new into x and returns the previous value.
func (x *Pointer[T]) Swap(new *T) (old *T) { return (*T)(SwapPointer(&x.v, unsafe.Pointer(new))) }

// CompareAndSwap executes the compare-and-swap operation for x.
func (x *Pointer[T]) CompareAndSwap(old, new *T) (swapped bool) {
    return CompareAndSwapPointer(&x.v, unsafe.Pointer(old), unsafe.Pointer(new))
}

LoadPointer, StorePointer, SwapPointer, CompareAndSwapPointer are runtime intrinsics — the compiler recognises them and emits architecture-specific instructions.

Type safety¶

The [0]*T field is a clever trick. It is zero-sized at runtime but enforces type compatibility at compile time. Two Pointer[T] types with different T cannot be assigned to each other.

The noCopy field is checked by go vet to prevent accidental copying:

type noCopy struct{}

func (*noCopy) Lock()   {}
func (*noCopy) Unlock() {}

go vet flags struct copies whose fields have Lock/Unlock methods. This is how the vet checker catches var p atomic.Pointer[T] = q.p.

The intrinsics¶

runtime/internal/atomic defines the platform-specific operations. On amd64:

//go:noescape
func LoadPointer(ptr *unsafe.Pointer) unsafe.Pointer

The corresponding assembly (in runtime/internal/atomic/atomic_amd64.s):

TEXT ·LoadPointer(SB),NOSPLIT,$0-16
    MOVQ ptr+0(FP), AX
    MOVQ (AX), AX
    MOVQ AX, ret+8(FP)
    RET

A plain MOV instruction. On x86, an aligned 64-bit MOV is atomic and provides acquire semantics for free. No fence needed.

For Store:

TEXT ·StorePointer(SB),NOSPLIT,$0-16
    MOVQ ptr+0(FP), BX
    MOVQ val+8(FP), AX
    XCHGQ AX, 0(BX)
    RET

XCHGQ is used because it provides a full memory fence (sequential consistency). A plain MOV would suffice for x86 ordering but Go's memory model requires SC even on weaker architectures, so XCHG is the common choice.

Cost summary¶

Loads dominate in COW reads. Stores happen rarely. The asymmetry is exactly what makes COW efficient.

Why Pointer types are special¶

The GC must scan all pointers on the heap. Atomic operations on pointer types coordinate with the GC's write barrier (more on this later). Atomic operations on non-pointer types (Int32, Bool, etc.) do not need this coordination and use simpler implementations.

Inside sync/atomic.Value¶

atomic.Value predates generics. It stores an interface{}:

type Value struct {
    v any
}

But interface{} is two words (type pointer + data pointer). Storing two words atomically is hardware-dependent. The implementation uses a careful protocol.

The implementation strategy¶

type efaceWords struct {
    typ  unsafe.Pointer
    data unsafe.Pointer
}

func (v *Value) Load() (val any) {
    vp := (*efaceWords)(unsafe.Pointer(v))
    typ := LoadPointer(&vp.typ)
    if typ == nil || typ == unsafe.Pointer(&firstStoreInProgress) {
        return nil
    }
    data := LoadPointer(&vp.data)
    vlp := (*efaceWords)(unsafe.Pointer(&val))
    vlp.typ = typ
    vlp.data = data
    return
}

The Load reads the type word first. If it's nil (initial state) or &firstStoreInProgress (a sentinel during the very first store), no value is available.

The Store is more complex. The first Store uses a CAS to install the type word, then writes the data word. Subsequent Stores write the data word atomically, having first verified the type matches:

func (v *Value) Store(val any) {
    if val == nil {
        panic("sync/atomic: store of nil value into Value")
    }
    vp := (*efaceWords)(unsafe.Pointer(v))
    vlp := (*efaceWords)(unsafe.Pointer(&val))
    for {
        typ := LoadPointer(&vp.typ)
        if typ == nil {
            // First store; CAS in the type word
            runtime_procPin()
            if !CompareAndSwapPointer(&vp.typ, nil, unsafe.Pointer(&firstStoreInProgress)) {
                runtime_procUnpin()
                continue
            }
            StorePointer(&vp.data, vlp.data)
            StorePointer(&vp.typ, vlp.typ)
            runtime_procUnpin()
            return
        }
        if typ == unsafe.Pointer(&firstStoreInProgress) {
            continue
        }
        if typ != vlp.typ {
            panic("sync/atomic: store of inconsistently typed value into Value")
        }
        StorePointer(&vp.data, vlp.data)
        return
    }
}

Key observations:

• The first store CASes a sentinel into the type word, then stores the data, then stores the real type. Loaders that see the sentinel retry.
• runtime_procPin() pins the goroutine to its M to prevent preemption during the first-store protocol — without this, a preempted goroutine could leave the value in an inconsistent state observable by another goroutine.
• Subsequent stores require the type to match. Mismatched types panic.

Why atomic.Pointer[T] is faster¶

atomic.Pointer[T] stores a single word (the pointer). One MOV (Load) or one XCHG (Store). No protocol, no sentinel, no pinning, no panic risk.

atomic.Value stores an interface, which is two words. The protocol adds overhead. The type check (and potential panic) adds risk.

Benchmark:

BenchmarkAtomicValueLoad-8     250000000          5.5 ns/op
BenchmarkAtomicPointerLoad-8   500000000          1.6 ns/op

BenchmarkAtomicValueStore-8     50000000         25.0 ns/op
BenchmarkAtomicPointerStore-8  150000000          7.5 ns/op

3–4× difference. For new code on Go 1.19+, always use atomic.Pointer[T].

Codegen Across Architectures¶

The Go compiler generates different instructions for atomic operations depending on target architecture.

amd64 (x86-64)¶

Strong memory model. Loads and stores of aligned 64-bit values are atomic by hardware. The compiler emits:

• Load: plain MOVQ.
• Store: XCHGQ (for the full-fence sequential consistency requirement).
• CompareAndSwap: LOCK CMPXCHG.

ARM64¶

Weaker memory model. The compiler uses load-acquire and store-release instructions:

• Load: LDAR (load-acquire register).
• Store: STLR (store-release register).
• CompareAndSwap: CAS (Go 1.20+ when the host supports the LSE extension) or an LL/SC loop with LDAXR/STLXR.

These instructions ensure ordering with respect to other memory operations but are slightly more expensive than plain MOV.

riscv64¶

Weak memory model. Uses LR.W/SC.W (load-reserved / store-conditional) for atomics. Memory fences via FENCE instructions.

arm (32-bit)¶

Older ARM lacks atomic 64-bit operations in some configurations. Go falls back to using locks for 64-bit atomics on these targets. Performance is much worse — avoid 32-bit ARM if you can.

Why this matters¶

For COW, the implication is:

• On x86, COW Load is extremely cheap — basically free.
• On ARM64, slightly more expensive but still fast.
• On older ARM, atomic costs are dominated by lock overhead — measure carefully.

You usually do not target older ARM. But knowing the difference helps explain why benchmarks vary across machines.

Inspecting codegen¶

To see the actual assembly:

go build -gcflags '-S' your.go 2>&1 | grep -A 20 'CALL.*Load'

Or use the playground's "Show Assembly" feature. For atomic.Pointer.Load, you should see a single MOV (on amd64) inlined into the caller.

Memory Ordering Primitives¶

Beyond Go's sequential consistency, hardware exposes finer ordering. Understanding these helps explain costs.

Memory barriers¶

• Load fence (LFENCE on x86): all earlier loads complete before later loads.
• Store fence (SFENCE): all earlier stores complete before later stores.
• Full fence (MFENCE): all earlier operations complete before later operations.

x86's strong model means LFENCE and SFENCE are largely unnecessary (loads and stores are naturally ordered relative to themselves). MFENCE is needed for store-to-load ordering, which x86 does not guarantee by default.

Acquire-release semantics¶

• Acquire: a load that becomes a happens-before edge from any store that happens-before-it.
• Release: a store that establishes happens-before to any later acquire-load of the same location.

This is what C++ memory_order_acquire / memory_order_release express. Go does not expose these — every atomic in Go is sequentially consistent.

For COW publication, acquire-release would suffice: - Writer's Store needs release semantics so prior writes (snapshot construction) are visible. - Reader's Load needs acquire semantics so subsequent reads (snapshot fields) see the published state.

Sequential consistency is strictly stronger than acquire-release. Go pays the small extra cost in exchange for simplicity.

Happens-before vs synchronizes-with¶

The Go memory model uses "synchronized before" (capital S) — synonymous with happens-before for our purposes. The C++ memory model uses "synchronizes with" for the inter-thread relation and "happens before" for the combined relation.

For COW purposes, the distinction is academic. The important fact: atomic Load and Store create an ordering edge that orders all non-atomic memory accesses on either side.

GC Interaction With Snapshots¶

The garbage collector's role in COW is what makes the pattern practical in Go. Understanding the interaction is critical.

Reachability tracing¶

Go's GC is a tricolor mark-and-sweep. It traces from roots (globals, stacks, etc.) through reachable pointers, marking everything live. Anything unreachable is swept.

In a COW system, the live snapshots are:

• The current snapshot (reachable from atomic.Pointer[T]).
• Any snapshot held in a local variable of a running goroutine.
• Any snapshot referenced from another live object (closures, channels, etc.).

Old snapshots become unreachable as soon as no live reference exists. The GC reclaims them on the next cycle.

Write barriers¶

When the writer does ptr.Store(next), the GC must learn that next is now reachable from a root. This is the job of the write barrier.

A write barrier is a small piece of code the compiler inserts around every pointer write. In Go's hybrid concurrent collector, it works (simplified):

// Before:
ptr = next

// With write barrier (conceptually):
oldPtr := ptr
ptr = next
gcWriteBarrier(oldPtr, next)

gcWriteBarrier informs the GC that next is now reachable (and oldPtr may have been freed if it was the last reference).

For atomic.Pointer[T].Store, the write barrier is woven into the atomic operation. The runtime ensures that the GC sees the new pointer atomically with the write.

GC during a COW publish¶

A snapshot publish is one atomic Store. During the Store:

• The new snapshot pointer becomes the value of atomic.Pointer.v.
• The write barrier marks the new snapshot as reachable from the atomic pointer.
• The old snapshot is no longer reachable through this pointer (other references may exist).

The Store completes in nanoseconds. The GC may run concurrently — it tracks the pointer change via the write barrier, even if the mark phase is in progress.

When the GC runs¶

Go's GC is triggered by heap growth. With GOGC=100, it runs whenever the heap doubles since last GC. For a COW system with 5 MB live heap and rapid writes producing garbage, the GC may run every few hundred milliseconds.

GC pauses (stop-the-world) are typically <1 ms for heaps under a few GB. The hybrid concurrent collector keeps pauses short by doing most work concurrently with goroutine execution.

Snapshot pinning and GC¶

A long-lived goroutine holding a snapshot pointer pins that snapshot. The GC cannot reclaim it as long as the goroutine is alive and its stack contains the reference.

Stacks are precisely scanned: the GC knows exactly which slots contain pointers vs scalars. A local variable holding *Snapshot is a pointer; the GC sees it.

After the variable is re-assigned or the function returns, the reference is gone. The next GC cycle reclaims the snapshot if no other references exist.

Soft memory limits¶

Go 1.19+ supports a soft memory limit:

debug.SetMemoryLimit(1 << 30) // 1 GiB

When live heap approaches the limit, the GC runs more aggressively. For COW systems with bursty writes that may pin many snapshots simultaneously, this can prevent OOM.

Final note on reachability¶

Reachability is exact — no false positives. If a snapshot is unreachable, the GC will eventually reclaim it. Memory leaks in Go COW systems are reachability bugs: somewhere, a path from a root to the old snapshot still exists, usually through a long-lived data structure or goroutine.

Write Barriers and Pointer Writes¶

Go's write barrier deserves a closer look because it affects atomic pointer performance.

What it is¶

The write barrier is a function the compiler inserts at every pointer write to a heap object. Its purpose: maintain the GC's invariants during concurrent marking.

In Go's hybrid concurrent collector, the write barrier is needed only during the marking phase. Outside of marking (most of the time), pointer writes proceed without the barrier.

Cost¶

A typical pointer write with the write barrier active costs ~10-30 ns. Without the barrier (most of the time), it's a few ns.

For atomic.Pointer.Store, the cost is dominated by the atomic instruction itself (~10 ns) plus the conditional write barrier overhead. Net: ~10-30 ns per store.

When the barrier fires¶

The barrier checks a global flag (writeBarrier.enabled). When false (mutator phase), the barrier is a no-op. When true (concurrent marking), the barrier records the pointer write so the GC can update its mark bits.

The atomic.Store codegen includes the barrier check:

TEXT runtime/internal/atomic.StorePointer(SB)
    // ... atomic store
    CMPB writeBarrier.enabled, $0
    JEQ done
    CALL gcWriteBarrier
done:
    RET

The check is one byte-load and one branch — essentially free unless the barrier is active.

Implications for COW¶

• Atomic stores are not always 10 ns; they may spike to 30-50 ns during GC.
• High-frequency COW writes during GC can prolong the marking phase.
• For latency-sensitive systems, monitor GC overlap with write bursts.

runtime.GC immediately after a publish¶

A pattern in deterministic-latency systems:

cur.Store(next)
runtime.GC() // force the old snapshot's reclamation

This is rarely worth the cost (~ms per runtime.GC). Use only when you absolutely need the old snapshot reclaimed immediately.

Escape Analysis and Snapshots¶

Escape analysis decides whether a value lives on the stack or the heap. For COW, snapshots usually escape — but understanding when and why illuminates the pattern.

When a snapshot escapes¶

A value escapes if its lifetime exceeds the function that created it. For COW writers:

func Update() {
    next := *cur.Load()  // (1) shallow copy on the stack initially
    next.Field = newVal  // (2) mutate stack value
    cur.Store(&next)     // (3) escape! address taken and stored to a heap-reachable location
}

After (3), next must live on the heap because its address is stored in cur, which is reachable from elsewhere.

The compiler detects this and allocates next on the heap from the start. Build with -gcflags '-m' to see escape decisions:

./main.go:42:6: moved to heap: next

When a snapshot does not escape¶

If you build a "snapshot" but never publish it (e.g., for use within a single function), it can stay on the stack:

func computeOnce() Value {
    temp := Snapshot{...}  // never escapes
    return temp.Field      // returned value escapes; temp doesn't
}

This is rare for production COW code. Almost every snapshot is published, hence escapes.

Cost¶

Stack allocations are essentially free. Heap allocations cost ~10 ns each, plus future GC work.

For COW writers, heap allocations are unavoidable. The cost is amortized over the snapshot's lifetime.

Pre-allocation tricks¶

You can pre-allocate snapshots and reuse them via sync.Pool, but only if the old snapshot is no longer reachable. This is hard to guarantee correctly — readers may still hold references.

The pragmatic answer: let the GC handle reclamation. Pre-allocation is a niche optimization.

Cache-Line Effects¶

Modern CPUs work in 64-byte cache lines. Memory access patterns affect performance enormously through caching.

Snapshot pointer location¶

The atomic.Pointer.v field is one word (8 bytes). It sits in a cache line with other fields of its containing struct.

If the containing struct has many fields, the atomic pointer shares a cache line with them. Writing to those fields invalidates the cache line for all readers of the atomic pointer.

type Store struct {
    cur     atomic.Pointer[Config]  // hot
    mu      sync.Mutex               // hot during writes
    updates atomic.Int64             // hot
    created time.Time                // cold
}

If cur, mu, and updates share a cache line, a single write to updates invalidates the line that readers loading cur need. Readers stall on cache misses.

Cache-line padding¶

To isolate the atomic pointer:

type Store struct {
    cur atomic.Pointer[Config]
    _   [56]byte // pad to 64 bytes
    mu  sync.Mutex
    // ...
}

The padding ensures cur lives in its own cache line. Reads do not contend with writes to other fields.

When padding matters¶

• High-contention COW systems with many readers and writes from other goroutines.
• Multi-socket NUMA systems where cache-line ping-pong is expensive.

For most Go services with moderate read rates, padding is overkill. Measure before applying.

Cache locality of the snapshot¶

The snapshot itself benefits from locality. A compact struct with frequently-accessed fields near each other reads faster than a sparse one:

// Good: hot fields together
type Config struct {
    Timeout time.Duration
    MaxConns int
    LogLevel string
    // ... cold fields below
    Description string
    OperatorEmail string
}

Putting Description first means every Load + Read accesses a different cache line than the hot fields.

Cache pressure on reads¶

A read of cur.Load() + .SomeField touches at most 2 cache lines (the atomic pointer, and the snapshot's hot region). Each is 64 bytes. 128 bytes of cache used per logical read.

At 1 M reads/sec, you touch 128 MB/sec of cache footprint — well within L1/L2.

If the snapshot is huge (10 MB), most reads touch only the hot prefix. The cold parts age out of cache between accesses.

False Sharing in COW Systems¶

False sharing happens when unrelated data shares a cache line and writes to one part invalidate the line for readers of another.

Classic example¶

type counters struct {
    a atomic.Int64
    b atomic.Int64
}

a and b likely share a cache line. A writer incrementing a invalidates the cache line for any reader of b. Even though the data is independent, the CPU sees the line as contended.

In COW¶

type Store struct {
    cur atomic.Pointer[T]
    mu  sync.Mutex
}

cur and mu may share a cache line. The writer locks mu (writing to its internal state), invalidating the line that contains cur. Readers of cur then experience cache misses.

For most workloads this is unmeasurable. For 1 M reads/sec across many cores with active writers, it can add noticeable latency.

Mitigation¶

Pad to separate cache lines:

type Store struct {
    cur atomic.Pointer[T]
    _   [56]byte // padding
    mu  sync.Mutex
}

64 bytes minus the 8-byte pointer = 56 bytes of padding.

Go provides runtime.NumCPU() and you can derive the line size with platform-specific knowledge. The constant is typically 64 on x86 and 128 on some ARM.

Measurement¶

Use perf (Linux) or Intel VTune (cross-platform) to measure cache misses. In Go, look for runtime.MemStats.NumGC and runtime.ReadMemStats for indirect signals.

The simpler test: benchmark with and without padding. If padding helps, you had false sharing.

RCU in the Linux Kernel Detail¶

RCU in the Linux kernel is the gold-standard implementation of COW-style patterns. Studying it deepens understanding.

The RCU API¶

// Reader:
rcu_read_lock();
ptr = rcu_dereference(global_ptr);
use(ptr->field);
rcu_read_unlock();

// Writer:
new = build_new();
old = global_ptr;
rcu_assign_pointer(global_ptr, new);
synchronize_rcu();  // wait for grace period
kfree(old);

rcu_read_lock and rcu_read_unlock are usually no-ops (in the default RCU "preemptible" mode they only disable preemption). They mark "I am in a critical section reading the structure."

rcu_dereference loads the pointer with the appropriate memory barrier.

rcu_assign_pointer stores the new pointer with the appropriate memory barrier.

synchronize_rcu waits for a grace period — the point at which all readers that were active when the writer published are guaranteed to have finished.

Grace period detection¶

The kernel knows a CPU has finished any reading critical section by observing it pass through a "quiescent state":

• Voluntary context switch.
• Returning to user mode.
• Idle.

Once every CPU has passed through a quiescent state since the publish, the writer can safely free the old structure.

Why Go is simpler¶

In Go, the equivalent of synchronize_rcu is "wait for the GC to reclaim it." But you don't wait explicitly — the GC handles it.

The trade-off: Go's GC has more overhead than the kernel's RCU but is much easier to use. For most workloads, Go's approach is preferable. For the highest-performance kernel code, manual RCU wins.

Lessons applicable to Go¶

• The notion of a "reader critical section" maps to "the lifetime of a Go variable holding the snapshot pointer."
• The notion of "grace period" maps to "GC cycle that proves no goroutine references the old snapshot."
• The kernel's rcu_dereference corresponds to Go's atomic.Pointer.Load.

Understanding the kernel's discipline can guide Go code: keep reader critical sections short; don't pin snapshots across long operations.

Hazard Pointers and Epoch-Based Reclamation¶

For systems where the GC's reclamation is insufficient — typically because you must close a resource as soon as it's no longer in use — there are two manual techniques.

Hazard pointers¶

Each thread publishes a "hazard pointer": the pointer it is currently reading. Before reclaiming, the writer checks all hazard pointers; if any matches the pointer to reclaim, wait.

var hazards [N]atomic.Pointer[Snapshot]

// Reader:
func Read(id int) *Snapshot {
    for {
        p := global.Load()
        hazards[id].Store(p)
        // double-check
        if global.Load() == p {
            return p
        }
    }
}

// Writer:
func Publish(next *Snapshot) {
    old := global.Swap(next)
    for {
        safe := true
        for _, h := range hazards {
            if h.Load() == old {
                safe = false
                break
            }
        }
        if safe { break }
        runtime.Gosched()
    }
    old.Free()
}

Hazard pointers give deterministic reclamation but add complexity.

Epoch-based reclamation (EBR)¶

Threads operate within "epochs" that advance globally. Reclamation defers until all threads have advanced past the epoch of the old data.

type Epoch struct {
    global atomic.Int64
    local  [N]atomic.Int64
}

func (e *Epoch) Enter(id int) {
    e.local[id].Store(e.global.Load())
}

func (e *Epoch) Exit(id int) {
    e.local[id].Store(-1)
}

func (e *Epoch) Reclaim(g int64, fn func()) {
    for {
        safe := true
        for i := 0; i < N; i++ {
            le := e.local[i].Load()
            if le != -1 && le <= g {
                safe = false
                break
            }
        }
        if safe {
            fn()
            return
        }
        runtime.Gosched()
    }
}

Less per-thread overhead than hazard pointers, but more global synchronization.

When to use either in Go¶

Almost never. The Go GC is suitable for 99% of cases. Reach for hazard pointers or EBR only when:

• You're integrating with non-Go code that requires deterministic resource management.
• You're writing a Go runtime extension.
• You're benchmarking and the GC's overhead is provably unacceptable.

For application-level COW, trust the GC.

Lock-Free Programming Subtleties¶

Some COW designs venture into lock-free territory. The subtleties:

The ABA problem¶

Pointer A is replaced by B, then back to A. A CAS comparing the current pointer to A succeeds incorrectly — the structure has changed even though the pointer matches.

In Go, ABA is essentially impossible because every &next allocates a fresh pointer (the GC doesn't reuse pointers while they're reachable). Each snapshot has a unique identity throughout its lifetime.

In C, ABA is a constant concern, addressed by version-stamped pointers or hazard pointers.

Memory reuse¶

C systems may reuse freed memory immediately. A reader holding a "freed" pointer may suddenly find unrelated data there. Hazard pointers / EBR prevent this.

Go avoids this entirely: a freed pointer cannot be reused while any reader holds it (GC reachability ensures this).

CAS retry loops¶

A CAS loop with N writers and contention causes average N retries per write. Total work = N² operations. Watch for this in benchmarks.

Liveness¶

Lock-free does not mean wait-free. A CAS loop can theoretically retry forever under starvation. In practice, hardware bounds this, but pathological cases exist.

Linearizability¶

A linearizable operation appears to take effect at a single instant between invocation and response. atomic.Pointer.Store is linearizable. A sequence of Load + non-atomic field access is not linearizable — the field access happens after the Load.

For COW, this means: the publish is linearizable, but the reader's full operation (Load + traverse) is not. The reader may see a "stale" snapshot relative to wall-clock time. This is intentional and acceptable for the COW pattern.

Weak References and Snapshot Caches¶

Go 1.24+ introduces weak references via runtime/weak. They enable snapshot-aware caches without preventing GC.

The problem they solve¶

A cache keyed on *Snapshot keeps the snapshot alive:

var cache map[*Snapshot]Result

Even after a new snapshot is published, the old one remains alive because cache references it. Memory grows.

Weak references¶

import "weak"

var cache map[weak.Pointer[Snapshot]]Result

A weak pointer does not keep the target alive. When the GC determines the target is otherwise unreachable, the weak pointer is "cleared" — calling .Value() returns nil.

For snapshot caches, this allows entries to be reclaimed automatically when their snapshot is no longer current.

Caveats¶

• Weak references add a small overhead per access.
• Not all GC operations finalize weak references immediately; there may be a one-cycle delay.
• The API is new; expect refinements.

For most COW caches, plain caches with explicit eviction work fine. Weak references are an option to keep in mind for memory-sensitive scenarios.

unsafe.Pointer for Advanced Cases¶

Most COW code does not need unsafe.Pointer. A few situations warrant it.

Case 1: Pre-Go-1.19 codebases¶

atomic.LoadPointer and atomic.StorePointer operate on unsafe.Pointer. If you support pre-generic Go, you use them directly:

var p unsafe.Pointer // points to *Config

func Load() *Config {
    return (*Config)(atomic.LoadPointer(&p))
}

func Store(c *Config) {
    atomic.StorePointer(&p, unsafe.Pointer(c))
}

Verbose and type-unsafe. Migrate to atomic.Pointer[T] as soon as possible.

Case 2: Type-erased snapshots¶

A library that handles snapshots of arbitrary type without using generics:

type Store struct {
    v unsafe.Pointer
}

func (s *Store) Load() unsafe.Pointer { return atomic.LoadPointer(&s.v) }
func (s *Store) Store(p unsafe.Pointer) { atomic.StorePointer(&s.v, p) }

Callers cast to/from concrete types. Lots of opportunity for bugs.

Case 3: Interfacing with C via cgo¶

If you must share state with C code that reads/writes the pointer, unsafe.Pointer is the only way.

Case 4: SeqLock-like protocols¶

Some lock-free designs need to read multiple words atomically. Go does not have 128-bit atomic types, so you may use unsafe for layout control.

General advice¶

Avoid unsafe.Pointer in COW code. The type-safe atomic.Pointer[T] is sufficient for 99% of cases. When you must use unsafe, isolate it to one package and document heavily.

Assembly-Level Considerations¶

For the curious, here is what atomic.Pointer.Load looks like at the assembly level on amd64.

Source¶

func (x *Pointer[T]) Load() *T { return (*T)(LoadPointer(&x.v)) }

Compiled (simplified)¶

TEXT runtime/atomic.LoadPointer(SB), NOSPLIT, $0-16
    MOVQ ptr+0(FP), AX      ; load argument (pointer to atomic.Pointer.v)
    MOVQ (AX), AX           ; dereference; atomic on aligned 64-bit
    MOVQ AX, ret+8(FP)      ; return value
    RET

A single MOVQ does the work. The x86 memory model guarantees this is atomic for aligned 8-byte accesses.

Compiled (with full SC semantics for amd64)¶

The runtime ensures the load happens before any later non-atomic loads. On amd64, this is implicit (TSO memory model). No fences needed.

On ARM64¶

TEXT runtime/atomic.LoadPointer(SB), NOSPLIT, $0-16
    MOVD ptr+0(FP), R0
    LDAR R0, R0             ; load-acquire register
    MOVD R0, ret+8(FP)
    RET

LDAR (load-acquire register) is the ARM64 load-acquire instruction. It costs slightly more than a plain LDR but provides the needed ordering.

Performance¶

For COW, the L1-cache-hit path is what you optimize for. Hot snapshot pointers stay in L1; cold ones pay the miss penalty.

Profiling Lock-Free COW¶

Profiling lock-free systems requires different tools than profiling lock-based ones.

pprof mutex profile¶

runtime.SetMutexProfileFraction(1)

Captures contention on sync.Mutex and sync.RWMutex. For COW with a writer mutex, this shows time spent waiting on the writer mutex.

pprof block profile¶

runtime.SetBlockProfileRate(1)

Captures goroutine blocking (channel send/recv, mutex Lock, etc.). Useful for finding subscribers stuck on channel reads.

Goroutine profile¶

curl http://localhost:6060/debug/pprof/goroutine?debug=2

Stack traces for all live goroutines. Useful for finding pinned snapshots and stuck readers.

Heap profile¶

curl http://localhost:6060/debug/pprof/heap

Allocations by call site. Find write-heavy code paths.

Trace¶

curl http://localhost:6060/debug/pprof/trace?seconds=10

Full goroutine and GC trace. Visualize with go tool trace. Shows GC pauses, write barrier activity, and goroutine scheduling.

Custom metrics¶

Embed counters in the COW store:

type Store struct {
    loads  atomic.Int64
    stores atomic.Int64
}

Emit periodically to your metrics backend.

runtime.GoroutineProfile¶

Programmatic access to goroutine info. Tag goroutines with pprof.Labels to identify snapshot holders.

ctx = pprof.WithLabels(ctx, pprof.Labels("snapshot", fmt.Sprintf("v%d", snap.Version)))
pprof.SetGoroutineLabels(ctx)

Later, pprof.Lookup("goroutine") shows each goroutine's snapshot version.

Correctness Proofs and Race Conditions¶

For high-assurance code, formal reasoning helps.

The publication invariant¶

A COW snapshot is correctly published if:

1. Every field of the snapshot is initialized before Store.
2. No field is modified after Store.

The Go memory model guarantees:

• Writes to the snapshot's fields (in the writer goroutine) happen-before the Store.
• The Store happens-before the reader's Load of the same value.
• The reader's Load happens-before its access of the snapshot's fields.

Transitively: writes happen-before reads. The snapshot is consistently visible.

The mutation invariant¶

If the snapshot is mutated after Store, the invariant breaks. Readers may see partial mutations because there is no happens-before edge between the mutation and the reads.

This is why "never mutate a published snapshot" is the central rule. The race detector catches violations.

The writer serialization invariant¶

If two writers concurrently Store based on the same loaded snapshot, one of their updates is lost. Even if both writes are atomic, the read-modify-write sequence is not.

The fix: writer mutex (serializes the entire RMW) or CAS loop (retries on conflict).

Linearizability of atomic.Pointer.Store¶

atomic.Pointer.Store is linearizable: it appears to take effect at a single instant. Two concurrent Stores have a well-defined order: the second observes the first's effect.

The reader's Load is linearizable: it sees the value as of the moment it executed.

The combined operation Load + read field is not linearizable — the field read happens at some moment after the Load. But this is acceptable for COW because the snapshot is immutable after publication.

Common race conditions¶

1. Mutated snapshot. Writer modifies fields after Store.
2. Aliased slice/map. Writer's next.Slice shares backing with old.Slice; next is published; writer appends.
3. Lost update. Two writers race; one's Store overwrites the other.
4. Stale read. Reader loads at T1; writer publishes at T2 > T1; reader proceeds with stale snapshot. Often not a bug — snapshot is intended to be stable. Bug only if business logic assumes freshness.
5. Snapshot leak. Long-lived goroutine holds snapshot; new snapshots are also retained because the old chain is reachable.

The race detector catches 1, 2, and 3 reliably. 4 is by design. 5 requires heap profiling.

Designing for Hardware¶

Production COW for the highest-performance use cases requires hardware awareness.

NUMA¶

On multi-socket systems, memory access is faster within a NUMA node than across. The current snapshot's pointer location and the snapshot's data may be in different nodes.

Mitigation: pin the writer to one node; readers on the same node have fast access. Cross-node readers pay extra latency.

Go's runtime is not NUMA-aware by default. For extreme performance, you may need to launch one COW system per NUMA node.

Cache-line size¶

x86 and ARM64 are 64 bytes. Some platforms are 128. Align hot structures accordingly.

Branch prediction¶

atomic.Pointer.Store includes a write-barrier check. The check almost always falls through (the barrier is off most of the time), so the branch is well-predicted. Don't try to "optimize" by removing it — you'd be doing the runtime's job, badly.

TLB pressure¶

Very large snapshots (> tens of MB) may stress the TLB. Modern CPUs handle this with huge pages, but Go applications usually do not use huge pages.

For most COW systems this is negligible.

Cache coherence protocols¶

MESI / MOESI / MESIF determine how cache lines transit between cores. Heavily-shared read-only lines (like the snapshot pointer) settle into "Shared" state across many cores with no further coherence traffic. Writers must transition the line to "Modified" / "Exclusive", briefly stalling readers.

A COW writer that publishes 1000 times per second invalidates the cache line 1000 times per second. With 64 cores each reading the line, that's 64 000 cache misses per second. Still tiny in absolute terms (microseconds total), but noticeable in some benchmarks.

Self-Assessment¶

A professional-level engineer should be able to answer:

• Describe the Go memory model's happens-before relation and how it applies to COW.
• Explain the difference between atomic.Pointer[T].Load and atomic.Value.Load at the instruction level.
• Walk through the codegen for atomic.Pointer.Store on amd64 vs arm64.
• Explain how the GC's write barrier interacts with atomic.Pointer.Store.
• Describe what happens during a GC cycle when many snapshots are pinned by in-flight readers.
• Identify a false-sharing problem in a COW store and apply padding.
• Compare Go's GC-based reclamation with the Linux kernel's RCU.
• Explain when hazard pointers or EBR might be needed in Go.
• Describe the ABA problem and why it does not occur in Go COW.
• Use pprof mutex and block profiles to debug a contended COW system.
• Read and explain the runtime source for atomic.Pointer[T].

If you can do all of these, you have professional-level mastery.

Summary¶

At the professional level, COW becomes a question of runtime mechanics. You understand the memory model that makes atomic.Pointer[T].Load correct without a lock. You can read the codegen and explain why it costs what it costs on different architectures. You understand the GC's role in reclamation and the write barrier's cost. You know when to reach for hazard pointers or weak references and when the GC's automatic reclamation suffices.

This file completes the COW curriculum. The remaining files in this sub-section (specification, interview, tasks, find-bug, optimize) are reference material applying the knowledge built across all four levels.

Appendix: Reading the Runtime Source¶

A useful exercise: read the runtime source for atomic.Pointer[T]. Files:

• src/sync/atomic/type.go — the public API.
• src/sync/atomic/doc.go — documentation.
• src/runtime/internal/atomic/atomic_amd64.s — amd64 implementation.
• src/runtime/internal/atomic/atomic_arm64.s — arm64 implementation.
• src/runtime/mbarrier.go — write barrier.
• src/runtime/mgcmark.go — GC marking.

Tracing a single atomic.Pointer[Config].Store(c) from source to instruction:

1. Pointer[T].Store(val *T) calls StorePointer(&x.v, unsafe.Pointer(val)).
2. StorePointer is a runtime intrinsic. The compiler recognizes it and emits the architecture-specific assembly.
3. On amd64, this is a single XCHGQ (with implicit lock prefix for fence semantics).
4. Before the XCHG, the write barrier check fires. If GC is in concurrent marking, it calls gcWriteBarrier.
5. The XCHG completes; the store is visible to all CPUs.

End-to-end: 5-15 ns depending on GC state and cache. For a system shipping millions of stores per day, this is fast enough that the rest of the system dominates.

Appendix: A Formal Look at Sequential Consistency¶

Sequential consistency (SC) is the strongest practical memory model. Formally, an execution is sequentially consistent if there exists a total order on all atomic operations such that:

1. The total order is consistent with each goroutine's program order.
2. Each atomic load returns the value of the most recent (in the total order) atomic store to the same variable.

For Go, every atomic operation participates in this total order. Non-atomic operations do not — they are ordered only by happens-before edges established by atomic operations.

Why SC is enough for COW¶

Consider two writers and one reader:

Writer A:                Writer B:                Reader:
  build snapA             build snapB              load ptr
  Store(ptr, snapA)       Store(ptr, snapB)        use(snap.field)

SC says there's a total order on the two Stores and the one Load. Cases:

• Order: A's Store, B's Store, R's Load. Reader sees snapB.
• Order: A's Store, R's Load, B's Store. Reader sees snapA.
• Order: B's Store, A's Store, R's Load. Reader sees snapA.
• Order: B's Store, R's Load, A's Store. Reader sees snapB.
• Order: R's Load, A's Store, B's Store. Reader sees whatever was stored before (initial value).
• Order: R's Load, B's Store, A's Store. Reader sees initial value.

In every case, the reader sees a single, fully-constructed snapshot. There is no case where the reader sees a half-built snapshot.

The reader's subsequent field accesses, while not atomic, are ordered after the Load by program order. The snapshot's fields were written before its Store (program order in writer). Combined, every field access sees the correctly-written value.

This is the formal proof of COW's correctness.

Appendix: GC Pause Analysis¶

Modern Go GC pauses are very short, but understanding their composition matters.

A GC cycle has phases:

1. STW start (microseconds). Stop all goroutines briefly to set up.
2. Concurrent mark (milliseconds-seconds). GC and goroutines run together; goroutines pay the write barrier cost.
3. STW mark termination (microseconds). Finalize marking.
4. Concurrent sweep (background). Free unreachable memory.

For COW: - Phase 2 is when the write barrier is active. Atomic Stores cost slightly more. - Phase 4 reclaims old snapshots.

Tuning levers: - GOGC: higher value = less frequent GC, more memory used. - GOMEMLIMIT: cap heap; GC more aggressive near the limit. - Pacing: GC tries to balance allocation rate with reclaim rate.

For COW systems with bursty writes (e.g., a deploy that triggers many config reloads), pausing GC briefly to handle the burst can be done with debug.SetGCPercent(-1) (disable) ... but rarely advisable.

Appendix: When to Drop to Assembly¶

In 1 in 1000 cases, you may benefit from hand-written assembly for COW operations.

Scenarios: - A custom synchronization primitive not exposed by sync/atomic. - 128-bit atomic operations (Go has no native support). - Hardware-specific instructions (e.g., x86's CLFLUSH for cache control).

The Go assembler is documented in cmd/asm. Files end in .s and use Plan 9 syntax (different from gas).

For 99.9% of COW code, the standard library is sufficient. Reach for assembly only when profiling proves it necessary and reviewing engineers agree.

Appendix: Cross-Reference Tables¶

Mapping Go API to Hardware¶

Mapping COW Patterns to Memory Model Edges¶

Mapping Concerns to Tools¶

Final Professional-Level Synthesis¶

Copy-on-write at the professional level is the intersection of:

• The Go memory model.
• The Go runtime (atomic primitives, GC, write barriers).
• Architecture-specific codegen and hardware memory models.
• Low-level diagnostic tools (pprof, perf, trace).

A professional Go engineer treats COW as a transparent abstraction over these layers. They can debug a memory-leak bug by reading goroutine profiles. They can explain why an atomic.Pointer.Store costs more on ARM than on x86. They understand when the GC's reclamation is sufficient and when manual schemes are needed.

This depth is rarely needed in day-to-day work. But when a production issue surfaces — a mysterious latency spike, a heap that won't shrink, a benchmark that varies wildly across machines — the professional-level engineer is the one who finds the root cause.

The remaining files in this section (specification, interview, tasks, find-bug, optimize) build on this depth with reference material, practice problems, and bug-finding exercises. Use them to reinforce and apply what you've learned across all four levels.

Appendix: Glossary of Professional-Level Concepts¶

A professional engineer recognizes all of these concepts and their relevance to COW.

Closing Notes for Professional Level¶

This is the deepest layer of COW understanding. Below this lies hardware engineering, which is generally outside the Go engineer's purview.

The journey from junior to professional has been:

• Junior: the pattern, the API, the trivial mistakes.
• Middle: the engineering, the trade-offs, the production patterns.
• Senior: the algorithms, the architecture, the failure modes at scale.
• Professional: the substrate, the runtime, the formal model.

You now have the full picture. Use it judiciously. The right COW design is usually the simplest one that meets requirements; deeper knowledge informs when "simplest" doesn't suffice.

Production engineering rewards depth even when day-to-day code doesn't show it. The day a strange bug surfaces is the day this knowledge pays for itself.

Appendix: A Tour of the runtime/internal/atomic Package¶

For the truly curious, a tour of src/runtime/internal/atomic:

• atomic_amd64.s — x86-64 implementations.
• atomic_arm64.s — ARM64 implementations.
• atomic_mips64x.s, atomic_ppc64x.s, atomic_riscv64.s, atomic_s390x.s — other arches.
• types.go — the runtime's own atomic types (separate from sync/atomic).
• unaligned.go — fallbacks for unaligned access.

The package is internal to the runtime and not exposed to user code. But reading it teaches Go's implementation choices for atomic operations.

A particularly interesting file: atomic_amd64.go, which contains Go signatures with //go:noescape and //go:nosplit directives marking the intrinsics. The compiler intercepts these and substitutes inline assembly.

Appendix: Cross-Language Memory Model Comparison¶

Go's choice of SC for all atomics is friendlier to programmers but slightly more expensive than acquire-release. The trade-off is intentional: simplicity for correctness.

Appendix: References for Deep Study¶

• The Go Programming Language Specification: go.dev/ref/spec.
• The Go Memory Model: go.dev/ref/mem.
• The Go Programming Language (Donovan & Kernighan).
• Concurrent Programming in Go (Cox-Buday).
• Programming with POSIX Threads (Butenhof) — for portable concurrency.
• The Art of Multiprocessor Programming (Herlihy & Shavit).
• Is Parallel Programming Hard, And, If So, What Can You Do About It? (McKenney).
• Memory Models for C/C++ Programmers (Mazières lecture notes).
• "Hardware Memory Models" (Russ Cox).
• "Programming Language Memory Models" (Russ Cox).
• "Memory Models" essays at preshing.com.
• The Linux kernel RCU documentation.

The professional engineer has read most of these. The senior engineer has read at least half. The middle-level engineer has heard of them and can find what they need.

Final Note¶

Copy-on-write is one of the rare patterns where Go's design choices align perfectly with the problem. The atomic.Pointer[T] API is exactly the right tool. The garbage collector handles the hardest part for free. The memory model is strong enough to be intuitive.

This made it easy to ship COW code at the junior level. The middle level showed the engineering decisions. The senior level revealed the algorithmic depths. The professional level explained why all of this works.

A Go engineer who has internalized this material can deploy COW systems with confidence at any scale and debug them when they break. They know when to choose COW, when to reject it, and what to migrate to when its limits are reached.

That mastery is the goal of this curriculum.

Deep Dive: Implementing Your Own atomic.Pointer¶

To cement understanding, here is a from-scratch implementation of an atomic pointer type. This is for educational purposes; in production always use sync/atomic.Pointer[T].

Building blocks¶

package myatomic

import (
    "sync/atomic"
    "unsafe"
)

type Pointer[T any] struct {
    _ noCopy
    v unsafe.Pointer
}

type noCopy struct{}

func (*noCopy) Lock()   {}
func (*noCopy) Unlock() {}

func (p *Pointer[T]) Load() *T {
    return (*T)(atomic.LoadPointer(&p.v))
}

func (p *Pointer[T]) Store(val *T) {
    atomic.StorePointer(&p.v, unsafe.Pointer(val))
}

func (p *Pointer[T]) Swap(new *T) (old *T) {
    return (*T)(atomic.SwapPointer(&p.v, unsafe.Pointer(new)))
}

func (p *Pointer[T]) CompareAndSwap(old, new *T) bool {
    return atomic.CompareAndSwapPointer(&p.v, unsafe.Pointer(old), unsafe.Pointer(new))
}

This is essentially the source of the standard atomic.Pointer[T]. Our version cuts the [0]*T field, but the standard library uses it for an extra layer of type checking.

What we lose without the [0]*T field¶

type FastPointer[T any] struct {
    _ noCopy
    v unsafe.Pointer
}

var a FastPointer[int]
var b FastPointer[string]

// Without [0]*T, this might compile if we were sloppy:
// (it doesn't, because the generic types differ, but conceptually...)

The [0]*T field is a zero-sized marker that ensures different T types produce distinct generic instantiations. Without it, in some compilers, two instantiations might be mistakenly equated.

Testing the implementation¶

func TestMyAtomic(t *testing.T) {
    var p Pointer[int]
    a := 42
    p.Store(&a)
    if *p.Load() != 42 { t.Fatal("load") }
    b := 100
    p.Store(&b)
    if *p.Load() != 100 { t.Fatal("store2") }
    c := 200
    if !p.CompareAndSwap(&b, &c) { t.Fatal("CAS") }
    if *p.Load() != 200 { t.Fatal("CAS load") }
}

This works because we delegate to the runtime's atomic primitives. We added nothing; we just adapted the API.

Why we have generics now¶

Before generics, every COW user wrote unsafe.Pointer casts. The generic atomic.Pointer[T] is purely an ergonomic improvement; it has the same machine code at runtime.

Deep Dive: Tracing a COW Operation¶

Walk through a complete COW publish and load at the lowest level.

The setup¶

var cfg atomic.Pointer[Config]

type Config struct {
    Field int
}

func main() {
    c := &Config{Field: 42}
    cfg.Store(c)         // (1) Initial publish

    go func() {
        got := cfg.Load() // (2) Read by goroutine
        fmt.Println(got.Field)
    }()

    new := &Config{Field: 100}
    cfg.Store(new)        // (3) New publish
}

Step 1: Initial Store¶

The writer (main goroutine) executes cfg.Store(c).

1. Compiler emits a call to atomic.StorePointer(&cfg.v, unsafe.Pointer(c)).
2. On amd64, this becomes XCHGQ (with implicit lock prefix).
3. Before the XCHG, write barrier check: is GC marking? If yes, call gcWriteBarrier. (Usually no during program startup.)
4. The XCHG writes the pointer value of c into cfg.v. Atomically.
5. After: any goroutine that reads cfg.v sees the address of c.

The writer's view of memory after step 1: c lives on the heap (because its address is taken and stored to a heap-reachable atomic pointer). c.Field == 42.

Step 2: Goroutine creation¶

go func() { ... }() starts a new goroutine. The Go spec guarantees:

The go statement happens-before the start of the goroutine.

So all writes from main (including c.Field = 42 and cfg.Store(c)) are visible to the new goroutine.

Step 3: Reader Load¶

The new goroutine executes cfg.Load().

1. Compiler emits atomic.LoadPointer(&cfg.v).
2. On amd64: a plain MOVQ from cfg.v. (Memory model permits because x86 loads are acquire by default.)
3. Returns the pointer to c.
4. The goroutine then accesses got.Field — a plain (non-atomic) load. Reads 42.

How do we know Field == 42 and not, say, 0?

• Main wrote c.Field = 42 in program order before cfg.Store(c).
• cfg.Store(c) happens-before cfg.Load() (atomic synchronization).
• cfg.Load() happens-before got.Field access (program order).
• Transitively: c.Field = 42 happens-before got.Field access.

This is what makes COW correct.

Step 4: Second Store¶

Main executes cfg.Store(new).

1. Same as step 1: XCHGQ replaces cfg.v.
2. Write barrier may fire if GC is marking.
3. After: cfg.v points at new. The pointer to c is no longer held by cfg.

The goroutine that loaded c still holds it in its local variable got. From the GC's perspective, c is reachable until that goroutine finishes.

Step 5: GC reclamation¶

Eventually: - The goroutine finishes; got goes out of scope; c becomes unreachable. - Next GC cycle marks live heap; c is not visited; c is swept.

Memory reclaimed automatically.

Deep Dive: Atomic Operations Cost in Detail¶

The naive view: "atomic loads cost a nanosecond." Reality is richer.

On a quiet machine¶

BenchmarkLoadCold    ~50 ns/op  (cache miss to L3)
BenchmarkLoadL1Hit    ~1.5 ns/op
BenchmarkLoadL2Hit    ~5 ns/op
BenchmarkLoadL3Hit    ~20 ns/op
BenchmarkStore       ~10 ns/op  (XCHG)
BenchmarkCAS         ~15 ns/op  (LOCK CMPXCHG)

The cache state dominates. Reads of frequently-accessed pointers stay in L1; reads of cold pointers pay L2/L3/main memory latency.

Under contention¶

When many cores write the same cache line, the line bounces between cores. Each access pays the latency of cross-core coherence traffic.

For COW: the pointer is written rarely, so reads stay in L1 across many cores. This is the magic.

When a writer publishes, the line transitions to Modified on the writer's core; readers' L1 copies become Invalid. The next read on each reader core fetches the line — adding ~50 ns one-time cost per reader core per publish.

For a service with 64 cores and 1 publish/sec, this is ~3 µs/sec of cache-coherence work. Trivial.

For a service with 64 cores and 100 publishes/sec, it's ~300 µs/sec. Still trivial.

For a service with 64 cores and 100 000 publishes/sec, it's ~300 ms/sec — 30% CPU just on coherence. At this point your design is wrong.

MESI state machine¶

[Invalid] --read--> [Shared] --write by other--> [Invalid]
[Shared] --write by me--> [Modified]
[Modified] --read by other--> [Shared]

COW's optimization: keep the line in Shared as much as possible. Writes briefly invalidate it; reads restore Shared. The pattern stays efficient as long as writes are rare.

Per-architecture differences¶

ARM and RISC-V have weaker memory models. Atomic stores require explicit fences, which are slightly more expensive than x86's implicit ordering. But absolute costs are still in the nanosecond range.

For most Go services, the cross-architecture difference is in the noise. Optimize for clarity; let hardware variance be a footnote.

Deep Dive: GC Pauses and COW¶

Let's trace what happens to a COW system during a GC cycle.

Pre-GC¶

• Heap is at threshold (e.g., 200 MB after last GC + 100 MB allocation since).
• COW system has 1 current snapshot + a few pinned snapshots (in flight requests).
• Total snapshot memory: ~10 MB out of 200 MB live.

GC start (STW)¶

The runtime briefly stops all goroutines (microseconds) to set up. During this time: - COW reads cannot proceed. - COW writes are blocked.

Concurrent mark begins¶

GC starts tracing reachable objects from roots. While this runs: - Goroutines resume. - COW reads happen normally. - COW writes now invoke the write barrier on the atomic Store.

The write barrier records the new pointer write. The GC sees the new snapshot and marks it reachable.

Marking duration¶

For a 200 MB heap with 1 million pointers, marking takes ~50-100 ms wall time. During this time: - COW writes are slightly slower (write barrier active). - New allocations (from COW writes) are accounted by the GC's pacing algorithm.

Mark termination (STW)¶

A brief stop-the-world to finalize marking. Microseconds.

Concurrent sweep¶

Unreachable objects are reclaimed background. Old snapshots that became unreachable after the last GC are freed during this phase.

Visible impact¶

For a COW system: - One ~100 µs pause at GC start, one at mark termination. - Slightly higher write latency during marking. - New allocations (snapshot rebuilds) trigger the next GC cycle.

For most workloads this is invisible. For latency-sensitive systems, monitor runtime/metrics:

samples := []metrics.Sample{
    {Name: "/gc/pauses:seconds"},
    {Name: "/gc/cycles/automatic:gc-cycles"},
}

Spikes in pause time correlate with allocation-heavy moments.

Deep Dive: Atomic Operations Across Compilation¶

Let's see what a single line of Go compiles to. Take:

func GetTimeout() time.Duration {
    return cfg.Load().Timeout
}

Where cfg is atomic.Pointer[Config] and Config has a Timeout time.Duration field.

Go SSA IR (approximate)¶

v1 = AddrOf cfg.v
v2 = AtomicLoad64 v1
v3 = CastUnsafeToPointer v2
v4 = AddrOf <*Config>.Timeout from v3
v5 = Load v4
Return v5

amd64 codegen¶

TEXT GetTimeout(SB)
    LEAQ cfg+0(SB), AX      ; load address of cfg.v
    MOVQ (AX), BX           ; atomic load (aligned MOV is atomic on x86)
    MOVQ Timeout+24(BX), CX ; load Timeout field
    MOVQ CX, ret+0(FP)
    RET

Three loads. Total cost: ~5 ns (each load is 1-2 ns from L1).

Why so few instructions?¶

Several optimizations: - The Go compiler inlines small functions including Pointer.Load. - The Go compiler inlines field access. - The Go compiler skips redundant pointer arithmetic when offsets are constants.

The function does essentially zero overhead beyond the loads themselves.

How escape analysis affects this¶

cfg.Load() returns a *Config. If the function uses cfg.Load().Timeout directly, the *Config pointer never escapes the function — it's a stack-local reference. No allocation.

If you stored it: c := cfg.Load(); use(c), escape analysis might still find that c doesn't escape. Compiler optimizes.

Deep Dive: Common Hardware Footguns¶

Footgun 1: Unaligned access¶

Atomic operations require alignment to the operand size. atomic.Int64 on 32-bit ARM may be unaligned within a struct, causing crashes or non-atomic behavior.

Go's runtime ensures alignment for top-level atomic types. But embedded in a struct, you must align manually:

type Stats struct {
    _      [56]byte // padding for the next field
    Counter atomic.Int64
}

atomic.Int64 is 8-byte aligned. Place it first or pad explicitly.

For atomic.Pointer[T], this isn't an issue because pointers are word-aligned on all supported architectures.

Footgun 2: Cache-line straddling¶

If a struct field crosses a cache-line boundary, atomic operations on it become non-atomic (the hardware may split the access). Go's runtime prevents this for atomic types by alignment, but if you use unsafe.Pointer arithmetic, beware.

Footgun 3: Memory bandwidth saturation¶

High-frequency atomic operations can saturate memory bandwidth. A single CPU can do ~1 billion atomic ops/sec uncontended, but the memory subsystem limits total throughput.

For COW: if writes happen at GHz frequency (you're doing it wrong), bandwidth becomes the bottleneck.

Footgun 4: NUMA effects¶

Atomic operations on a pointer in a different NUMA node pay extra latency. For NUMA-aware applications, partition data per node.

Go does not expose NUMA primitives directly. You can pin OS threads with runtime.LockOSThread and rely on the OS scheduler to keep them on a node.

Footgun 5: TSO vs. acquire/release¶

x86's TSO is stronger than acquire/release but weaker than SC. Specifically:

W1: write(x, 1)
W2: write(y, 1)
R1: read(y)
R2: read(x)

Possible: R1 sees 1, R2 sees 0

Wait, that's a store-buffer effect on weaker models, not TSO. On TSO, writes are visible in program order, so the above is impossible.

But for cross-variable atomic ordering, TSO is not enough — you need SC. Go's atomic.Store uses XCHG to provide SC even on TSO machines, paying a small extra cost.

For COW: not a concern. A single atomic pointer is always coherent.

Deep Dive: A SeqLock-Style Read of Multiple Words¶

Suppose you need to read a 128-bit value atomically (e.g., a 64-bit version plus a 64-bit pointer). Go's atomic.Pointer[T] only handles 64-bit pointers.

A SeqLock pattern:

type Versioned struct {
    version atomic.Uint64
    pointer atomic.Pointer[T]
}

func (v *Versioned) Read() (*T, uint64) {
    for {
        v1 := v.version.Load()
        if v1&1 != 0 {
            continue // writer in progress
        }
        p := v.pointer.Load()
        v2 := v.version.Load()
        if v1 == v2 {
            return p, v1
        }
    }
}

func (v *Versioned) Write(p *T) {
    v.version.Add(1) // odd version: writer in progress
    v.pointer.Store(p)
    v.version.Add(1) // even version: write complete
}

This is the SeqLock pattern. Readers can detect concurrent writes via the version field.

For pure COW, the SeqLock is unnecessary — atomic.Pointer[T] is itself atomic. But for multi-word reads (pointer + version, or pointer + flags), SeqLock-style is useful.

Why this is rarely needed in Go¶

Go's GC and atomic.Pointer give us almost everything for free. SeqLock-style is mainly useful when: - You need version-aware reads. - You're working with structures that span multiple cache lines. - You're matching the C kernel's RCU API exactly.

For 99% of Go code, plain atomic.Pointer[T] is sufficient.

Deep Dive: A Walk Through sync.Map¶

sync.Map is the standard library's most sophisticated read-mostly map. Its design has lessons for COW.

Two maps¶

type Map struct {
    mu     Mutex
    read   atomic.Value // readOnly
    dirty  map[any]*entry
    misses int
}

type readOnly struct {
    m       map[any]*entry
    amended bool
}

• read is the read-only map. Read with atomic.Value.Load.
• dirty is the writable map. Locked by mu.

Reads first check read. If the key is there, return atomically. If not (and the dirty map has it), fall through to the mutex.

Read fast path¶

func (m *Map) Load(key any) (value any, ok bool) {
    read, _ := m.read.Load().(readOnly)
    e, ok := read.m[key]
    if !ok && read.amended {
        // slow path
    }
    if !ok { return nil, false }
    return e.load()
}

For keys present in read, the entire load is a few atomic operations — no mutex.

Write¶

Writes go to dirty. Periodically, dirty is promoted to read (with a new readOnly value stored atomically).

Lessons for COW¶

• sync.Map is COW for the read map and mutex-protected for the write map.
• Promotion of dirty to read is a single atomic.Store of a new readOnly snapshot.
• It's a hybrid: COW for the read path, mutex for the write path, with periodic synchronization.

The pattern: use COW where you can, mutex where you must. Many real systems mix both.

Deep Dive: Detecting Reads During Marking¶

The Go GC's concurrent marker traces from roots. To remain correct, it uses a write barrier on pointer stores. But what about pointer reads?

Reads are free: the GC doesn't care if a reader sees a particular value. The barrier only ensures the GC sees pointer writes.

For COW: read paths pay no GC cost. Write paths pay the write-barrier cost during marking, but no other cost.

This asymmetry is a major reason COW is so efficient in Go.

The "snapshot at the beginning" technique¶

Go's GC takes a snapshot at the start of marking (logically), then traces from it. Pointers stored after the snapshot are tracked via the write barrier. This ensures any reachable object at the start (or made reachable during marking) is marked.

For COW: a new snapshot published during marking is correctly marked because of the write barrier. Old snapshots are reclaimed if no remaining root reaches them.

The hybrid concurrent GC's progress¶

Go's GC has improved over many versions: - 1.4: Stop-the-world. - 1.5: Concurrent marker, but with significant pauses. - 1.8+: Sub-millisecond pauses for most heaps. - 1.14+: Asynchronous preemption (helps GC progress without cooperative yield points). - 1.19+: Soft memory limit, improved pacing. - 1.21+: Continuous improvements to allocator and marker.

For COW systems, each version makes GC overhead lower. Production Go code today has GC pauses below 1 ms for heaps under a few GB.

Deep Dive: GOMAXPROCS and COW Scaling¶

GOMAXPROCS controls how many goroutines can run in parallel. For COW:

• Reads scale linearly with GOMAXPROCS (no contention).
• Writes scale with GOMAXPROCS if you have multiple writers and shard or use CAS; otherwise serialized.

Read scaling¶

GOMAXPROCS=1: 1 read at a time. Throughput = 1 / (Load + use) ≈ 100M reads/sec.
GOMAXPROCS=16: 16 reads in parallel. Throughput ≈ 1.6G reads/sec.

Linear scaling because each reader's atomic Load doesn't invalidate any other reader's cache line.

Write scaling¶

With a single writer mutex, write throughput is constant regardless of GOMAXPROCS. With sharded mutexes (N shards), write throughput scales up to N.

For CAS-based writers: contention grows with the number of writers, so throughput plateaus.

Best practice¶

For read-mostly COW, GOMAXPROCS=NumCPU is correct. Reads benefit from parallelism. Writes are bounded by the design's serialization, not by GOMAXPROCS.

Deep Dive: Comparing COW to RW Locks at the Hardware Level¶

A sync.RWMutex.RLock does:

1. Atomic increment of reader count.
2. Check writer-waiting flag.
3. (If writer waiting) wait.
4. Otherwise proceed.

Step 1 is an atomic operation on the reader count. Multiple readers contend for this cache line. Even with many readers, contention causes ~10-30 ns per RLock.

A COW Load does:

1. Atomic load of the pointer.

The pointer's cache line is shared (not modified by readers). No contention.

The hardware-level difference: COW reads do not invalidate any cache line. RW Mutex reads do.

Numbers¶

• COW Load on a 64-core machine: ~1.5 ns regardless of how many cores are reading.
• RWMutex RLock on a 64-core machine: ~30 ns uncontended, ~100 ns under heavy read load.

20× difference. The reason: RW Mutex requires modifying shared state (the reader count) on every RLock; COW does not.

When RW Mutex catches up¶

If your reads are heavy (do significant work after RLock), the constant overhead is amortized. RW Mutex becomes acceptable when read work is microseconds, not nanoseconds.

For trivial reads (single field access), COW dominates.

Deep Dive: Goroutine Stack Scanning¶

The GC scans every goroutine's stack to find pointers. This is the "stack scan" phase.

For COW: a goroutine holding a snapshot pointer in a local variable contributes that pointer to the live set. The snapshot is kept alive as long as the goroutine's stack contains the reference.

Precision¶

Go's stack scanning is precise — the compiler emits maps describing which stack slots are pointers. The GC follows them exactly. No false positives.

This is why COW works so well: pinned snapshots are exactly those goroutines hold, no more.

Implications for long-running goroutines¶

A goroutine that loads a snapshot once and runs for an hour pins it for an hour. The pin extends to anything else reachable from the snapshot (its fields, including slices and maps).

Mitigation: bound goroutine lifetimes or periodically re-load.

Stack growth¶

Goroutine stacks grow as needed. A function call that requires more stack space triggers a "stack growth" — the runtime allocates a larger stack and copies the contents. Stack-resident pointers (including snapshot references) move with the stack.

The atomic pointer is not on the stack — it's a global or heap-allocated struct. Stack growth doesn't affect it.

Deep Dive: A Cross-Architecture COW Benchmark¶

To see the differences in action, here is a benchmark comparing COW Load latency across architectures.

func BenchmarkCOWLoad(b *testing.B) {
    var p atomic.Pointer[int]
    x := 42
    p.Store(&x)
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            _ = *p.Load()
        }
    })
}

Typical results (median):

x86 wins on absolute latency. ARM is close. RISC-V is slower (younger architecture, fewer optimizations).

The takeaway: for COW, modern hardware is fast. Algorithm-level optimizations matter much more than microsecond-level architecture differences.

Closing Professional-Level Synthesis¶

You now possess the complete mental model of COW in Go:

• The high-level pattern (junior).
• The architectural choices (middle).
• The algorithmic optimizations (senior).
• The runtime mechanics (professional).

Each layer builds on the previous. Each is sufficient for a range of work; together they make you fluent across the entire stack.

The next files in this section apply this knowledge in different formats: - specification.md — formal Go-spec excerpts. - interview.md — interview Q&A. - tasks.md — hands-on exercises. - find-bug.md — bug-finding practice. - optimize.md — performance tuning.

Use them to reinforce, practice, and apply what you've learned. Real mastery comes from doing.

Final Reference: A Cheat Sheet for the Professional¶

// Declare
var p atomic.Pointer[T]

// Initialize
p.Store(&initial)

// Read (one operation)
v := p.Load()

// Write (mutex-protected)
mu.Lock(); defer mu.Unlock()
next := *p.Load()
fn(&next)
p.Store(&next)

// CAS (lock-free)
for {
    cur := p.Load()
    next := transform(cur)
    if p.CompareAndSwap(cur, next) { break }
}

Costs (amd64, L1-hit): - Load: ~1.5 ns - Store: ~10 ns - CAS: ~15 ns

Memory model guarantees: - Store(v) happens-before any Load that observes v. - Within a goroutine, program order is preserved. - Atomic operations are sequentially consistent.

GC interaction: - Pointers in snapshots are scanned during marking. - Old snapshots are reclaimed when no goroutine's reachable set contains them. - Write barriers fire on atomic Store during marking.

This is what every Go engineer should know about COW at the runtime level.

Appendix: Selected Go Runtime Source Pointers¶

For the curious, these are the most relevant source files to read:

• src/sync/atomic/type.go — public API (Pointer, Int64, etc.).
• src/sync/atomic/doc.go — package documentation.
• src/runtime/internal/atomic/* — runtime intrinsics.
• src/runtime/mbarrier.go — write barrier.
• src/runtime/mgcmark.go — GC marking phase.
• src/runtime/proc.go — goroutine scheduling (relevant for stack scanning).
• src/runtime/mheap.go — heap management.
• src/runtime/malloc.go — allocation paths.

Reading even a few of these makes Go's atomic and GC behavior less mysterious.

A senior or professional engineer benefits from a quarterly habit: skim one runtime file and understand it. Over time, you build a complete picture of the runtime.

Appendix: The History of atomic.Value and atomic.Pointer[T]¶

A brief timeline:

• Go 1.4 (Dec 2014): sync/atomic.Value added. Stores interface{}. Designed for COW.
• Go 1.13 (Sep 2019): atomic.Value.Swap added.
• Go 1.17 (Aug 2021): atomic.Value.CompareAndSwap added.
• Go 1.18 (Mar 2022): Generics introduced.
• Go 1.19 (Aug 2022): atomic.Pointer[T], atomic.Int32, atomic.Int64, atomic.Uint32, atomic.Uint64, atomic.Uintptr, atomic.Bool added.
• Go 1.22 (Feb 2024): Improved escape analysis for atomic types.
• Go 1.24+ (TBD): Continued refinement.

The progression shows Go's commitment to making atomic operations safer and more ergonomic. New code on 1.19+ should use the typed forms.

Appendix: Notable Bug Reports and CVEs¶

A few public bugs related to atomic operations and COW patterns:

• #52382 (atomic.Value with nil interface): Storing a nil interface caused panic in some paths; fixed.
• #48141 (RWMutex starvation): Long-running writers could starve readers; fixed by writer-preferring semantics in 1.18+.
• #37052 (memory model clarification): A long-running discussion that eventually produced the Go 1.19 memory model, formalizing atomic ordering.

Following Go's issue tracker is the best way to stay current on subtle bug fixes that may affect your COW code.

Appendix: Future Directions¶

Looking ahead:

• More granular memory ordering. Some teams advocate exposing acquire/release semantics for performance. Trade-off: complexity vs speed.
• Improved escape analysis. Snapshot allocations may move to stack in more cases.
• Standard persistent collections. Long-discussed; may eventually ship.
• Hardware transactional memory. Intel TSX, ARM TME. Not yet widely supported in Go, but watch this space.

A professional engineer keeps an eye on these developments, anticipating shifts in best practice.

Appendix: A Final, Practical Example¶

To close, a complete production COW example using everything covered:

package config

import (
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "os"
    "sync"
    "sync/atomic"
    "time"

    "github.com/prometheus/client_golang/prometheus"
    "go.opentelemetry.io/otel/trace"
)

type Config struct {
    Version     int64                  `json:"version"`
    PublishedAt time.Time              `json:"published_at"`
    Settings    map[string]string      `json:"settings"`
    Features    map[string]bool        `json:"features"`
    Routes      []Route                `json:"routes"`
}

type Route struct {
    Pattern string `json:"pattern"`
    Backend string `json:"backend"`
}

func (c *Config) Validate() error {
    if c.Settings == nil { return errors.New("settings nil") }
    if c.Features == nil { return errors.New("features nil") }
    for i, r := range c.Routes {
        if r.Pattern == "" || r.Backend == "" {
            return fmt.Errorf("route %d invalid", i)
        }
    }
    return nil
}

type Store struct {
    cur     atomic.Pointer[Config]
    mu      sync.Mutex
    tracer  trace.Tracer
    metrics *metrics
    path    string
    nextVer int64
}

type metrics struct {
    version      prometheus.Gauge
    age          prometheus.Gauge
    updates      prometheus.Counter
    failures     prometheus.Counter
    loadLatency  prometheus.Histogram
    writeLatency prometheus.Histogram
}

func NewStore(initial *Config, path string, tracer trace.Tracer) (*Store, error) {
    if err := initial.Validate(); err != nil {
        return nil, err
    }
    s := &Store{
        path:    path,
        tracer:  tracer,
        nextVer: 1,
        metrics: newMetrics(),
    }
    initial.Version = s.nextVer
    initial.PublishedAt = time.Now()
    s.cur.Store(initial)
    s.metrics.version.Set(float64(initial.Version))
    s.nextVer++
    return s, nil
}

func (s *Store) Get(ctx context.Context) *Config {
    _, span := s.tracer.Start(ctx, "config.Get")
    defer span.End()
    c := s.cur.Load()
    s.metrics.age.Set(time.Since(c.PublishedAt).Seconds())
    return c
}

func (s *Store) Update(ctx context.Context, fn func(*Config) error) (err error) {
    ctx, span := s.tracer.Start(ctx, "config.Update")
    defer span.End()
    start := time.Now()
    defer func() { s.metrics.writeLatency.Observe(time.Since(start).Seconds()) }()

    s.mu.Lock()
    defer s.mu.Unlock()
    old := s.cur.Load()
    next := old.Clone()
    if err = fn(next); err != nil {
        s.metrics.failures.Inc()
        span.RecordError(err)
        return
    }
    if err = next.Validate(); err != nil {
        s.metrics.failures.Inc()
        span.RecordError(err)
        return
    }
    next.Version = s.nextVer
    next.PublishedAt = time.Now()
    s.nextVer++
    s.cur.Store(next)
    s.metrics.updates.Inc()
    s.metrics.version.Set(float64(next.Version))
    return nil
}

func (s *Store) Reload(ctx context.Context) error {
    ctx, span := s.tracer.Start(ctx, "config.Reload")
    defer span.End()
    b, err := os.ReadFile(s.path)
    if err != nil {
        s.metrics.failures.Inc()
        return err
    }
    var next Config
    if err := json.Unmarshal(b, &next); err != nil {
        s.metrics.failures.Inc()
        return err
    }
    s.mu.Lock()
    defer s.mu.Unlock()
    if err := next.Validate(); err != nil {
        s.metrics.failures.Inc()
        return err
    }
    next.Version = s.nextVer
    next.PublishedAt = time.Now()
    s.nextVer++
    s.cur.Store(&next)
    s.metrics.updates.Inc()
    s.metrics.version.Set(float64(next.Version))
    return nil
}

func (c *Config) Clone() *Config {
    cp := *c
    cp.Settings = make(map[string]string, len(c.Settings))
    for k, v := range c.Settings { cp.Settings[k] = v }
    cp.Features = make(map[string]bool, len(c.Features))
    for k, v := range c.Features { cp.Features[k] = v }
    cp.Routes = append([]Route(nil), c.Routes...)
    return &cp
}

This is what production COW looks like. It uses: - atomic.Pointer[T] for the snapshot. - A writer mutex for serialization. - Validation before publish. - Deep clone via a method on the snapshot type. - Tracing (OpenTelemetry). - Metrics (Prometheus). - Reload from a JSON file. - Errors propagated to the caller.

Every pattern from junior through professional level is here. This is the synthesis.

A Final, Final Word¶

Copy-on-write is one of the most elegant patterns in Go. From a five-line atomic.Pointer[T] snippet to a million-entry sharded persistent map with hot reload and full observability, the pattern scales gracefully.

The journey from "I write go f()" to "I can explain how atomic.Pointer[T].Load is implemented on ARM64" is long. But it's a journey worth taking. The depth informs decision-making at every level.

For your next COW system: start simple. Use atomic.Pointer[T] and a writer mutex. Measure. If you need more, you have the toolkit to scale up.

That is the gift of having read four levels of this document. Use it well.

Extended Section: Memory Model — Worked Examples¶

To deepen understanding, walk through specific examples of memory-model reasoning applied to COW scenarios.

Example 1: Single producer, single consumer¶

var p atomic.Pointer[Data]
var ready atomic.Bool

// Producer
data := &Data{Value: 42}
p.Store(data)
ready.Store(true)

// Consumer
for !ready.Load() { runtime.Gosched() }
v := p.Load().Value

Question: is v == 42 guaranteed?

Walking through: - data.Value = 42 happens-before p.Store(data) (program order). - p.Store(data) happens-before ready.Store(true) (program order in producer). - ready.Load() returning true happens-after ready.Store(true) (atomic sync). - ready.Load() happens-before p.Load() (program order in consumer).

Transitively: data.Value = 42 happens-before p.Load().Value access.

Therefore v == 42 is guaranteed.

Example 2: Two writers, one reader¶

var p atomic.Pointer[int]

// Writer A
a := 1
p.Store(&a)

// Writer B
b := 2
p.Store(&b)

// Reader
v := *p.Load()

Question: what values can v be?

Sequential consistency requires a total order on the three atomic operations. The reader sees the value of the most recent Store in this order.

Cases: - Store(A), Store(B), Load: v == 2 - Store(B), Store(A), Load: v == 1 - Store(A), Load, Store(B): v == 1 - Load, Store(A), Store(B): v == (initial, likely panic on nil deref) - Other orderings: similarly bounded.

In all valid orderings, v is either 1, 2, or initial. No partial state.

Example 3: Snapshot field consistency¶

var p atomic.Pointer[Pair]

type Pair struct {
    A int
    B int
}

// Writer
p.Store(&Pair{A: 1, B: 2})
p.Store(&Pair{A: 10, B: 20})

// Reader
s := p.Load()
fmt.Printf("%d %d", s.A, s.B)

Question: can the reader see 1 20 or 10 2?

No. Each Pair literal is fully constructed before the Store. The reader sees one full Pair: 1 2 or 10 20.

The construction &Pair{A: 1, B: 2} happens entirely before the Store (program order in writer). The reader's field accesses happen after the Load (program order). The Store/Load atomic edge connects them.

Example 4: Mutated snapshot¶

var p atomic.Pointer[Pair]
pair := &Pair{A: 1, B: 2}
p.Store(pair)

// Reader 1
go func() {
    s := p.Load()
    fmt.Printf("R1: %d %d\n", s.A, s.B)
}()

// Buggy writer (mutates published snapshot!)
pair.A = 100
pair.B = 200

Question: what does R1 print?

Undefined behavior. R1 may print 1 2, 100 200, 1 200, 100 2, or anything. The race detector flags this as a data race.

There is no happens-before relationship between the buggy writer's pair.A = 100 and the reader's s.A access. They are racing.

Lesson: never mutate a published snapshot.

Example 5: Cross-pointer ordering¶

var pa, pb atomic.Pointer[int]
a, b := 1, 2

// Writer
pa.Store(&a)
pb.Store(&b)

// Reader
if pb.Load() != nil {
    x := *pa.Load() // is x guaranteed to be 1?
}

Question: if the reader observes pb != nil, does it see pa updated?

Yes, by sequential consistency. In the total order: - pa.Store(&a) happens before pb.Store(&b) (program order in writer). - pb.Load() (returning non-nil) happens after pb.Store(&b) (atomic edge). - pa.Load() happens after pb.Load() (program order in reader).

By transitivity: pa.Store(&a) happens before pa.Load(). So pa.Load() returns &a, and *pa.Load() == 1.

This is a powerful guarantee — atomic operations on different variables are coordinated by the total order.

Example 6: Memory barriers without atomics¶

var x int
var done atomic.Bool

// Writer
x = 42
done.Store(true)

// Reader
if done.Load() {
    fmt.Println(x)
}

Question: does the reader print 42?

Yes. The atomic Store/Load creates a happens-before edge. The non-atomic write x = 42 happens-before the Store (program order in writer); the Load (returning true) happens-after the Store (atomic edge); the read of x happens-after the Load (program order).

Transitively: x = 42 happens-before read of x. The reader sees 42.