
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


Sorting is a fundamental operation on collections. Go provides generic sorting via slices.Sort (Go 1.21+) for types with a natural order, slices.SortFunc for custom comparison logic, and sort.Search for binary search on already-sorted collections.

<ExamplePair>
<ExampleProse>

Sort a slice of integers in ascending order using slices.Sort. This is the generic, type-safe replacement for the older sort.Ints and sort.Slice functions.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "slices"
)

func main() {
    nums := []int{3, 1, 4, 1, 5, 9, 2, 6}
    slices.Sort(nums)
    fmt.Println(nums) // [1 1 2 3 4 5 6 9]

    // Sort in descending order using slices.SortFunc
    slices.SortFunc(nums, func(a, b int) int {
        return b - a // reverse comparison
    })
    fmt.Println(nums) // [9 6 5 4 3 2 1 1]
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Sort strings - slices.Sort handles strings as well as any type with a natural order. Sort in reverse with slices.Reverse (Go 1.21+).

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "slices"
)

func main() {
    words := []string{"zebra", "apple", "mango"}
    slices.Sort(words)
    fmt.Println(words) // [apple mango zebra]

    slices.Reverse(words)
    fmt.Println(words) // [zebra mango apple]
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Binary search on a sorted slice with sort.Search or slices.BinarySearch. search.Search returns the index where the element would be inserted; slices.BinarySearch (Go 1.21+) returns the index and a bool indicating exact match.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "slices"
    "sort"
)

func main() {
    sorted := []int{1, 2, 3, 5, 8, 13}

    // slices.BinarySearch (Go 1.21+)
    idx, found := slices.BinarySearch(sorted, 5)
    fmt.Println(idx, found) // 3 true

    // sort.Search (returns insertion point)
    idx = sort.Search(len(sorted), func(i int) bool {
        return sorted[i] >= 8
    })
    fmt.Println(idx) // 4
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Prefer slices.Sort and slices.SortFunc (Go 1.21+) for new code - they are generic, type-safe, and measurably faster than sort.Slice. sort.Search is a stable binary search that works on any sorted collection; reach for it instead of linear scans in hot paths (log(n) vs n). Note that slices.Sort is not stable - equal elements may not retain their original order. Use slices.SortStableFunc if you need to preserve the original order of equal elements (e.g., sorting by priority then by creation time for display).
</InProduction>


Sorting slices with slices.Sort (generic, Go 1.21+), slices.SortFunc for custom order, and sort.Search for binary search.

Sorting


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.

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