
A mutex (mutual exclusion lock) ensures only one goroutine can access a critical section at a time. `sync.Mutex` provides exclusive locking; `sync.RWMutex` allows concurrent readers but exclusive writers.

<ExamplePair>
<ExampleProse>

Embed the mutex in the struct it protects. Lock before reading or writing shared state, and defer the unlock so it runs even on early return or panic.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
)

type SafeCounter struct {
    mu sync.Mutex
    v  map[string]int
}

func (c *SafeCounter) Inc(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.v[key]++
}

func (c *SafeCounter) Value(key string) int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.v[key]
}

func main() {
    c := SafeCounter{v: make(map[string]int)}

    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            c.Inc("key")
        }()
    }

    wg.Wait()
    fmt.Println(c.Value("key")) // always 1000
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Use `sync.RWMutex` when reads are far more frequent than writes. Multiple goroutines can hold `RLock` simultaneously; `Lock` waits for all readers to release before acquiring:

</ExampleProse>
<ExampleCode>

```go
type Cache struct {
    mu    sync.RWMutex
    items map[string]string
}

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

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

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A **deadlock** happens when two goroutines each hold a lock and wait for the other's lock, so neither can ever proceed. The classic trigger is acquiring two mutexes in opposite order across goroutines.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "sync"
    "time"
)

func main() {
    var mu1, mu2 sync.Mutex

    go func() {
        mu1.Lock()
        time.Sleep(1 * time.Millisecond) // let main goroutine run
        mu2.Lock()                        // waits forever: mu2 is held below
        mu2.Unlock()
        mu1.Unlock()
    }()

    mu2.Lock()
    mu1.Lock() // waits forever: mu1 is held above
    mu1.Unlock()
    mu2.Unlock()
    // fatal error: all goroutines are asleep - deadlock!
}
```

</ExampleCode>
</ExamplePair>

Another way to avoid deadlocks entirely is to confine state to a single goroutine and access it through channels - covered in [Stateful Goroutines](/byexample/go/stateful-goroutines).

The Go race detector (`go test -race` or `go run -race`) catches lock violations at runtime. Run it in CI; it has a modest overhead but is essential for correctness.

<InProduction>
Embed the mutex in the struct it protects and name it clearly (`mu sync.Mutex`). Always acquire and release in the same goroutine. Use `defer mu.Unlock()` immediately after `Lock()` to prevent leaks on early returns or panics. Profile lock contention with pprof mutex profiling before switching to a sharded or lock-free design.
</InProduction>


Use sync.Mutex to safely share state across goroutines when atomic operations are not enough.

Mutexes


Instead of sharing state protected by a mutex, you can confine state to a single goroutine and expose read and write access through channels. This pattern eliminates data races by construction: only one goroutine ever touches the state.

<ExamplePair>
<ExampleProse>

A state goroutine owns a map. Callers send command structs over channels and receive results via per-request reply channels. The state goroutine serializes all access in its `select` loop.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

type readOp struct {
    key  int
    resp chan int
}

type writeOp struct {
    key  int
    val  int
    resp chan bool
}

func main() {
    reads := make(chan readOp)
    writes := make(chan writeOp)

    // state goroutine: sole owner of the map
    go func() {
        state := make(map[int]int)
        for {
            select {
            case op := <-reads:
                op.resp <- state[op.key]
            case op := <-writes:
                state[op.key] = op.val
                op.resp <- true
            }
        }
    }()

    // write
    w := writeOp{key: 1, val: 42, resp: make(chan bool)}
    writes <- w
    <-w.resp

    // read
    r := readOp{key: 1, resp: make(chan int)}
    reads <- r
    fmt.Println("value:", <-r.resp) // 42
}
```

</ExampleCode>
</ExamplePair>

Compare the two approaches:

| Approach | Best for |
|---|---|
| Mutex | Simple read-modify-write; high-throughput counters |
| Stateful goroutine | Complex state transitions; protocol-like sequencing |

<ExamplePair>
<ExampleProse>

The stateful goroutine is heavier than a mutex for a plain counter but shines when state transitions follow a protocol - for example, a connection that must be in `idle` before it can move to `in-flight`:

</ExampleProse>
<ExampleCode>

```go
type connState int

const (
    idle connState = iota
    inflight
    closing
)

// transition is enforced inside the state goroutine's select,
// so callers can never put the connection into an invalid state.
```

</ExampleCode>
</ExamplePair>

<InProduction>
The stateful goroutine pattern (one goroutine owns mutable state, all access goes through a channel) avoids data races by design. It trades throughput for correctness guarantees. Use it when the state transitions are complex or when you want to model a protocol; use a mutex when the critical section is a simple read-modify-write.
</InProduction>


Confine mutable state to a single goroutine and expose it through channels to avoid data races by design.

Stateful Goroutines


When multiple goroutines increment a plain integer at the same time, the result is wrong. This happens because `counter++` is not one operation -- it reads the current value, adds 1, then writes it back. Two goroutines can read the same value simultaneously and both write the same incremented result, effectively losing one increment. This is called a **race condition**.

<ExamplePair>
<ExampleProse>

Here is the broken version. Run it with `go run -race` and Go will report a data race. The final count will be less than 1000.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
)

func main() {
    counter := 0 // plain int, NOT safe for concurrent use

    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            counter++ // read-modify-write: not atomic
        }()
    }

    wg.Wait()
    fmt.Println("counter:", counter) // often less than 1000
}
```

</ExampleCode>
</ExamplePair>

The fix is to make each increment a single indivisible operation so no two goroutines can interfere with each other. The `sync/atomic` package provides exactly this. Go 1.19 added typed atomic types (`atomic.Int64`, `atomic.Uint64`) that are safer than the older function-based API.

<ExamplePair>
<ExampleProse>

Replace the plain `int` with `atomic.Int64`. The `Add` method increments in one uninterruptible step. `Load` reads the current value safely. The result is always exactly 1000.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
    "sync/atomic"
)

func main() {
    var counter atomic.Int64 // zero value is 0, ready to use

    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            counter.Add(1) // atomic: always correct
        }()
    }

    wg.Wait()
    fmt.Println("counter:", counter.Load()) // always 1000
}
```

</ExampleCode>
</ExamplePair>

**Compare-and-swap (CAS)** is a more advanced atomic operation. It reads the current value, checks if it matches what you expect, and only if it does, swaps it with a new value -- all in one uninterruptible step. It returns `true` if the swap happened, `false` if something else already changed the value first.

A practical example: imagine 5 goroutines all try to claim a background job. Only one should win. You can't use a plain `if` check because two goroutines might both read `false` at the same instant and both think they claimed it. CAS prevents this -- only the goroutine that gets there first succeeds, and all others see the updated value and back off.

<ExamplePair>
<ExampleProse>

5 goroutines race to claim a job. Each calls `CompareAndSwap(false, true)` -- only the first one finds the flag still `false` and wins. The rest get `false` back and skip.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
    "sync/atomic"
)

func main() {
    var claimed atomic.Bool

    var wg sync.WaitGroup
    for i := 1; i <= 5; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            if claimed.CompareAndSwap(false, true) {
                fmt.Printf("goroutine %d claimed the job\n", id)
            } else {
                fmt.Printf("goroutine %d: already claimed, skipping\n", id)
            }
        }(i)
    }

    wg.Wait()
}
// exactly one goroutine prints "claimed the job"
// the rest print "already claimed, skipping"
```

</ExampleCode>
</ExamplePair>

`atomic.Pointer[T]` lets you swap out an entire struct pointer atomically. This is a common pattern for publishing updated configuration: writers store a new pointer, readers always load the latest one, and no mutex is needed.

<ExamplePair>
<ExampleProse>

The writer allocates a new `Config` and stores the pointer. Reader goroutines call `Load` and get either the old or new config -- never a half-written one.

</ExampleProse>
<ExampleCode>

```go
type Config struct{ MaxConns int }

var current atomic.Pointer[Config]

// writer: publish a new config snapshot
newCfg := &Config{MaxConns: 100}
current.Store(newCfg)

// reader: always gets a complete, consistent snapshot
cfg := current.Load()
fmt.Println(cfg.MaxConns)
```

</ExampleCode>
</ExamplePair>

<InProduction>
Atomic operations are cheaper than mutexes for simple counters and flags, but they do not compose. If you need to update two variables together as one unit, you need a mutex. The `sync/atomic` package is correct only for single-variable operations -- using it for multi-variable invariants is a common subtle bug.
</InProduction>


Use sync/atomic for lock-free single-variable operations across goroutines.