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
- Move wg.Add(1) inside the goroutine and run the program twenty times. What is the failure mode, and does -race catch it?
- 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?
- 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.
-
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.
-
Why put wg.Done in a defer?
Answer
It runs on every return path and on a panic
A skipped Done makes Wait hang.
-
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.
-
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.
-
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.
-
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.
-
What does Wait do?
Answer
Blocks until the counter is zero
It is the join point.
-
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.
-
Which error wins in the hand-written collector?
Answer
The first one to take the lock
The mutex decides, not the wall clock.
-
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