sync.WaitGroup and structured waits

sync.WaitGroup is the join of Go: the program says how many goroutines it is starting, each one reports when it is done, and one Wait blocks until the count is zero. The order of the three calls matters more than their syntax, and the panics below are the ones a wrong order produces.

Three workers and a slice

Each goroutine writes its own index of the result slice, so no two goroutines touch the same memory and no lock is needed. Add runs in the loop before the goroutine starts: calling it inside the goroutine is the classic race, because Wait may return before the counter was ever raised. The printed order comes from the slice, not from the goroutines.

package main import ( "fmt" "sync" ) func main() { var wg sync.WaitGroup results := make([]int, 3) for i := 0; i < 3; i++ { wg.Add(1) go func() { defer wg.Done() results[i] = (i + 1) * 10 }() } wg.Wait() for i, r := range results { fmt.Printf("worker %d: %d\n", i, r) } }

go build -o app main.go && ./app

worker 0: 10
worker 1: 20
worker 2: 30

The slice is the result channel of this program: each worker has a slot of its own, so the output is stable without sorting and without a mutex. A slice of one value per worker is the cheapest way to keep the order of the work when the work is indexed by a number.

Done on every path

A worker can return early, and a worker can panic. defer wg.Done() covers both: it runs when the function returns, whichever branch returned it. The program below has one worker that skips its work and two that do it; the skip still calls Done, so the wait ends.

package main import ( "fmt" "sync" ) func process(id int, wg *sync.WaitGroup) { defer wg.Done() if id%2 == 0 { fmt.Println("skip", id) return } fmt.Println("work", id) } func main() { var wg sync.WaitGroup for i := 1; i <= 3; i++ { wg.Add(1) go process(i, &wg) } wg.Wait() fmt.Println("done") }

go build -o app main.go && ./app

work 3
work 1
skip 2
done

The two work lines came in the scheduler's order; the skip line and the final done are the parts that matter. Passing the group as a pointer is what makes the worker share the counter: a sync.WaitGroup passed by value is a copy with its own count, and vet reports it as a copied lock.

The counter below zero

A Done without an Add decrements the counter below zero, and the runtime panics rather than hide the bug: the program says that some goroutine finished that nobody was waiting for. The same panic comes from a worker that calls Done twice, which is why the defer is the only Done in the function.

package main import "sync" func main() { var wg sync.WaitGroup wg.Add(1) wg.Done() wg.Done() }

go build -trimpath -o app main.go && ./app

panic: sync: negative WaitGroup counter

goroutine 1 [running]:
sync.(*WaitGroup).Add(0x1a530c11c000, 0xffffffffffffffff)
sync/waitgroup.go:118 +0x23a
sync.(*WaitGroup).Done(...)
sync/waitgroup.go:156
main.main()
./main.go:9 +0x4d
exit status: 2

The trace names the second Done, the line of main and the runtime function behind it. A wait that never ends is the other side of the same mistake: an Add that no goroutine ever matches leaves the program blocked in Wait until the test timeout reports it.

The first error, and what errgroup adds

A group of workers that can fail needs to keep the first error and still wait for the rest. The program below does it by hand: a mutex around the error variable and a small helper that records only the first non-nil error. golang.org/x/sync/errgroup is the same idea in a package, with a context that is cancelled when the first worker fails; that module is not in this image, so the page shows the hand-written version and names the package without inventing its output.

package main import ( "errors" "fmt" "sync" ) func main() { var wg sync.WaitGroup var mu sync.Mutex var firstErr error fail := func(err error) { mu.Lock() defer mu.Unlock() if firstErr == nil { firstErr = err } } for i := 1; i <= 3; i++ { wg.Add(1) go func() { defer wg.Done() if i == 2 { fail(errors.New("task 2 failed")) } }() } wg.Wait() fmt.Println("first error:", firstErr) }

go build -o app main.go && ./app

first error: task 2 failed

The error that comes out is the first one recorded, not the first one in time: with two failing workers the one that takes the lock first wins. An errgroup would cancel the rest through a context at that moment, which is the difference between "wait for all of them" and "stop the ones that are still running".

Exercises

  1. Move wg.Add(1) inside the goroutine and run the program twenty times. What is the failure mode, and does -race catch it?
  2. Return from the middle of the worker without a defer and watch the program hang. Which goroutine is still waiting, and what does the test timeout print?
  3. Add a fourth worker that also fails and see which error is reported. Why is the answer not necessarily the worker with the lower id?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is the order of the three WaitGroup calls?

    Answer

    Add before the goroutine, Done in it, Wait after the loop

    Add must happen before Wait can see a zero counter.

  2. Why put wg.Done in a defer?

    Answer

    It runs on every return path and on a panic

    A skipped Done makes Wait hang.

  3. What does calling Add inside the goroutine risk?

    Answer

    Wait returning before the counter is raised

    The group can be at zero when Wait reads it.

  4. What happens when Done is called more often than Add?

    Answer

    The counter goes negative and the runtime panics

    The panic is sync: negative WaitGroup counter.

  5. Why does the worker take a *sync.WaitGroup?

    Answer

    Because a copy has its own counter

    A WaitGroup passed by value is a different group.

  6. How does the first program keep a stable order without a lock?

    Answer

    Each worker writes its own index of the slice

    Separate slots need no synchronisation.

  7. What does Wait do?

    Answer

    Blocks until the counter is zero

    It is the join point.

  8. What does golang.org/x/sync/errgroup add?

    Answer

    A context cancelled on the first error and a first-error return

    It wraps the wait and the error together.

  9. Which error wins in the hand-written collector?

    Answer

    The first one to take the lock

    The mutex decides, not the wall clock.

  10. What does a hang in Wait usually mean?

    Answer

    An Add with no matching Done

    The counter never reaches zero.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev