go-concurrency-foundations
Guides the agent to avoid foundational concurrency mistakes in Go: confusing concurrency with parallelism, assuming concurrency is always faster, misusing channels vs mutexes, ignoring data races and race conditions, mis-sizing worker pools for CPU- vs I/O-bound work, and misunderstanding Go contexts. Use when writing, reviewing, or refactoring any concurrent Go code, goroutines, channels, mutexes, worker pools, or context usage.
v0lka · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add v0lka/skills --skill go-concurrency-foundationsAbout this skill
name: go-concurrency-foundations description: > Guides the agent to avoid foundational concurrency mistakes in Go: confusing concurrency with parallelism, assuming concurrency is always faster, misusing channels vs mutexes, ignoring data races and race conditions, mis-sizing worker pools for CPU- vs I/O-bound work, and misunderstanding Go contexts. Use when writing, reviewing, or refactoring any concurrent Go code, goroutines, channels, mutexes, worker pools, or context usage.
Go Concurrency Foundations
Rules derived from "100 Go Mistakes" #55-#60. Apply whenever writing or reviewing concurrent Go code.
1. Concurrency vs Parallelism (#55)
- Concurrency is about structure -- decomposing a problem into independently executing steps that coordinate.
- Parallelism is about execution -- running the same step on multiple cores simultaneously.
- Concurrency enables parallelism but is not the same thing.
- When restructuring code, ask: "Am I changing the structure (concurrency) or adding more workers to the same step (parallelism)?"
2. Concurrency Is Not Always Faster (#56)
Go scheduling essentials
- Goroutines are multiplexed onto OS threads (M) by the Go runtime, not the OS.
GOMAXPROCSlimits the number of OS threads executing user-level Go code simultaneously (defaults to logical CPU count since Go 1.5).- The scheduler uses per-P local queues, a global queue, and work stealing.
- Since Go 1.14 the scheduler is preemptive (10 ms time slice).
Key rule: small workloads kill parallelism
Spinning up a goroutine per tiny unit of work makes things slower -- the goroutine creation and scheduling overhead dominates. Always use a threshold to fall back to sequential execution for small inputs.
const threshold = 2048 // tune via benchmarks on target hardware
func parallelMergesort(s []int) {
if len(s) <= 1 {
return
}
if len(s) <= threshold {
sequentialMergesort(s) // fall back to sequential
return
}
middle := len(s) / 2
var wg sync.WaitGroup
wg.Add(2)
go func() {
defer wg.Done()
parallelMergesort(s[:middle])
}()
go func() {
defer wg.Done()
parallelMergesort(s[middle:])
}()
wg.Wait()
merge(s, middle)
}
Checklist before adding concurrency
- Start with a correct sequential version.
- Profile and benchmark to confirm the bottleneck.
- Introduce concurrency with a tunable threshold or pool size.
- Benchmark the concurrent version -- if it is not measurably faster, keep the sequential one.
3. Channels vs Mutexes (#57)
Use this decision guide:
| Situation | Prefer |
|---|---|
| Parallel goroutines accessing/mutating a shared resource | sync.Mutex (or sync/atomic) |
| Concurrent goroutines that need to coordinate, signal, or transfer ownership | Channels |
| Signaling completion or readiness (with or without data) | Channels (chan struct{} for no data) |
| Protecting a critical section (read/write to shared state) | sync.Mutex / sync.RWMutex |
| Transferring ownership of a resource from one stage to the next | Channels |
- Do NOT force channels everywhere just because Go says "share memory by communicating." Mutexes and channels are complementary.
- If goroutines are parallel (same step, multiple workers): think mutexes.
- If goroutines are concurrent (different steps in a pipeline): think channels.
4. Data Races vs Race Conditions (#58)
Definitions
- Data race: two+ goroutines access the same memory location concurrently and
at least one writes. Detected by
go test -race/go run -race. - Race condition: behavior depends on uncontrolled timing of events. A data-race-free program can still have race conditions.
Eliminating data races does NOT guarantee deterministic results.
Preventing data races
Choose one of:
- Atomic operations --
sync/atomicfor simple numeric types. - Mutex --
sync.Mutex/sync.RWMutexto guard a critical section. - Channel communication -- ensure only one goroutine writes to the variable.
// BAD -- data race
i := 0
go func() { i++ }()
go func() { i++ }()
// GOOD -- atomic
var i int64
go func() { atomic.AddInt64(&i, 1) }()
go func() { atomic.AddInt64(&i, 1) }()
// GOOD -- mutex
var mu sync.Mutex
i := 0
go func() { mu.Lock(); i++; mu.Unlock() }()
go func() { mu.Lock(); i++; mu.Unlock() }()
// GOOD -- channel (only parent writes)
ch := make(chan int)
go func() { ch <- 1 }()
go func() { ch <- 1 }()
i := <-ch + <-ch
Race condition (data-race-free but non-deterministic)
// No data race, but i is unpredictably 1 or 2
var mu sync.Mutex
i := 0
go func() { mu.Lock(); i = 1; mu.Unlock() }()
go func() { mu.Lock(); i = 2; mu.Unlock() }()
To enforce ordering, use channels for coordination, not just mutexes.
Go memory model guarantees
Memorize these ordering rules:
- Goroutine creation happens-before the goroutine starts executing.
- Goroutine exit is NOT guaranteed to happen before any event -- always synchronize if the parent reads state written by the child.
- Channel send happens-before the corresponding receive completes.
- Channel close happens-before a receive observing the closure.
- Unbuffered channel receive happens-before the send completes.
- This means with an unbuffered channel, a write before the receive is guaranteed visible after the send returns.
- This guarantee does NOT hold for buffered channels.
// SAFE -- unbuffered channel guarantees ordering
i := 0
ch := make(chan struct{})
go func() {
i = 1
<-ch
}()
ch <- struct{}{}
fmt.Println(i) // guaranteed to print 1
// UNSAFE -- buffered channel, data race on i
ch := make(chan struct{}, 1)
go func() {
i = 1
<-ch
}()
ch <- struct{}{}
fmt.Println(i) // data race