golang-concurrency

$27

• Every goroutine must have a clear exit — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes

• Share memory by communicating — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit

• Send copies, not pointers on channels — sending pointers creates invisible shared memory, defeating the purpose of channels

• Only the sender closes a channel — closing from the receiver side panics if the sender writes after close

• Specify channel direction (chan<-, <-chan) — the compiler prevents misuse at build time

• Default to unbuffered channels — larger buffers mask backpressure; use them only with measured justification

• **Always include ctx.Done() in select** — without it, goroutines leak after caller cancellation

• **Avoid repeated time.After in hot loops** — each call allocates a timer and creates unnecessary churn; use time.NewTimer + Reset for long-running loops

• Track goroutine leaks in tests with go.uber.org/goleak

For detailed channel/select code examples, see Channels and Select Patterns.

Channel vs Mutex vs Atomic

Scenario

Use

Why

Passing data between goroutines

Channel

Communicates ownership transfer

Coordinating goroutine lifecycle

Channel + context

Clean shutdown with select

Protecting shared struct fields

sync.Mutex / sync.RWMutex

Simple critical sections

Simple counters, flags

sync/atomic

Lock-free, lower overhead

Many readers, few writers on a map

sync.Map

Optimized for read-heavy workloads. Concurrent map read/write causes a hard crash

Caching expensive computations

sync.Once / singleflight

Execute once or deduplicate

WaitGroup vs errgroup

Need

Use

Why

Wait for goroutines, errors not needed

sync.WaitGroup

Fire-and-forget

Wait + collect first error

errgroup.Group

Error propagation

Wait + cancel siblings on first error

errgroup.WithContext

Context cancellation on error

Wait + limit concurrency

errgroup.SetLimit(n)

Built-in worker pool

Sync Primitives Quick Reference

Primitive

Use case

Key notes

sync.Mutex

Protect shared state

Keep critical sections short; never hold across I/O

sync.RWMutex

Many readers, few writers

Never upgrade RLock to Lock (deadlock)

sync/atomic

Simple counters, flags

Prefer typed atomics (Go 1.19+): atomic.Int64, atomic.Bool

sync.Map

Concurrent map, read-heavy

No explicit locking; use RWMutex+map when writes dominate

sync.Pool

Reuse temporary objects

Always Reset() before Put(); reduces GC pressure

sync.Once

One-time initialization

Go 1.21+: OnceFunc, OnceValue, OnceValues

sync.WaitGroup

Waiting for simple goroutines

Go 1.25+: prefer wg.Go(func(){ ... }) for fire-and-wait tasks that do not panic and do not need error propagation. For Go <1.25 use Add/Done. For errors/cancellation/limits, use errgroup with context.

x/sync/singleflight

Deduplicate concurrent calls

Cache stampede prevention

x/sync/errgroup

Goroutine group + errors

SetLimit(n) replaces hand-rolled worker pools

For detailed examples and anti-patterns, see Sync Primitives Deep Dive.

Concurrency Checklist

Before spawning a goroutine, answer:

• How will it exit? — context cancellation, channel close, or explicit signal

• Can I signal it to stop? — pass context.Context or done channel

• Can I wait for it? — sync.WaitGroup or errgroup

• Who owns the channels? — creator/sender owns and closes

• Should this be synchronous instead? — don't add concurrency without measured need

Pipelines and Worker Pools

For pipeline patterns (fan-out/fan-in, bounded workers, generator chains, Go 1.23+ iterators, samber/ro), see Pipelines and Worker Pools.

Parallelizing Concurrency Audits

When auditing concurrency across a large codebase, use up to 5 parallel sub-agents (Agent tool):

• Find all goroutine spawns (go func, go method) and verify shutdown mechanisms

• Search for mutable globals and shared state without synchronization

• Audit channel usage — ownership, direction, closure, buffer sizes

• Find time.After in loops, missing ctx.Done() in select, unbounded spawning

• Check mutex usage, sync.Map, atomics, and thread-safety documentation

Common Mistakes

Mistake

Fix

Fire-and-forget goroutine

Provide stop mechanism (context, done channel)

Closing channel from receiver

Only the sender closes

time.After in hot loop

Reuse time.NewTimer + Reset

Missing ctx.Done() in select

Always select on context to allow cancellation

Unbounded goroutine spawning

Use errgroup.SetLimit(n) or semaphore

Sharing pointer via channel

Send copies or immutable values

wg.Add inside goroutine

Call Add before go — Wait may return early otherwise

Forgetting -race in CI

Always run go test -race ./...

Mutex held across I/O

Keep critical sections short

Cross-References

• -> See samber/cc-skills-golang@golang-performance skill for false sharing, cache-line padding, sync.Pool hot-path patterns

• -> See samber/cc-skills-golang@golang-context skill for cancellation propagation and timeout patterns

• -> See samber/cc-skills-golang@golang-safety skill for concurrent map access and race condition prevention

• -> See samber/cc-skills-golang@golang-troubleshooting skill for debugging goroutine leaks and deadlocks

• -> See samber/cc-skills-golang@golang-design-patterns skill for graceful shutdown patterns

• -> See samber/cc-skills-golang@golang-continuous-integration skill for automated AI-driven code review in CI using these guidelines

Go 1.26 experimental goroutine leak profile

For Go 1.26 diagnostics, there is an experimental goroutine leak profile. It is useful for production-oriented leak investigation, but is gated by GOEXPERIMENT=goroutineleakprofile; do not rely on it as default stable behavior.

Typical usage when the experiment is enabled:

curl http://localhost:6060/debug/pprof/goroutineleak?debug=2

go tool pprof http://localhost:6060/debug/pprof/goroutineleak

Keep existing tools:

• tests: go.uber.org/goleak

• runtime count: runtime.NumGoroutine()

• stack dump: /debug/pprof/goroutine?debug=2

• race checks: go test -race ./...

References

• Go Concurrency Patterns: Pipelines

• Effective Go: Concurrency