go-concurrency

Go Concurrency

Compatibility: Atomic examples may use standard-library typed atomics where available or go.uber.org/atomic where a project already depends on it.

Resource Routing

• references/GOROUTINE-PATTERNS.md - Read when starting, stopping, or waiting for goroutines.
• references/SYNC-PRIMITIVES.md - Read when choosing between mutexes, atomics, channels, and once-like primitives.
• references/BUFFER-POOLING.md - Read when considering channel-backed or sync.Pool-style reuse.
• references/ADVANCED-PATTERNS.md - Read for worker pools, pipelines, errgroup, and cancellation-heavy patterns.

Goroutine Lifetimes

Normative: When you spawn goroutines, make it clear when or whether they exit.

Goroutines can leak by blocking on channel sends/receives. The GC will not terminate a blocked goroutine even if no other goroutine holds a reference to the channel. Even non-leaking in-flight goroutines cause panics (send on closed channel), data races, memory issues, and resource leaks.

Core Rules

1. Every goroutine needs a stop mechanism — a predictable end time, a cancellation signal, or both
2. Code must be able to wait for the goroutine to finish
3. No goroutines in init() — expose lifecycle methods (Close, Stop, Shutdown) instead
4. Keep synchronization scoped — constrain to function scope, factor logic into synchronous functions

// Good: Clear lifetime with WaitGroup.Go (Go 1.25+)
var wg sync.WaitGroup
for item := range queue {
    item := item
    wg.Go(func() { process(ctx, item) })
}
wg.Wait()

// Bad: No way to stop or wait
go func() { for { flush(); time.Sleep(delay) } }()

Test for leaks with go.uber.org/goleak.

Principle: Never start a goroutine without knowing how it will stop.

---

Share by Communicating

"Do not communicate by sharing memory; instead, share memory by communicating."

This is Go's foundational concurrency design principle. Use channels for ownership transfer and orchestration — when one goroutine produces a value and another consumes it. Use mutexes when multiple goroutines access shared state and channels would add unnecessary complexity.