go-concurrency

Go Concurrency

Goroutines, channels, context, and errgroup for Go 1.27 — 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:

1. fuse-ai-pilot:explore-codebase - Map existing goroutine/channel/context usage
2. fuse-ai-pilot:research-expert - Verify errgroup/context docs via Context7/Exa
3. 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 (GA 1.27)	pprof.Lookup("goroutineleak") / /debug/pprof/goroutineleak — no GOEXPERIMENT needed

---

Critical Rules

1. context.Context is the first parameter - named ctx, never stored in a struct
2. Every started goroutine must be able to exit - or it leaks (see rule 4)
3. Prefer errgroup for fan-out with errors - it handles wait + first error + cancel
4. Unbuffered channel + early return = leak - senders block forever; buffer or drain
5. 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 goroutineleak profile (GA 1.27)

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; check the goroutineleak profile in CI (GA in 1.27; the 1.26 GOEXPERIMENT=goroutineleakprofile flag is deleted)

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