Go Concurrency
Goroutines, channels, context, and errgroup for Go 1.26 — plus the number-one
documented pitfall: leaking goroutines on an unbuffered channel + early return.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Map existing goroutine/channel/context usage
- fuse-ai-pilot:research-expert - Verify errgroup/context docs via Context7/Exa
- mcp__context7__query-docs - Confirm
golang.org/x/sync/errgroup signatures
After implementation, run fuse-ai-pilot:sniper for validation, and run tests
with go test -race ./....
Overview
| Feature |
Description |
| Goroutines & channels |
Lightweight concurrency + typed communication |
| errgroup |
Parallelism + error aggregation + context cancellation |
| context |
First param, propagated strictly, carries cancellation/deadline |
| WaitGroup vs channels |
Counting-only vs result/error passing |
| Race detector |
-race in tests/CI to catch data races |
| Leak profile (1.26) |
GOEXPERIMENT=goroutineleakprofile / /debug/pprof/goroutineleak |
Critical Rules
context.Context is the first parameter - named ctx, never stored in a struct
- Every started goroutine must be able to exit - or it leaks (see rule 4)
- Prefer
errgroup for fan-out with errors - it handles wait + first error + cancel
- Unbuffered channel + early return = leak - senders block forever; buffer or drain
- Test with
-race - a passing test without -race proves nothing about races
Architecture
internal/
├── fetch/
│ ├── fetch.go # errgroup.WithContext fan-out, bounded by SetLimit
│ └── worker.go # worker pool: fixed goroutines drain a jobs channel
└── pipeline/
└── stage.go # ctx-cancellable stages, buffered hand-off channels
→ See errgroup-patterns.md for full example
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| Goroutines & channels |
goroutines-channels.md |
Buffered vs not, select, WaitGroup vs channels |
| errgroup |
errgroup.md |
Fan-out, error aggregation, SetLimit, TryGo |
| context |
context-propagation.md |
Cancellation, deadlines, propagation rules |
| Goroutine leaks |
goroutine-leaks.md |
The #1 pitfall + the 1.26 leak profile |
Templates
| Template |
When to Use |
| errgroup-patterns.md |
Bounded parallel work with error handling |
| worker-pool.md |
Fixed workers draining a job queue |
Quick Reference
Parallel work with errgroup
g, ctx := errgroup.WithContext(ctx)
g.SetLimit(8) // bound concurrency
for _, u := range urls {
g.Go(func() error { return fetch(ctx, u) })
}
if err := g.Wait(); err != nil { // first non-nil error; cancels ctx
return err
}
→ See errgroup.md
Avoid the leak (buffer so senders never block)
ch := make(chan result, len(items)) // buffered → early return can't strand senders
→ See goroutine-leaks.md
Best Practices
DO
- Pass
ctx first and thread it through every blocking call
- Reach for
errgroup before hand-rolling WaitGroup + error channels
- Buffer result channels to the number of senders, or fully drain them
- Run
go test -race; try GOEXPERIMENT=goroutineleakprofile in CI (1.26)
DON'T
- Return early from a fan-out while goroutines still block on an unbuffered channel
- Store a
context.Context in a struct field
- Use a bare
sync.WaitGroup when goroutines return errors (use errgroup)
- Assume tests are race-free without the
-race flag
1---2name: go-concurrency3description: Use when writing or reviewing Go concurrency — goroutines, channels, errgroup, context cancellation, or goroutine leaks. Not for sequential idioms (go-core-idioms).4versions:5 go: "1.26"6 golang.org/x/sync: "latest"7user-invocable: false8references: references/goroutines-channels.md, references/errgroup.md, references/context-propagation.md, references/goroutine-leaks.md, references/templates/errgroup-patterns.md, references/templates/worker-pool.md9related-skills: go-core-idioms, solid-go10metadata:11 source: https://skillmd.com/skills/fusengine/go-concurrency12---1314<objective>15Covers Go concurrency for Go 1.26: goroutines and channels, golang.org/x/sync/errgroup,16context propagation and cancellation, sync.WaitGroup vs channels, the -race detector,17and diagnosing goroutine leaks (including the 1.26 goroutineleak profile). Does not18cover sequential error handling, slog, generics, or interface style (see19go-core-idioms), non-Go languages, or framework-specific code.20</objective>2122# Go Concurrency2324Goroutines, channels, `context`, and `errgroup` for Go 1.26 — plus the number-one25documented pitfall: **leaking goroutines on an unbuffered channel + early return.**2627## Agent Workflow (MANDATORY)2829Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:30311. **fuse-ai-pilot:explore-codebase** - Map existing goroutine/channel/context usage322. **fuse-ai-pilot:research-expert** - Verify errgroup/context docs via Context7/Exa333. **mcp__context7__query-docs** - Confirm `golang.org/x/sync/errgroup` signatures3435After implementation, run **fuse-ai-pilot:sniper** for validation, and run tests36with `go test -race ./...`.3738---3940## Overview4142| Feature | Description |43|---------|-------------|44| **Goroutines & channels** | Lightweight concurrency + typed communication |45| **errgroup** | Parallelism + error aggregation + context cancellation |46| **context** | First param, propagated strictly, carries cancellation/deadline |47| **WaitGroup vs channels** | Counting-only vs result/error passing |48| **Race detector** | `-race` in tests/CI to catch data races |49| **Leak profile (1.26)** | `GOEXPERIMENT=goroutineleakprofile` / `/debug/pprof/goroutineleak` |5051---5253## Critical Rules54551. **`context.Context` is the first parameter** - named `ctx`, never stored in a struct562. **Every started goroutine must be able to exit** - or it leaks (see rule 4)573. **Prefer `errgroup` for fan-out with errors** - it handles wait + first error + cancel584. **Unbuffered channel + early return = leak** - senders block forever; buffer or drain595. **Test with `-race`** - a passing test without `-race` proves nothing about races6061---6263## Architecture6465```66internal/67├── fetch/68│ ├── fetch.go # errgroup.WithContext fan-out, bounded by SetLimit69│ └── worker.go # worker pool: fixed goroutines drain a jobs channel70└── pipeline/71 └── stage.go # ctx-cancellable stages, buffered hand-off channels72```7374→ See [errgroup-patterns.md](references/templates/errgroup-patterns.md) for full example7576---7778## Reference Guide7980### Concepts8182| Topic | Reference | When to Consult |83|-------|-----------|-----------------|84| **Goroutines & channels** | [goroutines-channels.md](references/goroutines-channels.md) | Buffered vs not, select, WaitGroup vs channels |85| **errgroup** | [errgroup.md](references/errgroup.md) | Fan-out, error aggregation, SetLimit, TryGo |86| **context** | [context-propagation.md](references/context-propagation.md) | Cancellation, deadlines, propagation rules |87| **Goroutine leaks** | [goroutine-leaks.md](references/goroutine-leaks.md) | The #1 pitfall + the 1.26 leak profile |8889### Templates9091| Template | When to Use |92|----------|-------------|93| [errgroup-patterns.md](references/templates/errgroup-patterns.md) | Bounded parallel work with error handling |94| [worker-pool.md](references/templates/worker-pool.md) | Fixed workers draining a job queue |9596---9798## Quick Reference99100### Parallel work with errgroup101102```go103g, ctx := errgroup.WithContext(ctx)104g.SetLimit(8) // bound concurrency105for _, u := range urls {106 g.Go(func() error { return fetch(ctx, u) })107}108if err := g.Wait(); err != nil { // first non-nil error; cancels ctx109 return err110}111```112113→ See [errgroup.md](references/errgroup.md)114115### Avoid the leak (buffer so senders never block)116117```go118ch := make(chan result, len(items)) // buffered → early return can't strand senders119```120121→ See [goroutine-leaks.md](references/goroutine-leaks.md)122123---124125## Best Practices126127### DO128- Pass `ctx` first and thread it through every blocking call129- Reach for `errgroup` before hand-rolling `WaitGroup` + error channels130- Buffer result channels to the number of senders, or fully drain them131- Run `go test -race`; try `GOEXPERIMENT=goroutineleakprofile` in CI (1.26)132133### DON'T134- Return early from a fan-out while goroutines still block on an unbuffered channel135- Store a `context.Context` in a struct field136- Use a bare `sync.WaitGroup` when goroutines return errors (use `errgroup`)137- Assume tests are race-free without the `-race` flag