Concurrency: Goroutines & Channels

WaitGroup is simple in concept, but two specific mistakes account for almost every bug involving it.

Correct basic usage

var wg sync.WaitGroup

for i := 0; i < 5; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        fmt.Println("worker", id, "done")
    }(i)
}

wg.Wait()  // blocks until all 5 call Done()

Note Add(1) happens in the loop, before go func(...) starts — registering the count before the goroutine launches.

Mistake 1: calling Add too late

var wg sync.WaitGroup
go func() {
    wg.Add(1)         // BUG: race — Wait() below might already be past its check
    defer wg.Done()
    doWork()
}()
wg.Wait()

If Wait() runs before the goroutine gets to Add(1), the count is still zero, and Wait() returns immediately, before the work is actually done.

Mistake 2: passing WaitGroup by value

func startWorkers(wg sync.WaitGroup) {  // BUG: value receiver copies the WaitGroup
    wg.Add(1)                            // increments the copy's counter, not the caller's
    go func() {
        defer wg.Done()
        doWork()
    }()
}

func startWorkers(wg *sync.WaitGroup) {  // correct: pointer, shares the same counter
    wg.Add(1)
    go func() {
        defer wg.Done()
        doWork()
    }()
}

go vet catches this specific mistake (copying a sync.WaitGroup) automatically, which is one reason go vet should always run as part of CI.

The idiomatic pattern

Add before starting the goroutine, defer Done() as the first line inside it, and WaitGroup always shared by pointer. Following this exact shape avoids both common bugs.

context.Context is how Go plumbs "please stop" and "you have until X" through a call chain without every function needing bespoke cancellation logic.

Basic timeout usage

func fetchData(ctx context.Context, url string) ([]byte, error) {
    req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
data, err := fetchData(ctx, "https://example.com")

If the request takes longer than 3 seconds, the context's Done() channel closes, and http.NewRequestWithContext makes the underlying request abort with a context-deadline error.

Propagation through a call tree

ctx, cancel := context.WithCancel(context.Background())

go worker(ctx)      // derived context
go anotherWorker(ctx)

cancel()  // both worker and anotherWorker see ctx.Done() close, and can exit

Calling cancel() once cancels every goroutine that was handed this same ctx (or any context derived further from it), which is what makes context-based cancellation scale to a whole tree of concurrent work from a single call.

A function that respects cancellation

func worker(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("cancelled:", ctx.Err())
            return
        case <-time.After(500 * time.Millisecond):
            fmt.Println("still working")
        }
    }
}

The convention to follow

Always accept ctx context.Context as the first parameter, never store it inside a struct, and always call the cancel function returned by WithCancel/WithTimeout/WithDeadline (usually via defer cancel()) to release the context's resources even if it wasn't triggered by a timeout.

This is one of the more subtle Go topics, but the practical takeaway is simple: don't share data across goroutines without going through a synchronization primitive.

Why "it works in my test" isn't proof

var ready bool
var data int

go func() {
    data = 42
    ready = true   // no synchronization with the reader
}()

for !ready {}      // BUG: data race, and the compiler may cache "ready" in a register forever
fmt.Println(data)

Without a happens-before relationship between the write to ready/data and the read of them, the compiler is allowed to assume nothing else changes ready, and might optimize the for !ready {} loop into an infinite loop that never re-reads memory. This isn't a hypothetical: it's a real category of bug the race detector exists specifically to catch.

What actually establishes happens-before

// Channel send/receive
ch := make(chan int)
go func() {
    data := 42
    ch <- data     // send happens-before the matching receive completes
}()
v := <-ch          // guaranteed to observe everything written before the send

// Mutex lock/unlock
var mu sync.Mutex
var data int

go func() {
    mu.Lock()
    data = 42
    mu.Unlock()    // unlock happens-before a later goroutine's Lock() on the same mutex
}()

mu.Lock()
fmt.Println(data)  // guaranteed to see 42, since this Lock() happens-after the other goroutine's Unlock()
mu.Unlock()

The practical rule

Never read or write a variable from more than one goroutine unless every access goes through a channel, a mutex, or the sync/atomic package. "It passed my tests" doesn't mean a race-free program. Always run go test -race (or build with -race) to have the runtime's race detector actually check for unsynchronized concurrent access.

A data race in Go isn't just "you might read a stale value." It's genuinely undefined behavior, which is why the race detector is considered essential tooling, not optional.

A race, and what -race reports

func main() {
    counter := 0
    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            counter++   // unsynchronized read-modify-write: a data race
        }()
    }
    wg.Wait()
    fmt.Println(counter)  // often not 1000, and the race itself is the real bug
}

go run -race main.go

WARNING: DATA RACE
Read at 0x00c0000140a0 by goroutine 8:
  main.main.func1()
      main.go:12 +0x3c
Previous write at 0x00c0000140a0 by goroutine 7:
  main.main.func1()
      main.go:12 +0x52

The detector pinpoints the exact line and both goroutines involved, which is far more actionable than debugging an intermittent wrong answer by hand.

Fixing it

var mu sync.Mutex
counter := 0
// ... inside the goroutine:
mu.Lock()
counter++
mu.Unlock()

Or, for a simple counter, sync/atomic:

var counter int64
atomic.AddInt64(&counter, 1)

The detector's real limitation

-race only flags races that happen during the specific execution you ran. A race that only triggers under a rare goroutine interleaving might not show up in a quick test run, but could still exist in the code. Running the race detector broadly, and running concurrency-heavy tests repeatedly under load, meaningfully increases the odds of catching a race. It's still not a formal proof of race-freedom, the way a static analyzer might aim for.

Spawning a goroutine per task is fine for a handful of tasks, but a worker pool caps concurrency when you have many tasks or a rate-sensitive downstream dependency.

A basic worker pool

func worker(id int, jobs <-chan int, results chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()
    for j := range jobs {           // exits automatically once jobs is closed and drained
        results <- j * j
    }
}

func main() {
    jobs := make(chan int, 100)
    results := make(chan int, 100)
    var wg sync.WaitGroup

    const numWorkers = 5
    for w := 1; w <= numWorkers; w++ {
        wg.Add(1)
        go worker(w, jobs, results, &wg)
    }

    for j := 1; j <= 20; j++ {
        jobs <- j
    }
    close(jobs)   // signals workers: no more jobs coming

    wg.Wait()
    close(results)

    for r := range results {
        fmt.Println(r)
    }
}

Why bound concurrency at all

If each of 10,000 tasks makes an outbound API call, spawning 10,000 goroutines at once could open 10,000 simultaneous connections, likely tripping rate limits or overwhelming the remote service. A worker pool with, say, 20 workers processes the same 10,000 tasks with at most 20 concurrent outbound calls, trading total throughput for predictable, bounded load.

Choosing the pool size

There's no universal right number. CPU-bound work often benefits from a pool size near runtime.NumCPU(). I/O-bound work (network calls, disk access) can often use a much larger pool, since workers spend most of their time waiting, not consuming CPU. The right size is usually found by benchmarking against the actual downstream constraint, like a rate limit or connection pool size.

This is probably the single most famous Go gotcha, common enough that the language itself changed to eliminate it by default.

The bug, pre-Go 1.22

items := []string{"a", "b", "c"}
var wg sync.WaitGroup

for _, v := range items {
    wg.Add(1)
    go func() {
        defer wg.Done()
        fmt.Println(v)   // BUG (pre-1.22): all three goroutines may print "c"
    }()
}
wg.Wait()

All three closures captured a reference to the same v variable, which the loop kept reassigning. By the time the goroutines actually ran, the loop had likely already finished, leaving v at its final value, "c", for every closure to see.

The traditional fix (still valid, still seen in real code)

for _, v := range items {
    v := v  // shadow: creates a new variable per iteration
    wg.Add(1)
    go func() {
        defer wg.Done()
        fmt.Println(v)
    }()
}

Or, equivalently, pass v as a parameter to the closure:

go func(v string) {
    defer wg.Done()
    fmt.Println(v)
}(v)

The Go 1.22 fix

Starting with Go 1.22 (and only for modules whose go.mod declares go 1.22 or later), the language spec changed so each loop iteration gets its own copy of the loop variable automatically. The exact same original code, with no v := v shadow and no parameter trick, now prints "a", "b", "c" correctly.

Why this still matters in interviews

Plenty of production code still targets pre-1.22 semantics, or was written before the change and never revisited. Understanding why the bug happened, plus both fixes, is exactly the kind of "gotcha" question that comes up constantly in Go interviews. That's true no matter which Go version a specific codebase targets today.