Go Concurrency Agent Skill

Go Concurrency

> Compatibility: Atomic examples may use standard-library typed atomics where available or go.uber.org/atomic where a project already depends on it.

Resource Routing

• references/GOROUTINE-PATTERNS.md - Read when starting, stopping, or waiting for goroutines.
• references/SYNC-PRIMITIVES.md - Read when choosing between mutexes, atomics, channels, and once-like primitives.
• references/BUFFER-POOLING.md - Read when considering channel-backed or sync.Pool-style reuse.
• references/ADVANCED-PATTERNS.md - Read for worker pools, pipelines, errgroup, and cancellation-heavy patterns.

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

// Good: Clear lifetime with WaitGroup.Go (Go 1.25+)
var wg sync.WaitGroup
for item := range queue {
    item := item
    wg.Go(func() { process(ctx, item) })
}
wg.Wait()

// Bad: No way to stop or 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.

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.

Zero-value Mutexes

The zero-value of sync.Mutex and sync.RWMutex is valid — almost never need

a pointer to a mutex.

// Good: Zero-value is valid    // Bad: Unnecessary pointer
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.

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) { /* send-only */ }
func consume(in <-chan int)  { /* receive-only */ }
func transform(in <-chan int, out chan<- int) { /* both */ }

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)    // unbuffered — Good
c := make(chan int, 1) // size one — Good
c := make(chan int, 64) // arbitrary — needs justification

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.

// Good: Type-safe              // Bad: Easy to forget
var running atomic.Bool          var running int32 // atomic
running.Store(true)              atomic.StoreInt32(&running, 1)
running.Load()                   running == 1 // race!

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.

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

• [Never start a goroutine without knowing how it will

stop](https://dave.cheney.net/2016/12/22/never-start-a-goroutine-without-knowing-how-it-will-stop)

— Dave Cheney

• [Rethinking Classical Concurrency

Patterns](https://www.youtube.com/watch?v=5zXAHh5tJqQ) — 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