Go Concurrency
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
- Every goroutine needs a stop mechanism — a predictable end time, a
cancellation signal, or both
- Code must be able to wait for the goroutine to finish
- No goroutines in
init() — expose lifecycle methods (Close, Stop,
Shutdown) instead
- Keep synchronization scoped — constrain to function scope, factor logic
into synchronous functions
var wg sync.WaitGroup
for item := range queue {
wg.Add(1)
go func() { defer wg.Done(); process(ctx, item) }()
}
wg.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.
Read references/GOROUTINE-PATTERNS.md when
implementing stop/done channel patterns, goroutine waiting strategies, or
lifecycle-managed workers.
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.
Default to channels. Fall back to sync.Mutex / sync.RWMutex when the
problem is naturally about protecting a shared data structure (e.g., a cache or
counter) rather than passing data between goroutines.
Synchronous Functions
Normative: Prefer synchronous functions over asynchronous ones.
| Benefit |
Why |
| Localized goroutines |
Lifetimes easier to reason about |
| Avoids leaks and races |
Easier to prevent resource leaks and data races |
| Easier to test |
Check input/output without polling |
| Caller flexibility |
Caller adds concurrency when needed |
Advisory: It is quite difficult (sometimes impossible) to remove
unnecessary concurrency at the caller side. Let the caller add concurrency
when needed.
Read references/GOROUTINE-PATTERNS.md when
writing synchronous-first APIs that callers may wrap in goroutines.
Zero-value Mutexes
The zero-value of sync.Mutex and sync.RWMutex is valid — almost never need
a pointer to a mutex.
var mu sync.Mutex mu := new(sync.Mutex)
Don't embed mutexes — use a named mu field to keep Lock/Unlock as
implementation details, not exported API.
Read references/SYNC-PRIMITIVES.md when
implementing mutex-protected structs or deciding how to structure mutex fields.
Channel Direction
Normative: Specify channel direction where possible.
Direction prevents errors (compiler catches closing a receive-only channel),
conveys ownership, and is self-documenting.
func produce(out chan<- int) { }
func consume(in <-chan int) { }
func transform(in <-chan int, out chan<- int) { }
Channel Size: One or None
Channels should have size zero (unbuffered) or one. Any other size
requires justification for:
- How the size was determined
- What prevents the channel from filling under load
- What happens when writers block
c := make(chan int)
c := make(chan int, 1)
c := make(chan int, 64)
Read references/SYNC-PRIMITIVES.md when
reviewing detailed channel direction examples with error-prone patterns.
Atomic Operations
Use atomic.Bool, atomic.Int64, etc. (stdlib sync/atomic since Go 1.19, or
go.uber.org/atomic) for type-safe
atomic operations. Raw int32/int64 fields make it easy to forget atomic
access on some code paths.
var running atomic.Bool var running int32
running.Store(true) atomic.StoreInt32(&running, 1)
running.Load() running == 1
Read references/SYNC-PRIMITIVES.md when
choosing between sync/atomic and go.uber.org/atomic, or implementing atomic
state flags in structs.
Documenting Concurrency
Advisory: Document thread-safety when it's not obvious from the operation
type.
Go users assume read-only operations are safe for concurrent use, and mutating
operations are not. Document concurrency when:
- Read vs mutating is unclear — e.g., a
Lookup that mutates LRU state
- API provides synchronization — e.g., thread-safe clients
- Interface has concurrency requirements — document in type definition
Context Usage
For context.Context guidance (parameter placement, struct storage, custom
types, derivation patterns), see the dedicated
go-context skill.
Buffer Pooling with Channels
Use a buffered channel as a free list to reuse allocated buffers. This "leaky
buffer" pattern uses select with default for non-blocking operations.
Read references/BUFFER-POOLING.md when
implementing a worker pool with reusable buffers or choosing between
channel-based pools and sync.Pool.
Advanced Patterns
Read references/ADVANCED-PATTERNS.md when
implementing request-response multiplexing with channels of channels, or
CPU-bound parallel computation across cores.
Related Skills
- Context propagation: See go-context when passing cancellation, deadlines, or request-scoped values through goroutines
- Error handling: See go-error-handling when propagating errors from goroutines or using errgroup
- Defensive hardening: See go-defensive when protecting shared state at API boundaries or using defer for cleanup
- Interface design: See go-interfaces when choosing receiver types for types with sync primitives
External Resources
