Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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-foundations

About 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.
  • GOMAXPROCS limits 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

  1. Start with a correct sequential version.
  2. Profile and benchmark to confirm the bottleneck.
  3. Introduce concurrency with a tunable threshold or pool size.
  4. Benchmark the concurrent version -- if it is not measurably faster, keep the sequential one.

3. Channels vs Mutexes (#57)

Use this decision guide:

SituationPrefer
Parallel goroutines accessing/mutating a shared resourcesync.Mutex (or sync/atomic)
Concurrent goroutines that need to coordinate, signal, or transfer ownershipChannels
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 nextChannels
  • 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:

  1. Atomic operations -- sync/atomic for simple numeric types.
  2. Mutex -- sync.Mutex / sync.RWMutex to guard a critical section.
  3. 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:

  1. Goroutine creation happens-before the goroutine starts executing.
  2. Goroutine exit is NOT guaranteed to happen before any event -- always synchronize if the parent reads state written by the child.
  3. Channel send happens-before the corresponding receive completes.
  4. Channel close happens-before a receive observing the closure.
  5. 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

5. Worker Pool Sizing by Workload Type (#59

Read the complete source ↗