golang-concurrency
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.
- License 许可
- MIT
- 最近更新
- 2026-08-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- golang-concurrency
- license
- MIT
- metadata
- { "author": "gentleman-programming", "version": "1.1.5", "openclaw": { "emoji": "⚡", "install": [], "homepage": "https://github.com/gentleman-programming", "requires": { "bins": [ "go" ] } } }
- description
- 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.
- allowed-tools
- Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent AskUserQuestion
- compatibility
- Designed for OpenCode or similar AI coding agents, and for projects using Golang.
- user-invocable
- true
02 资源文件 4
- 参考文档evals/evals.json14.7 KB
- 参考文档references/channels-and-select.md3.9 KB
- 参考文档references/pipelines.md6.7 KB
- 参考文档references/sync-primitives.md8.1 KB
03 SKILL.md 正文
Persona: You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.
Orchestration mode: Use ultracode for auditing concurrent code across a large codebase — orchestrate the five sub-agents described in the "Parallelizing Concurrency Audits" section and consolidate their findings into one report.
Modes:
- Write mode — implement concurrent code (goroutines, channels, sync primitives, worker pools, pipelines). Follow the sequential instructions below.
- 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.
- Audit mode — auditing existing concurrent code across a codebase. Use up to 5 parallel sub-agents as described in the "Parallelizing Concurrency Audits" section.
Community default. A company skill that explicitly supersedes
golang-concurrencyskill takes precedence.
Go Concurrency Best Practices
Go'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.
Core Principles
- Every goroutine must have a clear exit — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes
- Share memory by communicating — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit
- Send copies, not pointers on channels — sending pointers creates invisible shared memory, defeating the purpose of channels
- Only the sender closes a channel — closing from the receiver side panics if the sender writes after close
- Specify channel direction (
chan<-,<-chan) — the compiler prevents misuse at build time - Default to unbuffered channels — larger buffers mask backpressure; use them only with measured justification
- Always include
ctx.Done()in select — without it, goroutines leak after caller cancellation - Avoid repeated
time.Afterin hot loops — each call allocates a timer and creates unnecessary churn; usetime.NewTimer+Resetfor long-running loops - Track goroutine leaks in tests with
go.uber.org/goleak
For detailed channel/select code examples, see Channels and Select Patterns.
Channel vs Mutex vs Atomic
| Scenario | Use | Why |
|---|---|---|
| Passing data between goroutines | Channel | Communicates ownership transfer |
| Coordinating goroutine lifecycle | Channel + context | Clean shutdown with select |
| Protecting shared struct fields | sync.Mutex / sync.RWMutex |
Simple critical sections |
| Simple counters, flags | sync/atomic |
Lock-free, lower overhead |
| Many readers, few writers on a map | sync.Map |
Optimized for read-heavy workloads. Concurrent map read/write causes a hard crash |
| Caching expensive computations | sync.Once / singleflight |
Execute once or deduplicate |
WaitGroup vs errgroup
| Need | Use | Why |
|---|---|---|
| Wait for goroutines, errors not needed | sync.WaitGroup |
Fire-and-forget |
| Wait + collect first error | errgroup.Group |
Error propagation |
| Wait + cancel siblings on first error | errgroup.WithContext |
Context cancellation on error |
| Wait + limit concurrency | errgroup.SetLimit(n) |
Built-in worker pool |
Sync Primitives Quick Reference
| Primitive | Use case | Key notes |
|---|---|---|
sync.Mutex |
Protect shared state | Keep critical sections short; never hold across I/O |
sync.RWMutex |
Many readers, few writers | Never upgrade RLock to Lock (deadlock) |
sync/atomic |
Simple counters, flags | Prefer typed atomics (Go 1.19+): atomic.Int64, atomic.Bool |
sync.Map |
Concurrent map, read-heavy | No explicit locking; use RWMutex+map when writes dominate |
sync.Pool |
Reuse temporary objects | Always Reset() before Put(); reduces GC pressure |
sync.Once |
One-time initialization | Go 1.21+: OnceFunc, OnceValue, OnceValues |
sync.WaitGroup |
Waiting for simple goroutines | Go 1.25+: prefer wg.Go(func(){ ... }) for fire-and-wait tasks that do not panic and do not need error propagation. For Go <1.25 use Add/Done. For errors/cancellation/limits, use errgroup with context. |
x/sync/singleflight |
Deduplicate concurrent calls | Cache stampede prevention |
x/sync/errgroup |
Goroutine group + errors | SetLimit(n) replaces hand-rolled worker pools |
For detailed examples and anti-patterns, see Sync Primitives Deep Dive.
Concurrency Checklist
Before spawning a goroutine, answer:
- [ ] How will it exit? — context cancellation, channel close, or explicit signal
- [ ] Can I signal it to stop? — pass
context.Contextor done channel - [ ] Can I wait for it? —
sync.WaitGrouporerrgroup - [ ] Who owns the channels? — creator/sender owns and closes
- [ ] Should this be synchronous instead? — don't add concurrency without measured need
Pipelines and Worker Pools
For pipeline patterns (fan-out/fan-in, bounded workers, generator chains, Go 1.23+ iterators, samber/ro), see Pipelines and Worker Pools.
Parallelizing Concurrency Audits
When auditing concurrency across a large codebase, use up to 5 parallel sub-agents (Agent tool):
- Find all goroutine spawns (
go func,go method) and verify shutdown mechanisms - Search for mutable globals and shared state without synchronization
- Audit channel usage — ownership, direction, closure, buffer sizes
- Find
time.Afterin loops, missingctx.Done()in select, unbounded spawning - Check mutex usage,
sync.Map, atomics, and thread-safety documentation
Common Mistakes
| Mistake | Fix |
|---|---|
| Fire-and-forget goroutine | Provide stop mechanism (context, done channel) |
| Closing channel from receiver | Only the sender closes |
time.After in hot loop |
Reuse time.NewTimer + Reset |
Missing ctx.Done() in select |
Always select on context to allow cancellation |
| Unbounded goroutine spawning | Use errgroup.SetLimit(n) or semaphore |
| Sharing pointer via channel | Send copies or immutable values |
wg.Add inside goroutine |
Call Add before go — Wait may return early otherwise |
Forgetting -race in CI |
Always run go test -race ./... |
| Mutex held across I/O | Keep critical sections short |
Cross-References
- -> See
golang-performanceskill for false sharing, cache-line padding,sync.Poolhot-path patterns - -> See
golang-contextskill for cancellation propagation and timeout patterns - -> See
golang-safetyskill for concurrent map access and race condition prevention - -> See
golang-troubleshootingskill for debugging goroutine leaks and deadlocks - -> See
golang-design-patternsskill for graceful shutdown patterns - -> See
golang-continuous-integrationskill for automated AI-driven code review in CI using these guidelines
Go 1.26 experimental goroutine leak profile
For Go 1.26 diagnostics, there is an experimental goroutine leak profile. It is useful for production-oriented leak investigation, but is gated by GOEXPERIMENT=goroutineleakprofile; do not rely on it as default stable behavior.
Typical usage when the experiment is enabled:
curl http://localhost:6060/debug/pprof/goroutineleak?debug=2
go tool pprof http://localhost:6060/debug/pprof/goroutineleak
Keep existing tools:
- tests:
go.uber.org/goleak - runtime count:
runtime.NumGoroutine() - stack dump:
/debug/pprof/goroutine?debug=2 - race checks:
go test -race ./...
References
04 同仓库更多 Skills
zustand-5
Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
zod-4
Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
x-bookmark-quote-posts
Workflow para revisar bookmarks de X/Twitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.