Go Concurrency Patterns (Production) Overview
Go concurrency scales when goroutine lifetimes are explicit, cancellation is propagated with context.Context, and shared state is protected (channels or locks). Apply these patterns to build reliable services and avoid common failure modes: goroutine leaks, deadlocks, and data races.
Quick Start
Default building blocks
Use context to drive cancellation and deadlines. Use errgroup.WithContext for fan-out/fan-in with early abort. Bound concurrency (avoid unbounded goroutines) with a semaphore or worker pool. Prefer immutable data; otherwise protect shared state with a mutex or make a single goroutine the owner.
Avoid
Fire-and-forget goroutines in request handlers. time.After inside hot loops. Closing channels from the receiver side. Sharing mutable variables across goroutines without synchronization. Core Concepts Goroutine lifecycle
Treat goroutines as resources with a clear owner and shutdown condition.
✅ Correct: stop goroutines via context
ctx, cancel := context.WithCancel(context.Background()) defer cancel()
go func() { ticker := time.NewTicker(250 * time.Millisecond) defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
// do work
}
}
}()
❌ Wrong: goroutine without a stop condition
go func() { for { doWork() // leaks forever } }()
Channels vs mutexes (choose intentionally) Use channels to model ownership/serialization of state or to pipeline work. Use mutexes to protect shared in-memory state with simple read/write patterns.
✅ Correct: one goroutine owns the map
type req struct { key string reply chan<- int }
func mapOwner(ctx context.Context, in <-chan req) { m := map[string]int{} for { select { case <-ctx.Done(): return case r := <-in: r.reply <- m[r.key] } } }
✅ Correct: mutex protects shared map
type SafeMap struct { mu sync.RWMutex m map[string]int }
func (s *SafeMap) Get(k string) (int, bool) { s.mu.RLock() defer s.mu.RUnlock() v, ok := s.m[k] return v, ok }
Patterns 1) Fan-out/fan-in with cancellation (errgroup)
Use errgroup.WithContext to run concurrent tasks, cancel siblings on error, and wait for completion.
✅ Correct: cancel on first error
g, ctx := errgroup.WithContext(ctx)
for _, id := range ids { id := id // capture g.Go(func() error { return process(ctx, id) }) }
if err := g.Wait(); err != nil { return err }
❌ Wrong: WaitGroup loses the first error and does not propagate cancellation
var wg sync.WaitGroup for _, id := range ids { wg.Add(1) go func() { defer wg.Done() _ = process(context.Background(), id) // ignores caller ctx + captures id }() } wg.Wait()
2) Bounded concurrency (semaphore pattern)
Bound parallelism to prevent CPU/memory exhaustion and downstream overload.
✅ Correct: bounded fan-out
limit := make(chan struct{}, 8) // max 8 concurrent g, ctx := errgroup.WithContext(ctx)
for _, id := range ids { id := id g.Go(func() error { select { case <-ctx.Done(): return ctx.Err() case limit <- struct{}{}: } defer func() { <-limit }()
return process(ctx, id)
})
}
return g.Wait()
3) Worker pool (durable throughput)
Use a fixed number of workers for stable throughput and predictable resource usage.
✅ Correct: worker pool with context stop
type Job struct{ ID string }
func runPool(ctx context.Context, jobs <-chan Job, workers int) error { g, ctx := errgroup.WithContext(ctx)
for i := 0; i < workers; i++ {
g.Go(func() error {
for {
select {
case <-ctx.Done():
return ctx.Err()
case j, ok := <-jobs:
if !ok {
return nil
}
if err := handleJob(ctx, j); err != nil {
return err
}
}
}
})
}
return g.Wait()
}
4) Pipeline stages (fan-out between stages)
Prefer one-directional channels and close only from the sending side.
✅ Correct: sender closes
func stageA(ctx context.Context, out chan<- int) { defer close(out) for i := 0; i < 10; i++ { select { case <-ctx.Done(): return case out <- i: } } }
❌ Wrong: receiver closes
func stageB(in <-chan int) { close(in) // compile error in<-chan; also wrong ownership model }
5) Periodic work without leaks (time.Ticker vs time.After)
Use time.NewTicker for loops; avoid time.After allocations in hot paths.
✅ Correct: ticker
t := time.NewTicker(1 * time.Second) defer t.Stop()
for { select { case <-ctx.Done(): return case <-t.C: poll() } }
❌ Wrong: time.After in loop
for { select { case <-ctx.Done(): return case <-time.After(1 * time.Second): poll() } }
Decision Trees Channel vs Mutex Need ownership/serialization (single writer, message passing) → use channel + owner goroutine Need shared cache/map with many readers and simple updates → use RWMutex Need simple counter with low contention → use atomic WaitGroup vs errgroup Need error propagation + sibling cancellation → use errgroup.WithContext Need only wait and errors are handled elsewhere → use sync.WaitGroup Buffered vs unbuffered channel Need backpressure and synchronous handoff → use unbuffered Need burst absorption up to a known size → use buffered (size with intent) Unsure → start unbuffered and measure; add buffer only to remove known bottleneck Testing & Verification Race detector and flake control
Run targeted tests with the race detector and disable caching during debugging:
go test -race ./... go test -run TestName -race -count=1 ./...
Timeouts to prevent hanging tests
✅ Correct: test-level timeout via context
func TestSomething(t testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 2time.Second) defer cancel()
if err := doThing(ctx); err != nil {
t.Fatal(err)
}
}
Troubleshooting Symptom: deadlock (test hangs, goroutines blocked)
Actions:
Add timeouts (context.WithTimeout) around blocking operations. Verify channel ownership: only the sender closes; receivers stop on ok == false. Check for missing <-limit release in semaphore patterns. Symptom: data race (go test -race reports)
Actions:
Identify shared variables mutated by multiple goroutines. Add a mutex or convert to ownership model (single goroutine owns state). Avoid writing to captured loop variables. Symptom: goroutine leak (memory growth, slow shutdown)
Actions:
Ensure every goroutine selects on ctx.Done(). Ensure time.Ticker is stopped and channels are closed by senders. Avoid context.Background() inside request paths; propagate caller context. Resources Go Blog: Concurrency patterns: https://go.dev/blog/pipelines errgroup: https://pkg.go.dev/golang.org/x/sync/errgroup Go memory model: https://go.dev/ref/mem