# Advanced Concurrency Patterns

Detailed reference for advanced concurrency patterns from Effective Go. These
patterns are situational — use when you need request/response multiplexing or
CPU-bound parallelization.

---

## Channels of Channels

> **Source**: Effective Go

A channel is a first-class value that can be allocated and passed around like
any other. A powerful pattern is embedding a **reply channel** inside a request
struct, letting each client provide its own path for the answer:

```go
type Request struct {
    args       []int
    f          func([]int) int
    resultChan chan int
}
```

The client sends a request with a function, its arguments, and a channel on
which to receive the result:

```go
request := &Request{[]int{3, 4, 5}, sum, make(chan int)}
clientRequests <- request
fmt.Printf("answer: %d\n", <-request.resultChan)
```

The server handler reads from the queue and sends results back on each
request's reply channel:

```go
func handle(queue chan *Request) {
    for req := range queue {
        req.resultChan <- req.f(req.args)
    }
}
```

This pattern forms the basis for a rate-limited, parallel, non-blocking RPC
system without a mutex in sight.

---

## CPU-Bound Parallelization

> **Source**: Effective Go (modernized)

When a computation can be broken into independent pieces, parallelize it across
CPU cores using a `sync.WaitGroup` to wait for completion. On Go 1.25 and
newer, use `WaitGroup.Go` so the add/done bookkeeping stays coupled to the
goroutine:

```go
type Vector []float64

func (v Vector) DoSome(i, n int, u Vector) {
    for ; i < n; i++ {
        v[i] += u.Op(v[i])
    }
}

func (v Vector) DoAll(u Vector) {
    numCPU := runtime.NumCPU()
    var wg sync.WaitGroup
    for i := 0; i < numCPU; i++ {
        i := i
        wg.Go(func() {
            v.DoSome(i*len(v)/numCPU, (i+1)*len(v)/numCPU, u)
        })
    }
    wg.Wait()
}
```

Use `runtime.NumCPU()` for hardware cores or `runtime.GOMAXPROCS(0)` to honor
the user's resource configuration. For Go versions before 1.25, use
`wg.Add(1)`, `go func`, and `defer wg.Done()` around each launched goroutine.

> **Important**: Don't confuse concurrency (structuring a program as
> independently executing components) with parallelism (executing calculations
> simultaneously on multiple CPUs). Go is a concurrent language; not all
> parallelization problems fit its model.

---

## Common Mistakes

### Forgetting to signal completion

If a goroutine never calls `wg.Done()` (or never sends on a done channel), the
waiting goroutine blocks forever:

```go
// Bad: Missing wg.Done — deadlocks
var wg sync.WaitGroup
wg.Add(1)
go func() {
    doWork()
}()
wg.Wait()

// Good: Always defer wg.Done
var wg sync.WaitGroup
wg.Add(1)
go func() {
    defer wg.Done()
    doWork()
}()
wg.Wait()
```

### Unbounded goroutine spawning

Launching one goroutine per work item with no limit can exhaust memory or
overwhelm downstream resources. Use a semaphore to cap concurrency:

```go
// Bad: Spawns len(items) goroutines at once
var wg sync.WaitGroup
for _, item := range items {
    wg.Add(1)
    go func(it Item) {
        defer wg.Done()
        process(it)
    }(item)
}
wg.Wait()

// Good: Semaphore limits concurrency to maxWorkers
var wg sync.WaitGroup
sem := make(chan struct{}, maxWorkers)
for _, item := range items {
    wg.Add(1)
    sem <- struct{}{}
    go func(it Item) {
        defer wg.Done()
        defer func() { <-sem }()
        process(it)
    }(item)
}
wg.Wait()
```

# Buffer Pooling with Channels

Use a buffered channel as a free list to reuse allocated buffers, avoiding
repeated allocations. This "leaky buffer" pattern uses `select` with `default`
for non-blocking operations.

> **Source**: Effective Go

```go
var freeList = make(chan *Buffer, 100) // Buffered channel as free list

// Client: Get buffer from free list or allocate new one
func getBuffer() *Buffer {
    select {
    case b := <-freeList:
        return b // Reuse existing buffer
    default:
        return new(Buffer) // Free list empty; allocate new buffer
    }
}

// Server: Return buffer to free list if room, otherwise drop it
func putBuffer(b *Buffer) {
    b.Reset() // Prepare for reuse
    select {
    case freeList <- b:
        // Buffer returned to free list
    default:
        // Free list full; drop buffer (GC will reclaim)
    }
}
```

## How It Works

1. **Non-blocking receive**: Client tries to grab a buffer from `freeList`. If
   empty, `default` runs and allocates a new buffer.
2. **Non-blocking send**: Server tries to return the buffer. If `freeList` is
   full, `default` runs and the buffer is dropped for garbage collection.
3. **Bounded memory**: The channel capacity (100) limits pooled buffers,
   preventing unbounded growth.

This pattern is useful when allocation is expensive and buffer reuse is
beneficial, but you don't want blocking behavior when the pool is empty or full.

## When to Use

- High-frequency allocations of similar-sized objects
- Performance-critical code paths where allocation overhead matters
- Scenarios where you want bounded memory usage

## Production Alternative

For production code, consider `sync.Pool` which provides similar functionality
with better integration into the garbage collector:

```go
var bufferPool = sync.Pool{
    New: func() any {
        return new(Buffer)
    },
}

func getBuffer() *Buffer {
    return bufferPool.Get().(*Buffer)
}

func putBuffer(b *Buffer) {
    b.Reset()
    bufferPool.Put(b)
}
```

`sync.Pool` advantages:
- Automatic cleanup during garbage collection
- No need to manage pool size
- Thread-safe by design
- Better performance under high concurrency

The channel-based approach is still valuable for understanding Go's concurrency
primitives and for cases where you need more control over pool behavior.

# Goroutine Lifecycle Patterns

Detailed patterns for managing goroutine lifetimes — ensuring every goroutine
has a clear start/stop mechanism and preventing resource leaks.

---

## Making Lifetimes Obvious

> The WaitGroup example and scoping rules are in the parent skill (SKILL.md §
> Goroutine Lifetimes, Core Rules). This reference covers: stop/done channel
> patterns, waiting strategies, init() lifecycle examples, and synchronous API
> design.

---

## Stop/Done Channel Pattern

Every goroutine must have a predictable stop mechanism. Use a stop channel to
signal shutdown and a done channel to confirm exit:

```go
var (
    stop = make(chan struct{}) // tells the goroutine to stop
    done = make(chan struct{}) // tells us that the goroutine exited
)
go func() {
    defer close(done)
    ticker := time.NewTicker(delay)
    defer ticker.Stop()
    for {
        select {
        case <-ticker.C:
            flush()
        case <-stop:
            return
        }
    }
}()

// To shut down:
close(stop)  // signal the goroutine to stop
<-done       // and wait for it to exit
```

Sending on a closed channel panics — always use `close()` to signal, never send:

```go
ch := make(chan int)
close(ch)
ch <- 13 // panic: send on closed channel
```

---

## Waiting for Goroutines

> The `sync.WaitGroup` pattern for multiple goroutines is in the parent skill
> (SKILL.md § Goroutine Lifetimes). Below is the done-channel alternative for a
> single goroutine.

Use a done channel for a single goroutine:

```go
done := make(chan struct{})
go func() {
    defer close(done)
    // work...
}()
<-done // wait for goroutine to finish
```

---

## No Goroutines in init()

> The core rule is in the parent skill (SKILL.md § Core Rules, rule 3). Below
> are expanded examples showing lifecycle management.

```go
// Bad: Spawns uncontrollable background goroutine
func init() {
    go doWork()
}
```

```go
// Good: Explicit lifecycle management
type Worker struct {
    stop chan struct{}
    done chan struct{}
}

func NewWorker() *Worker {
    w := &Worker{
        stop: make(chan struct{}),
        done: make(chan struct{}),
    }
    go w.doWork()
    return w
}

func (w *Worker) Shutdown() {
    close(w.stop)
    <-w.done
}
```

---

## Prefer Synchronous Functions

> The rationale and benefit table are in the parent skill (SKILL.md §
> Synchronous Functions). Below is a concrete code example.

```go
// Good: Synchronous function - caller controls concurrency
func ProcessItems(items []Item) ([]Result, error) {
    var results []Result
    for _, item := range items {
        result, err := processItem(item)
        if err != nil {
            return nil, err
        }
        results = append(results, result)
    }
    return results, nil
}

// Caller can add concurrency if needed:
go func() {
    results, err := ProcessItems(items)
    // handle results
}()
```

# Sync Primitives Patterns

Detailed patterns for mutexes and atomic operations — covering mutex embedding
pitfalls and type-safe atomic access.

---

## Don't Embed Mutexes

If you use a struct by pointer, the mutex should be a non-pointer field. Do not
embed the mutex on the struct, even if the struct is not exported.

```go
// Bad: Embedded mutex exposes Lock/Unlock as part of API
type SMap struct {
    sync.Mutex // Lock() and Unlock() become methods of SMap
    data map[string]string
}

func (m *SMap) Get(k string) string {
    m.Lock()
    defer m.Unlock()
    return m.data[k]
}
```

```go
// Good: Named field keeps mutex as implementation detail
type SMap struct {
    mu   sync.Mutex
    data map[string]string
}

func (m *SMap) Get(k string) string {
    m.mu.Lock()
    defer m.mu.Unlock()
    return m.data[k]
}
```

With the bad example, `Lock` and `Unlock` methods are unintentionally part of
the exported API. With the good example, the mutex is an implementation detail
hidden from callers.

---

## Atomic Operations: Full Example

The standard `sync/atomic` package operates on raw types (`int32`, `int64`,
etc.), making it easy to forget to use atomic operations consistently.

```go
// Bad: Easy to forget atomic operation
type foo struct {
    running int32 // atomic
}

func (f *foo) start() {
    if atomic.SwapInt32(&f.running, 1) == 1 {
        return // already running
    }
    // start the Foo
}

func (f *foo) isRunning() bool {
    return f.running == 1 // race! forgot atomic.LoadInt32
}
```

```go
// Good: Type-safe atomic operations
type foo struct {
    running atomic.Bool
}

func (f *foo) start() {
    if f.running.Swap(true) {
        return // already running
    }
    // start the Foo
}

func (f *foo) isRunning() bool {
    return f.running.Load() // can't accidentally read non-atomically
}
```

The `atomic.Bool`, `atomic.Int64`, etc. types (available in stdlib `sync/atomic`
since Go 1.19, or via [go.uber.org/atomic](https://pkg.go.dev/go.uber.org/atomic))
add type safety by hiding the underlying type.

---

## Channel Direction Examples

Specifying direction prevents accidental misuse:

```go
// Good: Direction specified - clear ownership
func sum(values <-chan int) int {
    total := 0
    for v := range values {
        total += v
    }
    return total
}
```

```go
// Bad: No direction - allows accidental misuse
func sum(values chan int) (out int) {
    for v := range values {
        out += v
    }
    close(values) // Bug! This compiles but shouldn't happen.
}
```