Chapter 11: Atomic Operations

// Illustrative snippet — not a complete program
var counter int64

atomic.AddInt64(&counter, 1)           // Increment
value := atomic.LoadInt64(&counter)    // Read
atomic.StoreInt64(&counter, 0)         // Write

// Illustrative snippet — not a complete program
var counter atomic.Int64

counter.Add(1)          // Increment
value := counter.Load() // Read
counter.Store(0)        // Write

// Illustrative snippet — not a complete program
type Metrics struct {
    requests atomic.Int64   // Ready to use, starts at 0
    errors   atomic.Int64   // No initialization needed
    healthy  atomic.Bool    // Starts as false
}

func (m *Metrics) RecordRequest() {
    m.requests.Add(1)  // Works immediately
}

// Illustrative snippet — not a complete program
// ✗ UNNECESSARY
counter := new(atomic.Int64)
counter.Store(0)

// ✓ CORRECT
var counter atomic.Int64

// Illustrative snippet — not a complete program
var counter atomic.Int64
var config atomic.Pointer[Config]

value := counter.Load()   // Returns int64
cfg := config.Load()      // Returns *Config

// Illustrative snippet — not a complete program
// ✗ BROKEN — the legacy API lets you mix the two
var counter int64
atomic.AddInt64(&counter, 1)  // atomic write
racy := counter               // plain read → DATA RACE

// Illustrative snippet — not a complete program
// ✓ CORRECT — both sides go through the package
var counter int64
atomic.AddInt64(&counter, 1)
value := atomic.LoadInt64(&counter)

// Illustrative snippet — not a complete program
var counter atomic.Int64
counter.Add(1)

// There is no counter + 1, no int64(counter), no counter++.
// Load is the only door.
value := counter.Load()

// Illustrative snippet — not a complete program
var shutdown atomic.Bool
var config atomic.Pointer[Config]

shutdown.Store(true)                              // Signal shutdown
config.Store(&Config{Timeout: 30 * time.Second})  // Update config

// Illustrative snippet — not a complete program
// Shutdown flag pattern
func (s *Server) Shutdown() {
    s.shutdown.Store(true)  // All readers immediately see true
}

func (s *Server) worker() {
    for !s.shutdown.Load() {
        // Do work...
    }
}

// Illustrative snippet — not a complete program
type Cache struct {
    data atomic.Pointer[CacheData]
}

func (c *Cache) Update() {
    current := c.data.Load()
    current.Count++  // Modify field directly
}

// Illustrative snippet — not a complete program
var counter atomic.Int64

newValue := counter.Add(1)   // Increment, returns new value
newValue = counter.Add(-1)   // Decrement, returns new value
newValue = counter.Add(10)   // Add 10, returns new value

// Illustrative snippet — not a complete program
var counter atomic.Int64  // starts at 0
result := counter.Add(5)  // result is 5, the value AFTER the add
result = counter.Add(3)   // result is 8, likewise

// Illustrative snippet — not a complete program
after := counter.Add(delta)
before := after - delta  // valid only for THIS goroutine's Add

// Illustrative snippet — not a complete program
type Metrics struct {
    requests atomic.Int64
    errors   atomic.Int64
}

func (m *Metrics) RecordError() {
    m.errors.Add(1)
    m.requests.Add(1)  // Count as request too
}

func (m *Metrics) Stats() (requests, errors int64) {
    return m.requests.Load(), m.errors.Load()
}

// Illustrative snippet — not a complete program
var flag atomic.Bool
var counter atomic.Int64

wasSet := flag.Swap(true)     // Returns previous value
oldCount := counter.Swap(0)   // Reset and get previous count

// Illustrative snippet — not a complete program
// Pattern: Drain and reset
func (m *Metrics) DrainRequests() int64 {
    return m.pendingRequests.Swap(0)  // Get count, reset to zero
}

// Pattern: Claim ownership (only first caller proceeds)
func (s *Server) Shutdown() {
    if s.running.Swap(false) {
        // Was true, now false—we're responsible for cleanup
        s.cleanup()
    }
    // Was already false—another goroutine handled it
}

// Illustrative snippet — not a complete program
var state atomic.Int64
state.Store(10)

swapped := state.CompareAndSwap(10, 20)  // Expects 10, sets to 20
fmt.Println(swapped)        // true
fmt.Println(state.Load())   // 20

swapped = state.CompareAndSwap(10, 30)   // Expects 10, but value is 20
fmt.Println(swapped)        // false (no change)
fmt.Println(state.Load())   // 20

// Illustrative snippet — not a complete program
for {
    old := value.Load()            // 1. read the current value
    next := computeNext(old)       // 2. compute the one you want
    if value.CompareAndSwap(old, next) {
        break                      // 3. success
    }
    // Someone else won. Loop back to step 1 -- and note that it
    // really is step 1: you must re-Load, not retry with the stale
    // `old`, or the CAS will fail forever.
}

// Illustrative snippet — not a complete program
func updateMax(target *atomic.Int64, value int64) {
    for {
        current := target.Load()
        if value <= current {
            return  // Current max already >= value
        }
        if target.CompareAndSwap(current, value) {
            return  // Successfully updated
        }
        // CAS failed: another goroutine changed it; retry
    }
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: the return value is the only report of failure
counter.CompareAndSwap(10, 11)

// ✓ CORRECT: act on it
if !counter.CompareAndSwap(10, 11) {
    // retry, log, or return an error -- but decide
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: two separate reads, two different instants
counter.CompareAndSwap(counter.Load(), counter.Load()+1)
//                     ^^^^ first      ^^^^ second, possibly newer

// Illustrative snippet — not a complete program
old := counter.Load()
counter.CompareAndSwap(old, old+1)

// Illustrative snippet — not a complete program
counter.Add(1)  // Atomic, no CAS needed

// Illustrative snippet — not a complete program
var counter atomic.Int64

// Attempt to increment
counter.CompareAndSwap(counter.Load(), counter.Load()+1)

// Illustrative snippet — not a complete program
var flags atomic.Uint32

// Type the constants. An untyped `1 << 1` is fine going in, but the
// complement below is not: ^flagDraining on an untyped constant is
// -3, which does not fit a uint32 and will not compile.
const (
    flagReady    uint32 = 1 << 0
    flagDraining uint32 = 1 << 1
    flagFailed   uint32 = 1 << 2
)

old := flags.Or(flagReady)       // set a bit, learn whether it was set
was := flags.And(^flagDraining)  // clear a bit, learn its old state

// Illustrative snippet — not a complete program
// The pre-1.23 spelling. Correct, but three lines and a loop for
// something the CPU does in one instruction.
for {
    old := flags.Load()
    if flags.CompareAndSwap(old, old|flagReady) {
        break
    }
}

// Illustrative snippet — not a complete program
// A connection's state as a bitset rather than four flags.
type Conn struct {
    flags atomic.Uint32
}

func (c *Conn) MarkDraining() {
    c.flags.Or(flagDraining)
}

func (c *Conn) Snapshot() (ready, draining, failed bool) {
    f := c.flags.Load()   // one load, one coherent view
    return f&flagReady != 0, f&flagDraining != 0, f&flagFailed != 0
}

// Illustrative snippet — not a complete program
var f atomic.Uint32
f.Store(0b0001)
prev := f.Or(0b0010)   // prev == 0b0001, f is now 0b0011

// Illustrative snippet — not a complete program
type Config struct {
    Timeout  time.Duration
    MaxConns int
}

var globalConfig atomic.Pointer[Config]

func init() {
    globalConfig.Store(&Config{
        Timeout:  30 * time.Second,
        MaxConns: 100,
    })
}

func GetConfig() *Config {
    return globalConfig.Load()  // Returns *Config directly
}

func UpdateConfig(cfg *Config) {
    globalConfig.Store(cfg)
}

// Illustrative snippet — not a complete program
a := &Config{Port: 8080}
b := &Config{Port: 8080}  // same contents, different address

config.Store(a)
config.CompareAndSwap(b, next)  // ✗ fails: b is not a
config.CompareAndSwap(a, next)  // ✓ works:  a is a

// Illustrative snippet — not a complete program
for {
    old := config.Load()      // the pointer actually stored
    next := &Config{...}
    if config.CompareAndSwap(old, next) {
        break
    }
}

// Illustrative snippet — not a complete program
cfg := globalConfig.Load()
cfg.Timeout = 5 * time.Second  // DATA RACE with every current reader

// Illustrative snippet — not a complete program
func UpdateTimeout(newTimeout time.Duration) {
    for {
        old := globalConfig.Load()
        next := &Config{
            Timeout:  newTimeout,
            MaxConns: old.MaxConns,
        }
        if globalConfig.CompareAndSwap(old, next) {
            return
        }
    }
}

// Illustrative snippet — not a complete program
var cache atomic.Value

// Store a map (non-pointer type)
cache.Store(map[string]int{"a": 1, "b": 2})

// Load requires type assertion
m := cache.Load().(map[string]int)

// Illustrative snippet — not a complete program
func GetConfig() *Config {
    v := configValue.Load()
    if v == nil {
        return nil  // Not yet initialized
    }
    return v.(*Config)
}

// Illustrative snippet — not a complete program
var ready atomic.Bool
var data string

// Goroutine A
data = "hello"        // Regular write
ready.Store(true)     // Atomic Store (release)

// Goroutine B
if ready.Load() {     // Atomic Load (acquire)
    fmt.Println(data) // Guaranteed to see "hello"
}

// Illustrative snippet — not a complete program
// ✗ WRONG: No synchronization (data race)
var data string
var ready bool  // Non-atomic!

// Writer
data = "hello"
ready = true  // Non-atomic write

// Reader
if ready {    // Non-atomic read
    // May see empty string! No happens-before guarantee
    fmt.Println(data)
}

// Illustrative snippet — not a complete program
var counter int64

atomic.AddInt64(&counter, 1)
value := atomic.LoadInt64(&counter)
atomic.StoreInt64(&counter, 0)
swapped := atomic.CompareAndSwapInt64(&counter, 0, 1)

// Illustrative snippet — not a complete program
// ✗ May CRASH on 32-bit systems
type Stats struct {
    flag    bool    // 1 byte
    counter int64   // May not be 8-byte aligned!
}

func (s *Stats) Increment() {
    atomic.AddInt64(&s.counter, 1)
    // PANIC on 32-bit ARM: "panic: unaligned 64-bit atomic operation"
}

// ✓ CORRECT: Typed atomics handle alignment
type Stats struct {
    flag    bool
    counter atomic.Int64  // Always properly aligned
}

// Illustrative snippet — not a complete program
var counter int64  // Is this atomic? Who knows!

func bad() {
    counter++  // Oops: should have used atomic.AddInt64
}

// Illustrative snippet — not a complete program
var counter atomic.Int64  // Obviously atomic

func good() {
    counter.Add(1)  // The only way to modify it
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Copying loses atomicity
var counter atomic.Int64
counter.Store(42)

counterCopy := counter      // Copies the struct
counterCopy.Add(1)          // Operates on COPY, not original
fmt.Println(counter.Load()) // Still 42!

// ✓ CORRECT: Pass by pointer
func increment(c *atomic.Int64) {
    c.Add(1)
}

// Illustrative snippet — not a complete program
// ✗ WRONG: Function receives a copy
func incrementByValue(c atomic.Int64) {
    c.Add(1)  // Modifies the COPY, not the original
}

var count atomic.Int64
count.Store(10)
incrementByValue(count)
fmt.Println(count.Load())  // Still 10!

// ✓ CORRECT: Pass pointer to struct containing atomic
type Counter struct {
    value atomic.Int64
}

func (c *Counter) Increment() {
    c.value.Add(1)  // Modifies the actual atomic
}

// Illustrative snippet — not a complete program
type Metrics struct {
    requests int64
}

func (m *Metrics) Inc() {
    atomic.AddInt64(&m.requests, 1)
}

func (m *Metrics) Get() int64 {
    return m.requests  // Direct read
}

// Illustrative snippet — not a complete program
func Increment() int64 {
    counter.Add(1)
    return counter.Load()
}

// Illustrative snippet — not a complete program
var cache atomic.Value

func Init() {
    cache.Store(map[string]int{})
}

func Reset() {
    cache.Store([]string{})
}

// Illustrative snippet — not a complete program
var flag atomic.Bool
result := flag.Swap(true)

// Illustrative snippet — not a complete program
config.Store(&Config{Port: 8080})

expected := &Config{Port: 8080}  // Same contents
newCfg := &Config{Port: 9090}
success := config.CompareAndSwap(expected, newCfg)

// Illustrative snippet — not a complete program
type Server struct {
    shutdown atomic.Bool
    wg       sync.WaitGroup
}

func (s *Server) Shutdown() {
    s.shutdown.Store(true)  // Signal all workers
    s.wg.Wait()             // Wait for completion
}

func (s *Server) worker(id int) {
    defer s.wg.Done()

    for !s.shutdown.Load() {  // Lock-free check on every iteration
        s.doWork()  // If this blocks long, shutdown check is delayed
    }
    log.Printf("Worker %d exiting", id)
}

// Illustrative snippet — not a complete program
// A named type over uint32 keeps the states readable; the atomic
// holds the underlying value, so transitions convert at the call.
// §11.4.6 builds the whole machine this way.
type ConnState uint32

const (
    StateDisconnected ConnState = iota
    StateConnecting
    StateConnected
)

// Only one concurrent caller can win this transition; the rest get
// the error and know they did not start the connection attempt.
if !c.state.CompareAndSwap(
    uint32(StateDisconnected), uint32(StateConnecting)) {
    return errors.New("invalid state for connect")
}

// Illustrative snippet — not a complete program
type FeatureFlags struct {
    debugMode      atomic.Bool
    newAlgorithm   atomic.Bool
    rateLimiting   atomic.Bool
}

func ProcessRequest(req *Request) *Response {
    if features.debugMode.Load() {
        log.Printf("Processing request: %+v", req)
    }

    if features.newAlgorithm.Load() {
        return processWithNewAlgorithm(req)
    }
    return processWithOldAlgorithm(req)
}

// Toggle returns the new value
func (f *FeatureFlags) ToggleDebugMode() bool {
    for {
        old := f.debugMode.Load()
        next := !old
        if f.debugMode.CompareAndSwap(old, next) {
            return next  // report what we actually stored
        }
        // Another goroutine toggled; retry
    }
}

// Illustrative snippet — not a complete program
type ServerMetrics struct {
    requestsTotal   atomic.Int64
    requestsActive  atomic.Int64
    bytesReceived   atomic.Int64
    bytesSent       atomic.Int64
    errorsTotal     atomic.Int64
}

func (m *ServerMetrics) HandleRequest(req *Request) {
    m.requestsActive.Add(1)
    defer m.requestsActive.Add(-1)

    m.requestsTotal.Add(1)
    m.bytesReceived.Add(int64(req.Size))

    resp, err := processRequest(req)
    if err != nil {
        m.errorsTotal.Add(1)
        return
    }

    m.bytesSent.Add(int64(resp.Size))
}

// Illustrative snippet — not a complete program
// Mutex: four steps, one of which can block.
func (m *Metrics) Inc() {
    m.mu.Lock()
    m.count++
    m.mu.Unlock()
}

// Illustrative snippet — not a complete program
// Atomic: one instruction, and it never blocks.
func (m *Metrics) Inc() {
    m.count.Add(1)
}

// Illustrative snippet — not a complete program
// Multiple related counters with invariants
type Stats struct {
    mu       sync.Mutex
    success  int64
    failure  int64
    total    int64  // Invariant: total == success + failure
}

func (s *Stats) RecordSuccess() {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.success++
    s.total++  // must move together, or the invariant is briefly false
}

func (s *Stats) RecordFailure() {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.failure++
    s.total++
}

func (s *Stats) Snapshot() (success, failure, total int64) {
    s.mu.Lock()
    defer s.mu.Unlock()
    return s.success, s.failure, s.total  // Consistent snapshot
}

// Illustrative snippet — not a complete program
// Swap is the whole point: Load followed by Store(0) would lose
// every increment that arrived between the two.
func (m *IntervalMetrics) Collect() (requests, errors int64) {
    return m.requests.Swap(0), m.errors.Swap(0)
}

// Illustrative snippet — not a complete program
func updateMax(target *atomic.Int64, value int64) {
    for {
        current := target.Load()
        if value <= current {
            return              // not a new maximum; nothing to do
        }
        if target.CompareAndSwap(current, value) {
            return
        }
        // another goroutine raised it; re-read and reconsider
    }
}

// Illustrative snippet — not a complete program
type IDGenerator struct{ next atomic.Uint64 }

func (g *IDGenerator) Next() uint64 { return g.next.Add(1) }

// Illustrative snippet — not a complete program
type Activity struct {
    lastSeen atomic.Int64  // Unix nano timestamp
}

func (a *Activity) Touch() {
    a.lastSeen.Store(time.Now().UnixNano())
}

func (a *Activity) LastSeen() time.Time {
    ns := a.lastSeen.Load()
    if ns == 0 {
        return time.Time{}  // Zero time
    }
    return time.Unix(0, ns)
}

func (a *Activity) IdleDuration() time.Duration {
    ns := a.lastSeen.Load()
    if ns == 0 {
        return 0
    }
    return time.Since(time.Unix(0, ns))
}

// Illustrative snippet — not a complete program
type LazyResource struct {
    ready    atomic.Bool
    mu       sync.Mutex
    resource *ExpensiveResource
}

func (r *LazyResource) Get() *ExpensiveResource {
    if r.ready.Load() {          // fast path: no lock
        return r.resource
    }

    r.mu.Lock()
    defer r.mu.Unlock()
    if r.ready.Load() {          // another goroutine won the race
        return r.resource
    }
    r.resource = createExpensiveResource()
    r.ready.Store(true)          // publishes the write above
    return r.resource
}

// Illustrative snippet — not a complete program
var getResource = sync.OnceValue(createExpensiveResource)

// Illustrative snippet — not a complete program
type Config struct {
    Timeout    time.Duration
    MaxRetries int
    Endpoints  []string
    Features   map[string]bool
}

// One pointer, swapped whole. Readers take whatever it points at.
var config atomic.Pointer[Config]

// Called on every request. 1.17 ns, and unlike a read lock it
// scales: nobody writes the line, so every core can hold it.
func Current() *Config { return config.Load() }

// Called on a reload or an admin action, perhaps hourly.
func Publish(cfg *Config) { config.Store(cfg) }

// Illustrative snippet — not a complete program
func (cm *ConfigManager) SetTimeout(timeout time.Duration) {
    for {
        old := cm.config.Load()
        updated := *old            // copy the struct
        updated.Timeout = timeout  // change the copy
        if cm.config.CompareAndSwap(old, &updated) {
            return
        }
        // someone else published in the meantime; retry from theirs
    }
}

// Illustrative snippet — not a complete program
type ProgressTracker struct {
    total     int64          // set in the constructor, then read-only
    completed atomic.Int64
}

func (p *ProgressTracker) Complete(n int64) { p.completed.Add(n) }
func (p *ProgressTracker) Done() int64 { return p.completed.Load() }

// Illustrative snippet — not a complete program
type RequestLimiter struct {
    active atomic.Int64
    limit  int64
}

func (r *RequestLimiter) TryAcquire() bool {
    for {
        current := r.active.Load()
        if current >= r.limit {
            return false  // At capacity
        }
        if r.active.CompareAndSwap(current, current+1) {
            return true  // Acquired
        }
        // CAS failed—another goroutine changed it; retry
    }
}

func (r *RequestLimiter) Release() {
    r.active.Add(-1)
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: the check and the increment are two operations
func (r *RequestLimiter) TryAcquire() bool {
    if r.active.Load() < r.limit {
        r.active.Add(1)  // two goroutines can both reach here
        return true
    }
    return false
}

// Illustrative snippet — not a complete program
type Cache struct {
    mu    sync.RWMutex
    data  map[string][]byte

    // High-frequency atomic counters
    hits   atomic.Int64
    misses atomic.Int64
}

func (c *Cache) Get(key string) ([]byte, bool) {
    c.mu.RLock()
    val, ok := c.data[key]
    c.mu.RUnlock()

    if ok {
        c.hits.Add(1)    // Lock-free increment
    } else {
        c.misses.Add(1)  // Lock-free increment
    }

    return val, ok
}

// Illustrative snippet — not a complete program
// ✗ Inconsistent: size and hits/misses captured at different moments
func (c *Cache) Stats() (size int, hits, misses int64) {
    c.mu.RLock()
    size = len(c.data)
    c.mu.RUnlock()

    hits = c.hits.Load()
    misses = c.misses.Load()
    return  // size may not line up with hits+misses
}

// Illustrative snippet — not a complete program
func BenchmarkAtomicAdd(b *testing.B) {
    var c atomic.Int64          // declared here, not at package level
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            c.Add(1)
        }
    })
}

func BenchmarkMutexAdd(b *testing.B) {
    var mu sync.Mutex           // a fresh lock, for the same reason
    var c int64
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            mu.Lock()
            c++
            mu.Unlock()
        }
    })
}

// Illustrative snippet — not a complete program
type Feature struct {
    enabled atomic.Bool
    config  map[string]string  // Feature configuration
}

func (f *Feature) Enable(cfg map[string]string) {
    f.config = cfg
    f.enabled.Store(true)
}

func (f *Feature) GetConfig() map[string]string {
    if f.enabled.Load() {
        return f.config
    }
    return nil
}

// Illustrative snippet — not a complete program
func (r *RequestLimiter) TryAcquire() bool {
    if r.active.Load() < r.limit {
        r.active.Add(1)
        return true
    }
    return false
}

// Illustrative snippet — not a complete program
type Logger struct {
    mu        sync.Mutex
    file      *os.File
    lineCount int64  // Should this be atomic?
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Invariant violation
type Account struct {
    balance atomic.Int64
    limit   atomic.Int64  // Invariant: balance <= limit
}

func (a *Account) Deposit(amount int64) {
    a.balance.Add(amount)
    // What if balance now exceeds limit?
    // No way to check-and-update atomically across both fields
}

func (a *Account) SetLimit(newLimit int64) {
    // What if current balance exceeds newLimit?
    a.limit.Store(newLimit)  // Invariant may already be broken
}

func (a *Account) IsValid() bool {
    balance := a.balance.Load()
    limit := a.limit.Load()
    // Between these two loads either value can change.
    return balance <= limit
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Mutex protects the invariant
type Account struct {
    mu      sync.Mutex
    balance int64
    limit   int64
}

func (a *Account) Deposit(amount int64) error {
    a.mu.Lock()
    defer a.mu.Unlock()

    newBalance := a.balance + amount
    if newBalance > a.limit {
        return errors.New("deposit would exceed limit")
    }
    a.balance = newBalance
    return nil
}

func (a *Account) SetLimit(newLimit int64) error {
    a.mu.Lock()
    defer a.mu.Unlock()

    if a.balance > newLimit {
        return errors.New("current balance exceeds new limit")
    }
    a.limit = newLimit
    return nil
}

// Illustrative snippet — not a complete program
type AccountState struct {
    Balance int64
    Limit   int64
}

type Account struct {
    state atomic.Pointer[AccountState]
}

func (a *Account) Deposit(amount int64) error {
    for {
        old := a.state.Load()
        newBalance := old.Balance + amount
        if newBalance > old.Limit {
            return errors.New("deposit would exceed limit")
        }

        newState := &AccountState{
            Balance: newBalance,
            Limit:   old.Limit,
        }

        if a.state.CompareAndSwap(old, newState) {
            return nil
        }
        // Another goroutine changed state; retry
    }
}

func (a *Account) Get() (balance, limit int64) {
    s := a.state.Load()
    return s.Balance, s.Limit  // Guaranteed consistent
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Bank transfer loses money
func Transfer(from, to *atomic.Int64, amount int64) error {
    if from.Load() < amount {
        return errors.New("insufficient funds")
    }

    from.Add(-amount)  // Deducted!
    // ← another goroutine reading both accounts here sees
    //   the money in neither of them
    to.Add(amount)

    return nil
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Mutex ensures atomic transfer
type Bank struct {
    mu       sync.Mutex
    accounts map[string]int64
}

func (b *Bank) Transfer(from, to string, amount int64) error {
    b.mu.Lock()
    defer b.mu.Unlock()

    if b.accounts[from] < amount {
        return errors.New("insufficient funds")
    }

    b.accounts[from] -= amount
    b.accounts[to] += amount
    return nil
}

// Illustrative snippet — not a complete program
// Snapshot returns approximately-consistent stats.
// Values may be from slightly different instants.
// Suitable for monitoring; NOT suitable for billing or SLAs.
func (s *Stats) Snapshot() (requests, errors, latency int64) {
    return s.requests.Load(), s.errors.Load(), s.latency.Load()
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Race between check and act
type Pool struct {
    available atomic.Int64
    max       int64
}

func (p *Pool) Acquire() bool {
    if p.available.Load() > 0 {
        // another goroutine may have taken the last one
        p.available.Add(-1)
        return true
    }
    return false
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: CAS ensures check and act are atomic
func (p *Pool) Acquire() bool {
    for {
        current := p.available.Load()
        if current <= 0 {
            return false  // Nothing available
        }
        if p.available.CompareAndSwap(current, current-1) {
            return true  // Successfully acquired
        }
        // CAS failed—another goroutine changed it; retry
    }
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Mutex is often clearer for check-then-act
type Pool struct {
    mu        sync.Mutex
    available int64
    max       int64
}

func (p *Pool) Acquire() bool {
    p.mu.Lock()
    defer p.mu.Unlock()

    if p.available <= 0 {
        return false
    }
    p.available--
    return true
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Multiple goroutines might initialize
var initialized atomic.Bool
var data *Config

func GetConfig() *Config {
    if !initialized.Load() {
        data = loadConfig()      // several goroutines can reach here
        initialized.Store(true)
    }
    return data
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Use sync.Once
var once sync.Once
var data *Config

func GetConfig() *Config {
    once.Do(func() {
        data = loadConfig()  // Guaranteed to run exactly once
    })
    return data
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Multiple goroutines might both "claim"
func (w *Worker) TryClaim() bool {
    if !w.claimed.Load() {
        w.claimed.Store(true)
        return true  // Another goroutine might also return true!
    }
    return false
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: CAS guarantees only one succeeds
func (w *Worker) TryClaim() bool {
    return w.claimed.CompareAndSwap(false, true)
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: State change has side effects
type Connection struct {
    state    atomic.Uint32  // a ConnState (§11.2.1)
    socket   net.Conn
    handlers []Handler
}

func (c *Connection) Close() error {
    if !c.state.CompareAndSwap(
        uint32(StateConnected), uint32(StateClosing)) {
        return errors.New("not connected")
    }

    // Problem: others see StateClosing while the socket is still open
    c.socket.Close()

    // Problem: handlers run after the close, before the final state
    for _, h := range c.handlers {
        h.OnClose()
    }

    c.state.Store(StateClosed)
    return nil
}

func (c *Connection) Send(data []byte) error {
    if c.state.Load() != StateConnected {
        return errors.New("not connected")
    }
    // Race: state might change to StateClosing between check and write
    _, err := c.socket.Write(data)
    return err
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Mutex bundles state change with side effects
type Connection struct {
    mu       sync.Mutex
    state    int32
    socket   net.Conn
    handlers []Handler
}

func (c *Connection) Close() error {
    c.mu.Lock()
    defer c.mu.Unlock()

    if c.state != StateConnected {
        return errors.New("not connected")
    }

    c.state = StateClosing

    // All cleanup happens atomically from observers' perspective
    if err := c.socket.Close(); err != nil {
        // In production prefer StateError: the socket may be broken.
        // Simplified rollback for illustration purposes.
        c.state = StateConnected
        return err
    }

    for _, h := range c.handlers {
        h.OnClose()
    }

    c.state = StateClosed
    return nil
}

func (c *Connection) Send(data []byte) error {
    c.mu.Lock()
    defer c.mu.Unlock()

    if c.state != StateConnected {
        return errors.New("not connected")
    }
    _, err := c.socket.Write(data)
    return err
}

// Illustrative snippet — not a complete program
// Original: Data race on lastError
type Service struct {
    lastError error
}

func (s *Service) DoWork() error {
    err := s.work()
    s.lastError = err  // DATA RACE
    return err
}

func (s *Service) LastError() error {
    return s.lastError  // DATA RACE
}

// Illustrative snippet — not a complete program
// ✗ BROKEN "fix": atomic.Value doesn't solve the real problem
type Service struct {
    lastError atomic.Value  // Stores error
}

func (s *Service) DoWork() error {
    err := s.work()
    s.lastError.Store(err)
    return err
}

func (s *Service) LastError() error {
    if v := s.lastError.Load(); v != nil {
        return v.(error)
    }
    return nil
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Define the semantics clearly
type Service struct {
    mu          sync.Mutex
    errors      []error        // All errors from current batch
    lastError   error          // Most recent error (any worker)
    errorCount  int            // Total errors
}

func (s *Service) RecordError(err error) {
    s.mu.Lock()
    defer s.mu.Unlock()

    s.errors = append(s.errors, err)
    s.lastError = err
    s.errorCount++
}

func (s *Service) ErrorSummary() ([]error, error, int) {
    s.mu.Lock()
    defer s.mu.Unlock()

    // Return consistent snapshot
    errorsCopy := make([]error, len(s.errors))
    copy(errorsCopy, s.errors)
    return errorsCopy, s.lastError, s.errorCount
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Modifying data through atomic pointer
type Config struct {
    Timeout   time.Duration
    Endpoints []string
}

type Server struct {
    config atomic.Pointer[Config]
}

func (s *Server) AddEndpoint(endpoint string) {
    cfg := s.config.Load()
    cfg.Endpoints = append(cfg.Endpoints, endpoint)  // DATA RACE!
    // Other goroutines are reading cfg.Endpoints right now
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Create new config, never modify existing
func (s *Server) AddEndpoint(endpoint string) {
    for {
        old := s.config.Load()

        // Deep copy the slice
        newEndpoints := make([]string, len(old.Endpoints)+1)
        copy(newEndpoints, old.Endpoints)
        newEndpoints[len(old.Endpoints)] = endpoint

        newCfg := &Config{
            Timeout:   old.Timeout,
            Endpoints: newEndpoints,
        }

        if s.config.CompareAndSwap(old, newCfg) {
            return
        }
    }
}

// Illustrative snippet — not a complete program
type Config struct {
    Features map[string]bool
}

// ✗ BROKEN: Map modification through atomic pointer
func (s *Server) EnableFeature(name string) {
    cfg := s.config.Load()
    cfg.Features[name] = true  // DATA RACE on map!
}

// ✓ CORRECT: Clone the map
func (s *Server) EnableFeature(name string) {
    for {
        old := s.config.Load()

        newFeatures := make(map[string]bool, len(old.Features)+1)
        for k, v := range old.Features {
            newFeatures[k] = v
        }
        newFeatures[name] = true

        newCfg := &Config{Features: newFeatures}

        if s.config.CompareAndSwap(old, newCfg) {
            return
        }
    }
}

// Illustrative snippet — not a complete program
// ✗ BAD: Counters share cache line, causing hidden contention
type Counters struct {
    reads   atomic.Int64  // These are likely in the same
    writes  atomic.Int64  // 64-byte cache line
    errors  atomic.Int64
    retries atomic.Int64
}

// Illustrative snippet — not a complete program
// ✓ BETTER: Pad to separate cache lines
type Counters struct {
    reads   atomic.Int64
    _pad1   [56]byte      // Fills rest of 64-byte cache line
    writes  atomic.Int64
    _pad2   [56]byte
    errors  atomic.Int64
    _pad3   [56]byte
    retries atomic.Int64
    _pad4   [56]byte
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: Inconsistent access patterns
type Server struct {
    requestCount atomic.Int64
    config       *Config  // Sometimes accessed without synchronization
}

func (s *Server) HandleRequest() {
    s.requestCount.Add(1)  // Atomic
    // Bug: Reading config without synchronization elsewhere
}

func (s *Server) UpdateConfig(c *Config) {
    s.config = c  // Non-atomic write!
}

func (s *Server) GetConfig() *Config {
    return s.config  // Non-atomic read!
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Consistent atomic access
type Server struct {
    requestCount atomic.Int64
    config       atomic.Pointer[Config]  // All access is atomic
}

func (s *Server) UpdateConfig(c *Config) {
    s.config.Store(c)  // Atomic write
}

func (s *Server) GetConfig() *Config {
    return s.config.Load()  // Atomic read
}

// Illustrative snippet — not a complete program
// ✗ UNNECESSARY: Atomics for rarely-accessed config
type App struct {
    debugMode atomic.Bool  // Checked once at startup
}

func main() {
    var app App
    app.debugMode.Store(os.Getenv("DEBUG") == "true")
    // ... app runs, debugMode checked occasionally ...
}

// Illustrative snippet — not a complete program
// ✗ WASTEFUL: Busy polling
func (s *Server) WaitForShutdown() {
    for !s.shutdown.Load() {
        time.Sleep(10 * time.Millisecond)  // Adds up to 10ms latency
    }
}

// ✓ BETTER: Block until signaled
func (s *Server) WaitForShutdown() {
    <-s.shutdownCh  // parks the goroutine; no CPU, instant wake
}

// Illustrative snippet — not a complete program
type RateLimiter struct {
    requests atomic.Int64
    window   atomic.Int64  // Unix timestamp of window start
    limit    int64
}

func (r *RateLimiter) Allow() bool {
    now := time.Now().Unix()

    // Reset if new window
    if now > r.window.Load() {
        r.window.Store(now)
        r.requests.Store(0)
    }

    if r.requests.Load() < r.limit {
        r.requests.Add(1)
        return true
    }
    return false
}

// Illustrative snippet — not a complete program
type Cache struct {
    data atomic.Pointer[map[string]string]
}

func (c *Cache) Set(key, value string) {
    m := c.data.Load()
    if m == nil {
        m = &map[string]string{}
        c.data.Store(m)
    }
    (*m)[key] = value
}

func (c *Cache) Get(key string) string {
    m := c.data.Load()
    if m == nil {
        return ""
    }
    return (*m)[key]
}

// Illustrative snippet — not a complete program
type Server struct {
    workerCount atomic.Int32
    shutdown    atomic.Bool
}

func (s *Server) Shutdown() {
    s.shutdown.Store(true)

    // Wait for workers to finish
    for s.workerCount.Load() > 0 {
        time.Sleep(10 * time.Millisecond)
    }

    log.Println("shutdown complete")
}

func (s *Server) worker() {
    s.workerCount.Add(1)
    defer s.workerCount.Add(-1)

    for !s.shutdown.Load() {
        // Do work
    }
}