golang-concurrency

**Persona:** You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.

**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 `samber/cc-skills-golang@golang-concurrency` skill 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

1. **Every goroutine must have a clear exit** — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes
2. **Share memory by communicating** — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit
3. **Send copies, not pointers** on channels — sending pointers creates invisible shared memory, defeating the purpose of channels
4. **Only the sender closes a channel** — closing from the receiver side panics if the sender writes after close
5. **Specify channel direction** (`chan<-`, `<-chan`) — the compiler prevents misuse at build time
6. **Default to unbuffered channels** — larger buffers mask backpressure; use them only with measured justification
7. **Always include `ctx.Done()` in select** — without it, goroutines leak after caller cancellation
8. **Never use `time.After` in loops** — each call creates a timer that lives until it fires, accumulating memory. Use `time.NewTimer` + `Reset`
9. **Track goroutine leaks in tests** with `go.uber.org/goleak`

For detailed channel/select code examples, see [Channels and Select Patterns](references/channels-and-select.md).

## 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`      | Wait for goroutine completion | `Add` before `go`; Go 1.24+: `wg.Go()` simplifies usage        |
| `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](references/sync-primitives.md).

## 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.Context` or done channel
- [ ] **Can I wait for it?** — `sync.WaitGroup` or `errgroup`
- [ ] **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](references/pipelines.md).

## Parallelizing Concurrency Audits

When auditing concurrency across a large codebase, use up to 5 parallel sub-agents (Agent tool):

1. Find all goroutine spawns (`go func`, `go method`) and verify shutdown mechanisms
2. Search for mutable globals and shared state without synchronization
3. Audit channel usage — ownership, direction, closure, buffer sizes
4. Find `time.After` in loops, missing `ctx.Done()` in select, unbounded spawning
5. 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 `samber/cc-skills-golang@golang-performance` skill for false sharing, cache-line padding, `sync.Pool` hot-path patterns
- -> See `samber/cc-skills-golang@golang-context` skill for cancellation propagation and timeout patterns
- -> See `samber/cc-skills-golang@golang-safety` skill for concurrent map access and race condition prevention
- -> See `samber/cc-skills-golang@golang-troubleshooting` skill for debugging goroutine leaks and deadlocks
- -> See `samber/cc-skills-golang@golang-design-patterns` skill for graceful shutdown patterns

## References

- [Go Concurrency Patterns: Pipelines](https://go.dev/blog/pipelines)
- [Effective Go: Concurrency](https://go.dev/doc/effective_go#concurrency)