Chapter 9: Mutexes

// Illustrative snippet — not a complete program
// ✓ Atomic: Single independent counter
var requests atomic.Int64
requests.Add(1)

// ✓ Mutex: Counter with related metadata
type Counter struct {
    mu        sync.Mutex
    value     int
    lastReset time.Time  // Invariant: updated together with value
}

// Illustrative snippet — not a complete program
type Transaction struct {
    Type   string
    Amount int
    Time   time.Time
}

type Account struct {
    mu           sync.Mutex
    balance      int
    transactions []Transaction
}

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

    // Invariant: transactions must reflect all balance changes
    a.balance += amount
    a.transactions = append(a.transactions, Transaction{
        Type:   "deposit",
        Amount: amount,
        Time:   time.Now(),
    })
    // Both fields updated atomically—invariant preserved
}

// Illustrative snippet — not a complete program
type Cache struct {
    mu   sync.Mutex  // RWMutex for reads: §9.3
    data map[string][]byte
}

func NewCache() *Cache {
    return &Cache{data: make(map[string][]byte)}
}

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

func (c *Cache) Set(key string, value []byte) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key] = value
}

// Illustrative snippet — not a complete program
func producer(out chan<- *Job) {
    for {
        job := createJob()  // Producer owns this
        out <- job          // Ownership transfers
        // Producer must not use 'job' after send
    }
}

func consumer(in <-chan *Job) {
    for job := range in {
        process(job)  // Consumer now owns it
    }
}

// Illustrative snippet — not a complete program
func worker(id int, jobs <-chan Job, results chan<- Result) {
    for job := range jobs {
        results <- process(job)
    }
}

// Illustrative snippet — not a complete program
func worker(id int, done <-chan struct{}, jobs <-chan Job) {
    for {
        select {
        case <-done:
            return  // Shutdown broadcast received
        case job := <-jobs:
            process(job)
        }
    }
}
// close(done) wakes all workers simultaneously

// Illustrative snippet — not a complete program
// ✗ AWKWARD: Channel for simple state protection
type Counter struct {
    inc   chan struct{}
    value chan chan int
    done  chan struct{}
}

func NewCounter() *Counter {
    c := &Counter{
        inc:   make(chan struct{}),
        value: make(chan chan int),
        done:  make(chan struct{}),
    }
    go func() {
        count := 0
        for {
            select {
            case <-c.inc:
                count++
            case reply := <-c.value:
                reply <- count
            case <-c.done:
                return
            }
        }
    }()  // Dedicated goroutine just to protect an int!
    return c
}

func (c *Counter) Increment() { c.inc <- struct{}{} }

func (c *Counter) Value() int {
    reply := make(chan int)
    c.value <- reply
    return <-reply  // Allocation + channel ops for a simple read
}

func (c *Counter) Close() { close(c.done) }

// All this machinery for a simple integer!
// Compare to the mutex version: simpler, clearer, less overhead.

// Illustrative snippet — not a complete program
// ✗ AWKWARD: Mutex for work distribution
type WorkQueue struct {
    mu   sync.Mutex
    jobs []Job
}

func (wq *WorkQueue) TryGet() (Job, bool) {
    wq.mu.Lock()
    defer wq.mu.Unlock()
    if len(wq.jobs) == 0 {
        return Job{}, false
    }
    job := wq.jobs[0]
    wq.jobs = wq.jobs[1:]
    return job, true
}

// Workers must poll:
func worker(wq *WorkQueue) {
    for {
        job, ok := wq.TryGet()
        if !ok {
            time.Sleep(10 * time.Millisecond)  // Wastes CPU
            continue
        }
        process(job)
    }
}

// Illustrative snippet — not a complete program
// ✓ CLEAR: Channel for work distribution
func worker(jobs <-chan Job) {
    for job := range jobs {  // Blocks until work arrives
        process(job)
    }
}

// Illustrative snippet — not a complete program
type MetricsCollector struct {
    // Channels: Communication
    events   chan Event
    shutdown chan struct{}

    // Mutex: State protection
    mu       sync.Mutex
    counters map[string]int64
}

func NewMetricsCollector() *MetricsCollector {
    return &MetricsCollector{
        events:   make(chan Event, 100),
        shutdown: make(chan struct{}),
        counters: make(map[string]int64),
    }
}

func (mc *MetricsCollector) Run() {
    for {
        select {
        case event := <-mc.events:
            mc.recordEvent(event)
        case <-mc.shutdown:
            return
        }
    }
}

// recordEvent and GetCount may be called concurrently
// from different goroutines, so both must hold the lock
// to prevent data races on the counters map.
func (mc *MetricsCollector) recordEvent(event Event) {
    mc.mu.Lock()
    mc.counters[event.Name]++
    mc.mu.Unlock()
}

// GetCount can be called from any goroutine to read current metrics.
func (mc *MetricsCollector) GetCount(name string) int64 {
    mc.mu.Lock()
    defer mc.mu.Unlock()
    return mc.counters[name]
}

func (mc *MetricsCollector) Record(event Event) {
    select {
    case mc.events <- event:
    default:
        // Drop if buffer full
    }
}

// Illustrative snippet — not a complete program
var mu sync.Mutex

mu.Lock()    // Acquire exclusive access
// ... critical section ...
mu.Unlock()  // Release exclusive access

// Illustrative snippet — not a complete program
type Counter struct {
    mu    sync.Mutex  // Zero value is valid
    value int
}

// Works immediately—no constructor required
counter := &Counter{}
counter.mu.Lock()
counter.value++
counter.mu.Unlock()

// Illustrative snippet — not a complete program
// ✗ DON’T: Pointer to mutex is unnecessary
type Counter struct {
    mu    *sync.Mutex  // Extra allocation
    value int
}

func NewCounter() *Counter {
    return &Counter{
        mu: &sync.Mutex{},  // Unnecessary
    }
}

// ✓ DO: Embed directly (zero value works)
type Counter struct {
    mu    sync.Mutex  // Ready to use
    value int
}

// Illustrative snippet — not a complete program
mu.Lock()    // Acquires immediately (starts unlocked)
// ... critical section ...
mu.Unlock()

// From another goroutine:
mu.Lock()    // Blocks if someone else holds the lock

// Illustrative snippet — not a complete program
mu.Lock()
// ... critical section ...
mu.Unlock()  // Releases lock, wakes a waiter

// Illustrative snippet — not a complete program
var mu sync.Mutex
mu.Unlock()  // panic: sync: unlock of unlocked mutex

// Illustrative snippet — not a complete program
mu.Lock()
mu.Unlock()
mu.Unlock()  // panic: sync: unlock of unlocked mutex

// Illustrative snippet — not a complete program
func (c *Counter) Increment() {
    c.mu.Lock()        // ─┐
    c.value++          //  ├─ Critical section
    c.mu.Unlock()      // ─┘
}

// Illustrative snippet — not a complete program
func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.value  // Reads need synchronization too
}

// Illustrative snippet — not a complete program
var (
    mu    sync.Mutex
    data1 string
    data2 int
)

// Goroutine A
mu.Lock()
data1 = "hello"
data2 = 42
mu.Unlock()        // Happens-before...

// Goroutine B
mu.Lock()          // ...this Lock()
fmt.Println(data1) // Guaranteed: "hello"
fmt.Println(data2) // Guaranteed: 42
mu.Unlock()

// Illustrative snippet — not a complete program
func (c *Counter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()  // Runs when function returns

    c.value++
}

// Illustrative snippet — not a complete program
// ✗ FRAGILE: Manual unlock on each path
func (a *Account) Withdraw(amount int) error {
    a.mu.Lock()

    if amount <= 0 {
        a.mu.Unlock()  // Don’t forget!
        return errors.New("invalid amount")
    }

    if a.balance < amount {
        a.mu.Unlock()  // Don’t forget!
        return errors.New("insufficient funds")
    }

    a.balance -= amount
    a.mu.Unlock()  // Don’t forget!
    return nil
}

// Illustrative snippet — not a complete program
// ✓ ROBUST: defer handles all paths
func (a *Account) Withdraw(amount int) error {
    a.mu.Lock()
    defer a.mu.Unlock()  // Handles ALL paths

    if amount <= 0 {
        return errors.New("invalid amount")
    }

    if a.balance < amount {
        return errors.New("insufficient funds")
    }

    a.balance -= amount
    return nil
}

// Illustrative snippet — not a complete program
func (c *Cache) Process(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()

    value := c.data[key]
    result := transform(value)  // What if this panics?
    c.data[key] = result
}

// Illustrative snippet — not a complete program
func (x *Type) Method() {
    x.mu.Lock()
    defer x.mu.Unlock()

    // All work here
}

// Illustrative snippet — not a complete program
func (c *Cache) GetOrLoad(key string) ([]byte, error) {
    c.mu.Lock()
    if value, ok := c.data[key]; ok {
        c.mu.Unlock()  // Release before return
        return value, nil
    }
    c.mu.Unlock()  // Release before slow I/O

    // Load without holding lock
    value, err := loadFromDatabase(key)
    if err != nil {
        return nil, err
    }

    // Re-acquire to store
    c.mu.Lock()
    c.data[key] = value
    c.mu.Unlock()

    return value, nil
}

// Illustrative snippet — not a complete program
func (c *Cache) GetOrLoad(key string) ([]byte, error) {
    if value, ok := c.tryGet(key); ok {
        return value, nil
    }
    return c.loadAndCache(key)
}

func (c *Cache) tryGet(key string) ([]byte, bool) {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.data[key]
}

func (c *Cache) loadAndCache(key string) ([]byte, error) {
    value, err := loadFromDatabase(key)
    if err != nil {
        return nil, err
    }
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key] = value
    return value, nil
}

// Illustrative snippet — not a complete program
func (c *Counter) IncrementHot() {
    c.mu.Lock()
    c.value++
    c.mu.Unlock()
}

// Illustrative snippet — not a complete program
func (a *Account) Transfer(to *Account, amount int) {
    a.mu.Lock()
    defer a.mu.Unlock()

    a.withdraw(amount)  // DEADLOCK!
}

func (a *Account) withdraw(amount int) {
    a.mu.Lock()         // DEADLOCK: already locked!
    defer a.mu.Unlock()
    a.balance -= amount
}

// Illustrative snippet — not a complete program
// Public: acquires lock
func (a *Account) Withdraw(amount int) {
    a.mu.Lock()
    defer a.mu.Unlock()
    a.withdrawLocked(amount)
}

// Private: caller must hold lock
func (a *Account) withdrawLocked(amount int) {
    a.balance -= amount
}

// Illustrative snippet — not a complete program
if mu.TryLock() {
    defer mu.Unlock()
    // Got the lock—proceed
} else {
    // Lock was held, didn’t wait
}

// Illustrative snippet — not a complete program
// ✗ WRONG: Polling with TryLock
for !mu.TryLock() {
    time.Sleep(10 * time.Millisecond)
}

// ✓ CORRECT: Just block
mu.Lock()  // Goroutine parks, wakes when available

// Illustrative snippet — not a complete program
// ✗ BAD: Holds lock during slow operation
func (c *Cache) GetOrCompute(key string) Value {
    c.mu.Lock()
    defer c.mu.Unlock()

    if val, ok := c.data[key]; ok {
        return val
    }

    val := expensiveComputation(key)
    c.data[key] = val  // Lock held entire time!
    return val
}

// Complete Example: Thread-Safe Counter
// Run: go run -race counter.go

package main

import (
    "fmt"
    "sync"
)

type Counter struct {
    mu    sync.Mutex
    value int
}

func (c *Counter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.value++
}

func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.value
}

func main() {
    counter := &Counter{}
    var wg sync.WaitGroup

    // Launch 1000 goroutines, each incrementing 100 times
    for i := 0; i < 1000; i++ {
        wg.Go(func() {
            for j := 0; j < 100; j++ {
                counter.Increment()
            }
        })
    }

    wg.Wait()
    fmt.Printf("Final count: %d (expected: 100000)\n",
        counter.Value())
}

// Illustrative snippet — not a complete program
// ✗ WRONG: Value receiver copies the mutex
func (c Counter) Value() int {
    c.mu.Lock()    // Locks the COPY’s mutex
    defer c.mu.Unlock()
    return c.value
}

// ✓ CORRECT: Pointer receiver
func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.value
}

// Illustrative snippet — not a complete program
// ✗ CRITICAL BUG: Deadlocks on iteration 2
func (s *Store) ProcessItems(items []Item) {
    for _, item := range items {
        s.mu.Lock()
        defer s.mu.Unlock()  // Schedules for END OF FUNCTION
        s.process(item)
    }
    // All defers would execute here—but we never get here
}

// Illustrative snippet — not a complete program
Iteration 1: Lock() succeeds, defer #1 scheduled
Iteration 2: Lock() called—DEADLOCK!
             (still holding lock from iteration 1)
             defer #1 never runs because we’re blocked
             Program hangs forever—no panic, no error

A trace of defer inside a loop. On the first iteration Lock succeeds and the deferred Unlock is scheduled — but scheduled for when the function returns, not when the iteration ends. On the second iteration Lock is called while the first iteration's lock is still held, so the goroutine blocks forever waiting for itself. If every goroutine is blocked the runtime prints a fatal error saying all goroutines are asleep; if any other goroutine is still running, the program simply hangs with no message.

// Illustrative snippet — not a complete program
// ✓ CORRECT: Helper function scopes the defer
func (s *Store) ProcessItems(items []Item) {
    for _, item := range items {
        s.processItem(item)
    }
}

func (s *Store) processItem(item Item) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.process(item)
}

// ✓ ALSO CORRECT: Manual unlock in loop
func (s *Store) ProcessItems(items []Item) {
    for _, item := range items {
        s.mu.Lock()
        s.process(item)
        s.mu.Unlock()
    }
}

// Illustrative snippet — not a complete program
// ✗ WRONG: Unsynchronized read
func (c *Counter) Value() int {
    return c.value  // DATA RACE
}

// ✓ CORRECT: Lock reads too
func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.value
}

// Illustrative snippet — not a complete program
type ConfigCache struct {
    mu     sync.Mutex
    config Config
}

func (c *ConfigCache) Get() Config {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.config  // Just reading—but blocks all other readers!
}

func (c *ConfigCache) Update(cfg Config) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.config = cfg
}

// Illustrative snippet — not a complete program
type ConfigCache struct {
    mu     sync.RWMutex  // Changed from sync.Mutex
    config Config
}

func (c *ConfigCache) Get() Config {
    c.mu.RLock()         // Read lock—allows concurrent readers
    defer c.mu.RUnlock()
    return c.config
}

func (c *ConfigCache) Update(cfg Config) {
    c.mu.Lock()          // Write lock—exclusive access
    defer c.mu.Unlock()
    c.config = cfg
}

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

// Read operation: use RLock/RUnlock
func (c *Cache) Get(key string) ([]byte, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    val, ok := c.data[key]
    return val, ok
}

// Write operation: use Lock/Unlock
func (c *Cache) Set(key string, value []byte) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key] = value
}

// Another write operation
func (c *Cache) Delete(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    delete(c.data, key)
}

// Illustrative snippet — not a complete program
// ✗ Poor fit: 50% writes negates RWMutex benefit
type Counter struct {
    mu    sync.RWMutex  // Just use sync.Mutex
    value int
}

func (c *Counter) Increment() {  // Write: ~50% of calls
    c.mu.Lock()
    c.value++
    c.mu.Unlock()
}

func (c *Counter) Value() int {  // Read: ~50% of calls
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.value
}

// Illustrative snippet — not a complete program
// ✗ May not benefit: Critical section is trivial
func (c *Config) GetTimeout() time.Duration {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.timeout  // Single field read—tiny
}

// Illustrative snippet — not a complete program
// ✗ Low concurrency: RWMutex overhead without benefit
// Only 2 goroutines ever access this
type SingletonCache struct {
    mu   sync.RWMutex  // Overkill—use sync.Mutex
    data map[string]string
}

// Illustrative snippet — not a complete program
// ✗ DEADLOCK: Cannot upgrade RLock to Lock
func (c *Cache) GetOrCreate(key string) *Entry {
    c.mu.RLock()
    if entry, ok := c.data[key]; ok {
        c.mu.RUnlock()
        return entry
    }
    // Key not found—need to create
    c.mu.Lock()  // DEADLOCK! Waiting for readers (including us)
    defer c.mu.Unlock()
    // ...
}

// Illustrative snippet — not a complete program
// ✓ CORRECT: Release RLock before acquiring Lock
func (c *Cache) GetOrCreate(key string) *Entry {
    // First check with read lock
    c.mu.RLock()
    if entry, ok := c.data[key]; ok {
        c.mu.RUnlock()
        return entry
    }
    c.mu.RUnlock()  // Must release before write lock

    // Acquire write lock
    c.mu.Lock()
    defer c.mu.Unlock()

    // CRITICAL: Must check again—state may have changed!
    if entry, ok := c.data[key]; ok {
        return entry  // Another goroutine created it
    }

    // Now safe to create
    entry := &Entry{Key: key}
    c.data[key] = entry
    return entry
}

// Illustrative snippet — not a complete program
if c.mu.TryRLock() {
    defer c.mu.RUnlock()
    // Got read lock
} else {
    // Lock held by writer—do something else
}

if c.mu.TryLock() {
    defer c.mu.Unlock()
    // Got write lock
} else {
    // Lock held—do something else
}

// Illustrative snippet — not a complete program
func (c *Cache) ProcessAll() {
    // Take snapshot under read lock
    c.mu.RLock()
    snapshot := make(map[string][]byte, len(c.data))
    for k, v := range c.data {
        snapshot[k] = v  // Safe when values are replaced,
                         // not mutated in place
    }
    c.mu.RUnlock()

    // Process without holding lock
    for key, value := range snapshot {
        expensiveProcess(key, value)
    }
}

// Illustrative snippet — not a complete program
type Stats struct {
    mu       sync.RWMutex
    requests int64
    errors   int64
    bytes    int64
}

func (s *Stats) Snapshot() (requests, errors, bytes int64) {
    s.mu.RLock()
    defer s.mu.RUnlock()
    return s.requests, s.errors, s.bytes  // Consistent snapshot
}

func (s *Stats) RecordRequest(size int64, err error) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.requests++
    s.bytes += size
    if err != nil {
        s.errors++
    }
}

// Illustrative snippet — not a complete program
// ✗ DATA RACE: Modifying under read lock
func (c *Cache) BadIncrement(key string) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    c.data[key]++  // DATA RACE! Other readers see partial update
}

// ✓ CORRECT: Use write lock for modifications
func (c *Cache) GoodIncrement(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key]++
}

// Illustrative snippet — not a complete program
// ✗ PANIC: Wrong unlock method
func (c *Cache) Bad() {
    c.mu.RLock()
    defer c.mu.Unlock()  // WRONG! Should be RUnlock()
    // ...
}

// ✓ CORRECT: Matching pairs
func (c *Cache) Good() {
    c.mu.RLock()
    defer c.mu.RUnlock()  // Correct
    // ...
}

// Illustrative snippet — not a complete program
// ✗ DEFEATS PURPOSE: Write lock for read-only operation
func (c *Cache) Get(key string) []byte {
    c.mu.Lock()         // Should be RLock!
    defer c.mu.Unlock()
    return c.data[key]
}

// ✓ CORRECT: Read lock for read operations
func (c *Cache) Get(key string) []byte {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.data[key]
}

// Illustrative snippet — not a complete program
type Entry struct {
    Name, Region string
    Weight       int
}

// A read that does real work. §9.3's own rule is "> 100ns" — a
// single map lookup is the case where RWMutex does not pay.
func lookup(m map[string]Entry, key string) int {
    total := 0
    for i := 0; i < 40; i++ {
        if e, ok := m[fmt.Sprintf("%s-%d", key, i)]; ok {
            total += e.Weight + len(e.Region)
        }
    }
    return total
}

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

func (c *MutexCache) Get(key string) int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return lookup(c.data, key)
}

type RWMutexCache struct {
    mu   sync.RWMutex
    data map[string]Entry
}

func (c *RWMutexCache) Get(key string) int {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return lookup(c.data, key)
}

func BenchmarkMutexCache(b *testing.B) {
    cache := &MutexCache{data: makeTestData()}
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            cache.Get("key")
        }
    })
}

func BenchmarkRWMutexCache(b *testing.B) {
    cache := &RWMutexCache{data: makeTestData()}
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            cache.Get("key")
        }
    })
}

// Illustrative snippet — not a complete program
// Monitor pattern: State + synchronization encapsulated together
type Counter struct {
    mu    sync.Mutex  // Synchronization
    value int         // Protected state
}

// All access through methods
func (c *Counter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.value++
}

func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.value
}

// Illustrative snippet — not a complete program
// ✗ BAD: Exported mutex and data
type Cache struct {
    Mu   sync.RWMutex          // Exported!
    Data map[string][]byte     // Exported!
}

// Caller can bypass synchronization:
cache.Data["key"] = value      // No lock—DATA RACE!

// Or lock incorrectly:
cache.Mu.Lock()
value := cache.Data["key"]
// Forgot to unlock—all future operations block forever

// Illustrative snippet — not a complete program
// ✓ GOOD: Unexported mutex and data, exported methods
type Cache struct {
    mu   sync.RWMutex          // Unexported
    data map[string][]byte     // Unexported
}

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

func (c *Cache) Set(key string, value []byte) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key] = value
}

// Callers MUST use methods—no way to access data without lock

// Illustrative snippet — not a complete program
type Account struct {
    // Mutex first, then what it protects
    mu           sync.Mutex
    balance      int
    transactions []Transaction

    // Unprotected fields after a blank line
    id   string
    name string
}

// Illustrative snippet — not a complete program
type Server struct {
    // Configuration (immutable after construction)
    addr    string
    timeout time.Duration

    // Connection state (protected by connMu)
    connMu sync.RWMutex
    conns  map[string]*Conn

    // Metrics (protected by metricsMu)
    metricsMu sync.Mutex
    requests  int64
    errors    int64
}

// Illustrative snippet — not a complete program
// Single mutex—use 'mu'
type Counter struct {
    mu    sync.Mutex
    value int
}

// Multiple mutexes—use descriptive names
type Server struct {
    connMu    sync.RWMutex
    conns     map[string]*Conn

    metricsMu sync.Mutex
    requests  int64
}

// Illustrative snippet — not a complete program
type Account struct {
    mu           sync.Mutex
    balance      int
    transactions []Transaction
}

// Public: acquires lock
func (a *Account) Deposit(amount int) {
    a.mu.Lock()
    defer a.mu.Unlock()
    a.depositLocked(amount)
}

// Public: acquires lock
func (a *Account) Withdraw(amount int) error {
    a.mu.Lock()
    defer a.mu.Unlock()
    return a.withdrawLocked(amount)
}

// Public: acquires lock, uses helpers for atomicity
func (a *Account) Transfer(to *Account, amount int) error {
    a.mu.Lock()
    defer a.mu.Unlock()

    if err := a.withdrawLocked(amount); err != nil {
        return err
    }

    to.mu.Lock()
    defer to.mu.Unlock()
    to.depositLocked(amount)

    return nil
}

// Private helper: caller MUST hold lock
func (a *Account) depositLocked(amount int) {
    a.balance += amount
    a.transactions = append(a.transactions, Transaction{
        Type:   "deposit",
        Amount: amount,
        Time:   time.Now(),
    })
}

// Private helper: caller MUST hold lock
func (a *Account) withdrawLocked(amount int) error {
    if a.balance < amount {
        return errors.New("insufficient funds")
    }
    a.balance -= amount
    a.transactions = append(a.transactions, Transaction{
        Type:   "withdraw",
        Amount: amount,
        Time:   time.Now(),
    })
    return nil
}

// Illustrative snippet — not a complete program
func (c *Cache) GetConfig() Config {
    c.mu.RLock()
    defer c.mu.RUnlock()

    // Return a copy—caller can't modify our internal state
    return c.config  // Config is a struct, so this copies
}

// Illustrative snippet — not a complete program
func (c *Cache) GetEntry(key string) *Entry {
    c.mu.RLock()
    defer c.mu.RUnlock()

    // Returns pointer to internal data!
    // Caller could modify without holding lock—document the contract
    return c.entries[key]
}

// Illustrative snippet — not a complete program
func (r *Registry) GetAllServices() []*Service {
    r.mu.RLock()
    defer r.mu.RUnlock()

    // Copy the slice—caller can't affect our internal slice
    result := make([]*Service, 0, len(r.services))
    for _, svc := range r.services {
        result = append(result, svc)
    }
    return result
}

// Illustrative snippet — not a complete program
// Deep copy (if Service is safe to copy)
result := make([]Service, len(r.services))
for i, svc := range r.services {
    result[i] = *svc  // Copy the Service struct
}

// Illustrative snippet — not a complete program
type Pool struct {
    mu        sync.Mutex
    available []*Conn
    inUse     map[*Conn]bool
    total     int  // Invariant: total == len(available) + len(inUse)
}

func (p *Pool) Acquire() (*Conn, error) {
    p.mu.Lock()
    defer p.mu.Unlock()

    if len(p.available) == 0 {
        return nil, errors.New("no connections available")
    }

    // Temporarily breaks invariant
    conn := p.available[len(p.available)-1]
    p.available = p.available[:len(p.available)-1]

    // Restores invariant
    p.inUse[conn] = true

    // Invariant holds: total == len(available) + len(inUse)
    return conn, nil
}

func (p *Pool) Release(conn *Conn) {
    p.mu.Lock()
    defer p.mu.Unlock()

    delete(p.inUse, conn)
    p.available = append(p.available, conn)
    // Invariant maintained
}

// Illustrative snippet — not a complete program
func (p *Pool) Acquire() (*Conn, error) {
    p.mu.Lock()
    defer p.mu.Unlock()

    // Assert invariant (remove in production or use build tags)
    if p.total != len(p.available)+len(p.inUse) {
        panic("pool invariant violated")
    }

    // ... rest of implementation
}

// Illustrative snippet — not a complete program
// Embedding: Lock/Unlock become methods of Counter
type Counter struct {
    sync.Mutex  // Embedded
    value int
}

counter := &Counter{}
counter.Lock()    // Works—but exported!
counter.Unlock()

// Illustrative snippet — not a complete program
// ✗ BAD: Embedding exports Lock/Unlock
type Counter struct {
    sync.Mutex
    value int
}

// ✓ GOOD: Named field keeps Lock/Unlock private
type Counter struct {
    mu    sync.Mutex
    value int
}

// Illustrative snippet — not a complete program
func (c *Cache) GetOrLoad(key string) ([]byte, error) {
    c.mu.RLock()
    val, ok := c.data[key]
    c.mu.RUnlock()  // ← Gap here

    if ok {
        return val, nil
    }

    val, err := loadFromDatabase(key)  // ← May run concurrently
    if err != nil {
        return nil, err
    }

    c.mu.Lock()
    c.data[key] = val  // ← Last write wins
    c.mu.Unlock()

    return val, nil
}

// Illustrative snippet — not a complete program
func (c *Cache) GetOrCompute(key string) Value {
    // First check (read lock)
    c.mu.RLock()
    if val, ok := c.data[key]; ok {
        c.mu.RUnlock()
        return val
    }
    c.mu.RUnlock()

    // Compute without holding lock
    computed := expensiveComputation(key)

    // Second check (write lock) — CRITICAL
    c.mu.Lock()
    defer c.mu.Unlock()

    if val, ok := c.data[key]; ok {
        return val  // Another goroutine computed it!
    }

    c.data[key] = computed
    return computed
}

// Illustrative snippet — not a complete program
// Each method is thread-safe...
cache.Get(key)
cache.Set(key, value)

// ...but this sequence is NOT atomic:
val, ok := cache.Get(key)
if !ok {
    val = compute(key)
    cache.Set(key, val)  // Race: another goroutine might have set it
}

// Illustrative snippet — not a complete program
// Atomic get-or-set operation
func (c *Cache) GetOrSet(
    key string, value []byte,
) (actual []byte, loaded bool) {
    c.mu.Lock()
    defer c.mu.Unlock()

    if existing, ok := c.data[key]; ok {
        return existing, true  // Was already present
    }

    c.data[key] = value
    return value, false  // We stored it
}

// Atomic increment-if-exists (for a type with map[string]int data)
func (c *HitCounter) IncrementIfExists(
    key string,
) (newValue int, ok bool) {
    c.mu.Lock()
    defer c.mu.Unlock()

    if val, exists := c.data[key]; exists {
        c.data[key] = val + 1
        return val + 1, true
    }
    return 0, false
}

// Atomic compare-and-swap
func (c *Cache) CompareAndSwap(key string, old, new []byte) bool {
    c.mu.Lock()
    defer c.mu.Unlock()

    if current, ok := c.data[key]; ok && bytes.Equal(current, old) {
        c.data[key] = new
        return true
    }
    return false
}

// Illustrative snippet — not a complete program
// ✗ DANGEROUS: Callback under lock
func (r *Registry) Notify(event string) {
    r.mu.Lock()
    defer r.mu.Unlock()

    if handler, ok := r.handlers[event]; ok {
        handler()  // What if handler calls back into Registry?
    }
}

// Illustrative snippet — not a complete program
// ✓ SAFE: Release lock before callback
func (r *Registry) Notify(event string) {
    r.mu.RLock()
    handler, ok := r.handlers[event]
    r.mu.RUnlock()  // Release before callback

    if ok {
        handler()  // Safe—no lock held
    }
}

// Illustrative snippet — not a complete program
func (r *Registry) NotifyAll(event string) {
    // Copy handlers under lock
    r.mu.RLock()
    handlers := make([]func(), len(r.handlers[event]))
    copy(handlers, r.handlers[event])
    r.mu.RUnlock()

    // Call without lock
    for _, h := range handlers {
        h()
    }
}

// Illustrative snippet — not a complete program
// ✗ BAD: Lock held during network call
func (c *Cache) GetOrFetch(key string) ([]byte, error) {
    c.mu.Lock()
    defer c.mu.Unlock()

    if val, ok := c.data[key]; ok {
        return val, nil
    }

    // Lock held for entire network call (100ms+)!
    val, err := fetchFromRemote(key)
    if err != nil {
        return nil, err
    }

    c.data[key] = val
    return val, nil
}

// Illustrative snippet — not a complete program
// ✓ GOOD: Minimal critical section
func (c *Cache) GetOrFetch(key string) ([]byte, error) {
    // Quick check under read lock
    c.mu.RLock()
    val, ok := c.data[key]
    c.mu.RUnlock()

    if ok {
        return val, nil
    }

    // Fetch without holding lock
    val, err := fetchFromRemote(key)
    if err != nil {
        return nil, err
    }

    // Brief write lock to store
    c.mu.Lock()
    c.data[key] = val  // Race condition—see double-check
    c.mu.Unlock()

    return val, nil
}

// Illustrative snippet — not a complete program
// Coarse-grained: Simple, safe
type Server struct {
    mu      sync.Mutex
    config  Config
    conns   map[string]*Conn
    metrics Metrics
}

// Fine-grained: Higher concurrency, more complexity
type Server struct {
    configMu  sync.RWMutex
    config    Config

    connsMu   sync.RWMutex
    conns     map[string]*Conn

    metricsMu sync.Mutex
    metrics   Metrics
}

// Illustrative snippet — not a complete program
import _ "net/http/pprof"

func main() {
    // Enable mutex profiling
    runtime.SetMutexProfileFraction(1)

    // Start pprof server
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()

    // ... your application ...
}

// Illustrative snippet — not a complete program
type Counter struct {
    mu    sync.Mutex
    value int
}

// Zero value works fine
counter := &Counter{}
counter.Increment()  // Works immediately

// Illustrative snippet — not a complete program
type Cache struct {
    mu   sync.RWMutex
    data map[string][]byte  // Maps must be initialized!
}

// ✗ WRONG: Zero value has nil map
cache := &Cache{}
cache.Set("key", value)  // panic: assignment to nil map

// ✓ CORRECT: Use constructor
func NewCache() *Cache {
    return &Cache{
        data: make(map[string][]byte),
    }
}

cache := NewCache()
cache.Set("key", value)  // Works

// Illustrative snippet — not a complete program
func TestCounterConcurrent(t *testing.T) {
    counter := &Counter{}
    var wg sync.WaitGroup

    goroutines := 100
    increments := 1000

    for i := 0; i < goroutines; i++ {
        wg.Go(func() {
            for j := 0; j < increments; j++ {
                counter.Increment()
            }
        })
    }

    wg.Wait()

    expected := goroutines * increments
    if got := counter.Value(); got != expected {
        t.Errorf("Expected %d, got %d", expected, got)
    }
}

// Illustrative snippet — not a complete program
func TestCacheStress(t *testing.T) {
    if testing.Short() {
        t.Skip("Skipping stress test in short mode")
    }

    cache := NewCache()
    var wg sync.WaitGroup

    // Concurrent readers and writers
    for i := 0; i < 50; i++ {
        // Writer
        wg.Go(func() {
            for j := 0; j < 1000; j++ {
                key := fmt.Sprintf("key-%d", i)
                cache.Set(key, []byte(fmt.Sprintf("value-%d", j)))
            }
        })

        // Reader
        wg.Go(func() {
            for j := 0; j < 1000; j++ {
                key := fmt.Sprintf("key-%d", i)
                cache.Get(key)
            }
        })
    }

    wg.Wait()
}

// Illustrative snippet — not a complete program
// Registry manages named services with thread-safe access.
type Registry struct {
    mu       sync.RWMutex
    services map[string]*Service
}

// Service represents a registered service.
type Service struct {
    Name     string
    Endpoint string
    healthy  bool
}

// NewRegistry creates an empty registry.
func NewRegistry() *Registry {
    return &Registry{
        services: make(map[string]*Service),
    }
}

// Register adds a service. Returns error if name already exists.
func (r *Registry) Register(svc *Service) error {
    r.mu.Lock()
    defer r.mu.Unlock()

    if _, exists := r.services[svc.Name]; exists {
        return fmt.Errorf("service %q already registered", svc.Name)
    }

    r.services[svc.Name] = svc
    return nil
}

// Unregister removes a service. Returns false if not found.
func (r *Registry) Unregister(name string) bool {
    r.mu.Lock()
    defer r.mu.Unlock()

    if _, exists := r.services[name]; !exists {
        return false
    }

    delete(r.services, name)
    return true
}

// Get retrieves a service by name.
func (r *Registry) Get(name string) (*Service, bool) {
    r.mu.RLock()
    defer r.mu.RUnlock()

    svc, ok := r.services[name]
    return svc, ok
}

// GetOrRegister returns existing service or registers new one.
// Uses double-check pattern to avoid duplicate registration.
func (r *Registry) GetOrRegister(svc *Service) *Service {
    // First check with read lock
    r.mu.RLock()
    if existing, ok := r.services[svc.Name]; ok {
        r.mu.RUnlock()
        return existing
    }
    r.mu.RUnlock()

    // Acquire write lock
    r.mu.Lock()
    defer r.mu.Unlock()

    // Double-check: another goroutine may have registered it
    if existing, ok := r.services[svc.Name]; ok {
        return existing
    }

    r.services[svc.Name] = svc
    return svc
}

// List returns all registered service names.
// Returns a copy to prevent caller from modifying internal state.
func (r *Registry) List() []string {
    r.mu.RLock()
    defer r.mu.RUnlock()

    names := make([]string, 0, len(r.services))
    for name := range r.services {
        names = append(names, name)
    }
    return names
}

// Count returns the number of registered services.
func (r *Registry) Count() int {
    r.mu.RLock()
    defer r.mu.RUnlock()
    return len(r.services)
}

// SetHealthy updates service health status.
func (r *Registry) SetHealthy(name string, healthy bool) bool {
    r.mu.Lock()
    defer r.mu.Unlock()

    svc, ok := r.services[name]
    if !ok {
        return false
    }
    svc.healthy = healthy
    return true
}

// GetHealthy returns only healthy services.
func (r *Registry) GetHealthy() []*Service {
    r.mu.RLock()
    defer r.mu.RUnlock()

    var healthy []*Service
    for _, svc := range r.services {
        if svc.healthy {
            healthy = append(healthy, svc)
        }
    }
    return healthy
}

// Illustrative snippet — not a complete program
func (a *Account) Transfer(to *Account, amount int) {
    a.mu.Lock()
    defer a.mu.Unlock()
    a.withdrawLocked(amount)
}

func (a *Account) withdrawLocked(amount int) {
    a.mu.Lock()  // ?
    defer a.mu.Unlock()
    a.balance -= amount
}

// Illustrative snippet — not a complete program
func (c *Counter) Value() int {
    return c.value  // "It's just a read!"
}

// Illustrative snippet — not a complete program
func (s *Store) ProcessAll(items []Item) {
    for _, item := range items {
        s.mu.Lock()
        defer s.mu.Unlock()
        s.process(item)
    }
}

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

// Illustrative snippet — not a complete program
c.mu.RLock()
// ... discovered we need to write ...
c.mu.Lock()  // Can we do this?

// Illustrative snippet — not a complete program
func (s *Server) GetStats() (requests int, errors int) {
    s.mu.RLock()
    requests = s.requests
    s.mu.RUnlock()

    s.mu.RLock()
    errors = s.errors
    s.mu.RUnlock()

    return requests, errors
}

// Illustrative snippet — not a complete program
func (c Counter) Value() int     // A: value receiver
func (c *Counter) Value() int    // B: pointer receiver

// Illustrative snippet — not a complete program
// Option A: Exported fields
type Registry struct {
    Mu       sync.RWMutex
    Services map[string]*Service
}

// Option B: Unexported fields with methods
type Registry struct {
    mu       sync.RWMutex
    services map[string]*Service
}
func (r *Registry) Get(name string) (*Service, bool) { ... }
func (r *Registry) Register(svc *Service) error { ... }

// Illustrative snippet — not a complete program
func (c *Cache) GetAll() map[string][]byte {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.data  // Return internal map
}

// Illustrative snippet — not a complete program
func (r *Registry) Notify(event string) {
    r.mu.Lock()
    defer r.mu.Unlock()

    if handler, ok := r.handlers[event]; ok {
        handler()
    }
}