Golang Concurrency

1---2name: golang-concurrency3description: "Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues, or need to choose between channels and mutexes."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.1.2"10  openclaw:11    emoji: "⚡"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16    install: []17allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent AskUserQuestion18---19 20**Persona:** You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.21 22**Modes:**23 24- **Write mode** — implement concurrent code (goroutines, channels, sync primitives, worker pools, pipelines). Follow the sequential instructions below.25- **Review mode** — reviewing a PR's concurrent code changes. Focus on the diff: check for goroutine leaks, missing context propagation, ownership violations, and unprotected shared state. Sequential.26- **Audit mode** — auditing existing concurrent code across a codebase. Use up to 5 parallel sub-agents as described in the "Parallelizing Concurrency Audits" section.27 28> **Community default.** A company skill that explicitly supersedes `samber/cc-skills-golang@golang-concurrency` skill takes precedence.29 30# Go Concurrency Best Practices31 32Go's concurrency model is built on goroutines and channels. Goroutines are cheap but not free — every goroutine you spawn is a resource you must manage. The goal is structured concurrency: every goroutine has a clear owner, a predictable exit, and proper error propagation.33 34## Core Principles35 361. **Every goroutine must have a clear exit** — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes372. **Share memory by communicating** — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit383. **Send copies, not pointers** on channels — sending pointers creates invisible shared memory, defeating the purpose of channels394. **Only the sender closes a channel** — closing from the receiver side panics if the sender writes after close405. **Specify channel direction** (`chan<-`, `<-chan`) — the compiler prevents misuse at build time416. **Default to unbuffered channels** — larger buffers mask backpressure; use them only with measured justification427. **Always include `ctx.Done()` in select** — without it, goroutines leak after caller cancellation438. **Never use `time.After` in loops** — each call creates a timer that lives until it fires, accumulating memory. Use `time.NewTimer` + `Reset`449. **Track goroutine leaks in tests** with `go.uber.org/goleak`45 46For detailed channel/select code examples, see [Channels and Select Patterns](references/channels-and-select.md).47 48## Channel vs Mutex vs Atomic49 50| Scenario | Use | Why |51| --- | --- | --- |52| Passing data between goroutines | Channel | Communicates ownership transfer |53| Coordinating goroutine lifecycle | Channel + context | Clean shutdown with select |54| Protecting shared struct fields | `sync.Mutex` / `sync.RWMutex` | Simple critical sections |55| Simple counters, flags | `sync/atomic` | Lock-free, lower overhead |56| Many readers, few writers on a map | `sync.Map` | Optimized for read-heavy workloads. **Concurrent map read/write causes a hard crash** |57| Caching expensive computations | `sync.Once` / `singleflight` | Execute once or deduplicate |58 59## WaitGroup vs errgroup60 61| Need | Use | Why |62| --- | --- | --- |63| Wait for goroutines, errors not needed | `sync.WaitGroup` | Fire-and-forget |64| Wait + collect first error | `errgroup.Group` | Error propagation |65| Wait + cancel siblings on first error | `errgroup.WithContext` | Context cancellation on error |66| Wait + limit concurrency | `errgroup.SetLimit(n)` | Built-in worker pool |67 68## Sync Primitives Quick Reference69 70| Primitive | Use case | Key notes |71| --- | --- | --- |72| `sync.Mutex` | Protect shared state | Keep critical sections short; never hold across I/O |73| `sync.RWMutex` | Many readers, few writers | Never upgrade RLock to Lock (deadlock) |74| `sync/atomic` | Simple counters, flags | Prefer typed atomics (Go 1.19+): `atomic.Int64`, `atomic.Bool` |75| `sync.Map` | Concurrent map, read-heavy | No explicit locking; use `RWMutex`+map when writes dominate |76| `sync.Pool` | Reuse temporary objects | Always `Reset()` before `Put()`; reduces GC pressure |77| `sync.Once` | One-time initialization | Go 1.21+: `OnceFunc`, `OnceValue`, `OnceValues` |78| `sync.WaitGroup` | Wait for goroutine completion | `Add` before `go`; Go 1.24+: `wg.Go()` simplifies usage |79| `x/sync/singleflight` | Deduplicate concurrent calls | Cache stampede prevention |80| `x/sync/errgroup` | Goroutine group + errors | `SetLimit(n)` replaces hand-rolled worker pools |81 82For detailed examples and anti-patterns, see [Sync Primitives Deep Dive](references/sync-primitives.md).83 84## Concurrency Checklist85 86Before spawning a goroutine, answer:87 88- [ ] **How will it exit?** — context cancellation, channel close, or explicit signal89- [ ] **Can I signal it to stop?** — pass `context.Context` or done channel90- [ ] **Can I wait for it?** — `sync.WaitGroup` or `errgroup`91- [ ] **Who owns the channels?** — creator/sender owns and closes92- [ ] **Should this be synchronous instead?** — don't add concurrency without measured need93 94## Pipelines and Worker Pools95 96For pipeline patterns (fan-out/fan-in, bounded workers, generator chains, Go 1.23+ iterators, `samber/ro`), see [Pipelines and Worker Pools](references/pipelines.md).97 98## Parallelizing Concurrency Audits99 100When auditing concurrency across a large codebase, use up to 5 parallel sub-agents (Agent tool):101 1021. Find all goroutine spawns (`go func`, `go method`) and verify shutdown mechanisms1032. Search for mutable globals and shared state without synchronization1043. Audit channel usage — ownership, direction, closure, buffer sizes1054. Find `time.After` in loops, missing `ctx.Done()` in select, unbounded spawning1065. Check mutex usage, `sync.Map`, atomics, and thread-safety documentation107 108## Common Mistakes109 110| Mistake | Fix |111| --- | --- |112| Fire-and-forget goroutine | Provide stop mechanism (context, done channel) |113| Closing channel from receiver | Only the sender closes |114| `time.After` in hot loop | Reuse `time.NewTimer` + `Reset` |115| Missing `ctx.Done()` in select | Always select on context to allow cancellation |116| Unbounded goroutine spawning | Use `errgroup.SetLimit(n)` or semaphore |117| Sharing pointer via channel | Send copies or immutable values |118| `wg.Add` inside goroutine | Call `Add` before `go` — `Wait` may return early otherwise |119| Forgetting `-race` in CI | Always run `go test -race ./...` |120| Mutex held across I/O | Keep critical sections short |121 122## Cross-References123 124- -> See `samber/cc-skills-golang@golang-performance` skill for false sharing, cache-line padding, `sync.Pool` hot-path patterns125- -> See `samber/cc-skills-golang@golang-context` skill for cancellation propagation and timeout patterns126- -> See `samber/cc-skills-golang@golang-safety` skill for concurrent map access and race condition prevention127- -> See `samber/cc-skills-golang@golang-troubleshooting` skill for debugging goroutine leaks and deadlocks128- -> See `samber/cc-skills-golang@golang-design-patterns` skill for graceful shutdown patterns129 130## References131 132- [Go Concurrency Patterns: Pipelines](https://go.dev/blog/pipelines)133- [Effective Go: Concurrency](https://go.dev/doc/effective_go#concurrency)