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

go-concurrency

NPX Install

Tags

SKILL.md Content

Go Concurrency

Goroutine Lifetimes

Why Goroutine Lifetimes Matter

Make Lifetimes Obvious

Don't Fire-and-Forget Goroutines

Waiting for Goroutines

No Goroutines in init()

Testing for Goroutine Leaks

Zero-value Mutexes

Don't Embed Mutexes

Synchronous Functions

Why Prefer Synchronous Functions?

Channel Direction

Why Specify Direction?

Channel Size: One or None

Common Patterns

Atomic Operations

Documenting Concurrency

Buffer Pooling with Channels

Quick Reference

Concurrency Checklist

Anti-Patterns to Avoid

See Also

External Resources