Go Concurrency
This skill covers concurrency patterns and best practices from Google's Go Style Guide and Uber's Go Style Guide, including goroutine management, channel usage, mutex handling, and synchronization.
Goroutine Lifetimes
Normative: When you spawn goroutines, make it clear when or whether they exit.
Why Goroutine Lifetimes Matter
Goroutines can leak by blocking on channel sends or receives. The garbage collector will not terminate a goroutine blocked on a channel even if no other goroutine has a reference to the channel.
Even when goroutines do not leak, leaving them in-flight when no longer needed causes:
Panics: Sending on a closed channel causes a panic Data races: Modifying still-in-use inputs after the result isn't needed Memory issues: Unpredictable memory usage from long-lived goroutines Resource leaks: Preventing unused objects from being garbage collected // Bad: Sending on closed channel causes panic ch := make(chan int) ch <- 42 close(ch) ch <- 13 // panic
Make Lifetimes Obvious
Write concurrent code so goroutine lifetimes are evident. Keep synchronization-related code constrained within function scope and factor logic into synchronous functions.
// Good: Goroutine lifetimes are clear func (w *Worker) Run(ctx context.Context) error { var wg sync.WaitGroup for item := range w.q { wg.Add(1) go func() { defer wg.Done() process(ctx, item) // Returns when context is cancelled }() } wg.Wait() // Prevent spawned goroutines from outliving this function }
// Bad: Careless about when goroutines finish func (w *Worker) Run() { for item := range w.q { go process(item) // When does this finish? What if it never does? } }
Don't Fire-and-Forget Goroutines
Every goroutine must have a predictable stop mechanism:
A predictable time at which it will stop running, OR A way to signal that it should stop Code must be able to block and wait for the goroutine to finish
Source: Uber Go Style Guide
// Bad: No way to stop or wait for this goroutine go func() { for { flush() time.Sleep(delay) } }()
// Good: Stop/done channel pattern for controlled shutdown 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
Waiting for Goroutines
Use sync.WaitGroup for multiple goroutines:
var wg sync.WaitGroup for i := 0; i < N; i++ { wg.Add(1) go func() { defer wg.Done() // work... }() } wg.Wait()
Use a done channel for a single goroutine:
done := make(chan struct{}) go func() { defer close(done) // work... }() <-done // wait for goroutine to finish
No Goroutines in init()
init() functions should not spawn goroutines. If a package needs a background goroutine, expose an object that manages the goroutine's lifetime with a method (Close, Stop, Shutdown) to stop and wait for it.
Source: Uber Go Style Guide
// Bad: Spawns uncontrollable background goroutine func init() { go doWork() }
// 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 }
Testing for Goroutine Leaks
Use go.uber.org/goleak to test for goroutine leaks in packages that spawn goroutines.
Principle: Never start a goroutine without knowing how it will stop.
Zero-value Mutexes
The zero-value of sync.Mutex and sync.RWMutex is valid, so you almost never need a pointer to a mutex.
Source: Uber Go Style Guide
// Bad: Unnecessary pointer mu := new(sync.Mutex) mu.Lock()
// Good: Zero-value is valid var mu sync.Mutex mu.Lock()
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.
// 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] }
// 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.
Synchronous Functions
Normative: Prefer synchronous functions over asynchronous functions.
Why Prefer Synchronous Functions? Localized goroutines: Keeps goroutines within a call, making lifetimes easier to reason about Avoids leaks and races: Easier to prevent resource leaks and data races Easier to test: Caller can pass input and check output without polling Caller flexibility: Caller can add concurrency by calling in a separate goroutine // 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 }()
Advisory: It is quite difficult (sometimes impossible) to remove unnecessary concurrency at the caller side. Let the caller add concurrency when needed.
Channel Direction
Normative: Specify channel direction where possible.
Why Specify Direction? Prevents errors: Compiler catches mistakes like closing a receive-only channel Conveys ownership: Makes clear who sends and who receives Self-documenting: Function signature tells the story // Good: Direction specified - clear ownership func sum(values <-chan int) int { total := 0 for v := range values { total += v } return total }
// 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. }
Channel Size: One or None
Channels should usually have a size of one or be unbuffered. Any other size must be subject to scrutiny. Consider:
How is the size determined? What prevents the channel from filling up under load? What happens when writers block?
Source: Uber Go Style Guide
// Bad: Arbitrary buffer size c := make(chan int, 64) // "Ought to be enough for anybody!"
// Good: Deliberate sizing c := make(chan int, 1) // Size of one c := make(chan int) // Unbuffered, size of zero
Common Patterns func produce(out chan<- int) { / send-only / } func consume(in <-chan int) { / receive-only / } func transform(in <-chan int, out chan<- int) { / both directions / }
Atomic Operations
Use go.uber.org/atomic for type-safe atomic operations. The standard sync/atomic package operates on raw types (int32, int64, etc.), making it easy to forget to use atomic operations consistently.
Source: Uber Go Style Guide
// 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 }
// 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 go.uber.org/atomic package adds type safety by hiding the underlying type and includes convenient types like atomic.Bool, atomic.Int64, etc.
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 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.
See references/BUFFER-POOLING.md for the full pattern with examples and production alternatives using sync.Pool.
Quick Reference Topic Guidance Type Goroutine lifetimes Make exit conditions clear Normative Fire-and-forget Don't do it - always have stop mechanism Normative Zero-value mutexes Valid; don't use pointers Advisory Mutex embedding Don't embed; use named field Advisory Synchronous functions Prefer over async Normative Channel direction Always specify Normative Channel size One or none by default Advisory Atomic operations Use go.uber.org/atomic Advisory Concurrency docs Document when not obvious Advisory Concurrency Checklist
Before spawning a goroutine, answer:
How will this goroutine exit? Can I signal it to stop? Can I wait for it to finish? Who owns the channels it uses? What happens when the context is cancelled? Should this be a synchronous function instead? Anti-Patterns to Avoid Anti-Pattern Problem Fix Fire-and-forget goroutines Resource leaks, undefined behavior Use WaitGroup, done channel, or context Goroutines in init() Uncontrollable lifecycle Use explicit object with Shutdown method Embedded mutexes Leaks Lock/Unlock into API Use named mu field Pointer to mutex Unnecessary indirection Zero-value is valid Arbitrary channel buffers Hidden blocking issues Default to 0 or 1 Raw sync/atomic Easy to forget atomic reads Use go.uber.org/atomic Undocumented thread-safety Callers may race Document when unclear See Also go-style-core: Foundational style principles (clarity, simplicity) go-error-handling: Error handling patterns in concurrent code go-defensive: Defensive programming including validation and safety go-documentation: General documentation conventions External Resources Never start a goroutine without knowing how it will stop Dave Cheney Rethinking Classical Concurrency Patterns - Bryan Mills (GopherCon 2018) When Go programs end - Go Time podcast go.uber.org/goleak - Goroutine leak detector for testing go.uber.org/atomic - Type-safe atomic operations