Ausführbare Go-Docs: WaitGroup

Q: Wie funktioniert sync.WaitGroup in Go?

Eine WaitGroup ist ein Zähler. wg.Add(n) erhöht ihn, wg.Done() verringert ihn um eins, und wg.Wait() blockiert, bis er null erreicht. Ruf Add vor dem Start jeder Goroutine auf, defer wg.Done() in ihr und Wait dort, wo alles fertig sein muss.

Q: Sollte ich eine WaitGroup als Wert oder per Pointer übergeben?

Per Pointer (*sync.WaitGroup), oder lass Goroutinen sie in einer Closure einfangen. Eine Kopie hat ihren eigenen Zähler, also erreicht Done auf der Kopie nie das Original, und Wait blockiert für immer. go vet meldet den Fehler als „passes lock by value“.

Q: Was verursacht „sync: negative WaitGroup counter“?

Mehr Aufrufe von Done als von Add. Meist ruft eine Goroutine Done zweimal auf (einmal mit defer und einmal explizit), oder Add(1) wird auf einem Pfad übersprungen. Das Programm löst eine Panic aus, da der Zähler nichts Wahres mehr aussagen kann.

Das Grundmuster

sync.WaitGroup zählt laufende Goroutinen. Add erhöht den Zähler, Done verringert ihn, Wait blockiert, bis er null ist.

package main

import (
	"fmt"
	"sync"
	"time"
)

func download(name string) int {
	time.Sleep(10 * time.Millisecond) // pretend to work
	return len(name) * 100
}

func main() {
	files := []string{"a.txt", "report.pdf", "photo.jpg"}
	sizes := make([]int, len(files))

	var wg sync.WaitGroup
	for i, f := range files {
		wg.Add(1) // before the go statement
		go func() {
			defer wg.Done() // runs even if download panics
			sizes[i] = download(f)
		}()
	}
	wg.Wait()

	for i, f := range files {
		fmt.Printf("%-11s %d bytes\n", f, sizes[i])
	}
}

Die drei Downloads laufen nebenläufig, also braucht das Programm etwa 10 ms statt 30. Die Ergebnisse erscheinen in der Reihenfolge der Eingabe, weil jede Goroutine nur ihren eigenen Index von sizes schreibt und main sie erst nach Wait liest.

Der Nullwert einer WaitGroup ist einsatzbereit. Kein Konstruktor nötig.

Die drei Regeln

Ruf Add vor go auf, nicht in der Goroutine. Ruft die Goroutine Add selbst auf, kann main bei Wait ankommen, bevor irgendeine Goroutine gestartet ist, einen Zähler von null sehen und zurückkehren, obwohl die Arbeit noch nicht begonnen hat. Kennst du die Anzahl vorher, ist ein einmaliges wg.Add(len(files)) vor der Schleife gleichwertig.

Ruf Done mit defer in der ersten Zeile der Goroutine auf. Auch eine Goroutine, die bei einem Fehler früh zurückkehrt oder panict, verringert dann den Zähler. Ein fehlendes Done lässt Wait für immer blockieren. Ist es die letzte verbliebene Goroutine, meldet die Runtime fatal error: all goroutines are asleep mit sync.WaitGroup.Wait im Trace.

Kopier eine WaitGroup nach der ersten Verwendung nie. Übergib *sync.WaitGroup an Funktionen oder fang die Variable wie oben in einer Closure ein.

Eine WaitGroup an eine Funktion übergeben

Ist der Rumpf der Goroutine eine benannte Funktion, übergib einen Pointer:

package main

import (
	"fmt"
	"sync"
)

func worker(id int, wg *sync.WaitGroup, out []string) {
	defer wg.Done()
	out[id] = fmt.Sprintf("worker %d done", id)
}

func main() {
	var wg sync.WaitGroup
	out := make([]string, 3)

	for id := range 3 {
		wg.Add(1)
		go worker(id, &wg, out)
	}
	wg.Wait()

	for _, line := range out {
		fmt.Println(line)
	}
}

Mit wg sync.WaitGroup als Wertparameter würde jeder Worker Done auf seiner eigenen Kopie aufrufen, und main würde für immer in Wait blockieren. go vet findet das, bevor du irgendetwas ausführst:

./main.go:8:24: worker passes lock by value: sync.WaitGroup contains sync.noCopy

Ein saubereres Design hält die Nebenläufigkeit ganz aus worker heraus: Lass es eine einfache Funktion sein und erledige die Buchführung mit Add/Done in der Closure des Aufrufers. Dann ist worker leicht zu testen und synchron aufzurufen.

Negativer Zähler

Done ist Add(-1). Fällt der Zähler unter null, löst das Programm eine Panic aus:

package main

import (
	"fmt"
	"sync"
)

func main() {
	defer func() {
		fmt.Println("recovered:", recover())
	}()

	var wg sync.WaitGroup
	wg.Add(1)
	wg.Done()
	wg.Done() // one Done too many
}

Die Ausgabe ist recovered: sync: negative WaitGroup counter. Die übliche Ursache ist eine Goroutine mit defer wg.Done(), die auf irgendeinem Pfad zusätzlich explizit wg.Done() aufruft.

Fehler einsammeln

Eine WaitGroup zählt nur. Für Fehler gibst du jeder Goroutine ihren eigenen Platz und prüfst sie nach Wait:

package main

import (
	"errors"
	"fmt"
	"sync"
)

func check(host string) error {
	if host == "db" {
		return errors.New("db: connection refused")
	}
	return nil
}

func main() {
	hosts := []string{"web", "db", "cache"}
	errs := make([]error, len(hosts))

	var wg sync.WaitGroup
	for i, h := range hosts {
		wg.Add(1)
		go func() {
			defer wg.Done()
			errs[i] = check(h)
		}()
	}
	wg.Wait()

	if err := errors.Join(errs...); err != nil {
		fmt.Println("health check failed:", err)
		return
	}
	fmt.Println("all healthy")
}

errors.Join (Go 1.20) überspringt nil-Werte und gibt nil zurück, wenn alle nil sind. Damit fasst es „ein Fehler pro Goroutine“ ohne zusätzliche Buchführung zusammen.

Willst du die restliche Arbeit abbrechen, sobald eine Goroutine fehlschlägt, nimm stattdessen golang.org/x/sync/errgroup. Das ist eine WaitGroup plus der erste Fehler plus ein Context, der bei einem Fehlschlag abgebrochen wird, und g.SetLimit(n) begrenzt die Nebenläufigkeit. Es liegt außerhalb der Standardbibliothek und läuft daher nicht im Editor dieser Seite:

g, ctx := errgroup.WithContext(ctx)
for _, h := range hosts {
	g.Go(func() error { return checkCtx(ctx, h) })
}
if err := g.Wait(); err != nil {
	return err // the first error; ctx was cancelled for the others
}

Ein Worker-Pool

Eine feste Anzahl von Goroutinen, die Jobs aus einem Channel lesen, hält die Nebenläufigkeit begrenzt, egal wie viele Jobs es gibt. Die WaitGroup sagt dir, wann alle Worker fertig sind, und genau dann kann der Ergebnis-Channel geschlossen werden.

package main

import (
	"fmt"
	"sort"
	"sync"
)

type result struct {
	job, value, worker int
}

func main() {
	jobs := make(chan int)
	results := make(chan result)

	const workers = 3
	var wg sync.WaitGroup
	for w := 1; w <= workers; w++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for j := range jobs { // ends when jobs is closed
				results <- result{job: j, value: j * j, worker: w}
			}
		}()
	}

	// Close results once every worker has exited.
	go func() {
		wg.Wait()
		close(results)
	}()

	// Feed the jobs, then close the channel so workers stop.
	go func() {
		for j := 1; j <= 8; j++ {
			jobs <- j
		}
		close(jobs)
	}()

	var all []result
	for r := range results {
		all = append(all, r)
	}
	sort.Slice(all, func(a, b int) bool { return all[a].job < all[b].job })

	for _, r := range all {
		fmt.Printf("job %d -> %d\n", r.job, r.value)
	}
	fmt.Println("jobs done:", len(all))
}

Die Reihenfolge der drei Teile ist wichtig:

main muss Ergebnisse empfangen, während die Worker laufen. Würde main wg.Wait() direkt vor dem Lesen aufrufen, würden die Worker beim Senden auf results blockieren, nie Done erreichen, und alles würde im Deadlock enden. Deshalb läuft Wait in einer eigenen Goroutine.
close(results) passiert erst nach Wait, also kann kein Worker auf einen geschlossenen Channel senden.
Auch das Einspeisen der Jobs läuft in einer Goroutine, sodass sich Einspeisen und Einsammeln überlappen.

Welcher Worker welchen Job bearbeitet, ändert sich von Lauf zu Lauf, also sortiert das Programm vor der Ausgabe nach Job. Alles, was es ausgibt, ist deterministisch.

WaitGroup, Channel oder errgroup

Bedarf	Nimm
Auf N Goroutinen warten, Ergebnisse in indizierten Plätzen	`sync.WaitGroup`
Auf eine einzige Goroutine warten	einen `done`-Channel oder den Ergebnis-Channel selbst
Ergebnisse streamen, sobald sie fertig sind	einen Channel, geschlossen nach `wg.Wait()`
Beim ersten Fehler alles stoppen	`errgroup.WithContext`
Bei Timeout oder Abbruch durch den Aufrufer alles stoppen	`context.Context` plus WaitGroup oder errgroup

Go 1.25 führt wg.Go(func() { ... }) ein, das Add(1) und das per defer aufgerufene Done für dich erledigt. Code für Go 1.24 und älter, einschließlich des Editors dieser Seite, verwendet die oben gezeigte explizite Form.

Häufige Fehler

wg.Add(1) innerhalb der Goroutine. Wait kann zurückkehren, bevor es läuft.
Done bei einem frühen Return vergessen. Immer defer wg.Done().
Die WaitGroup als Wert übergeben. Nimm einen Pointer; go vet markiert die Kopie.
In derselben Goroutine warten, die einen Channel leeren muss. Verschieb wg.Wait() samt close in eine separate Goroutine.
Eine WaitGroup wiederverwenden, bevor das vorherige Wait zurückgekehrt ist. Beginne einen neuen Zyklus von Add-Aufrufen erst, wenn Wait fertig ist.

Häufig gestellte Fragen

Wie funktioniert sync.WaitGroup in Go?

Eine WaitGroup ist ein Zähler. wg.Add(n) erhöht ihn, wg.Done() verringert ihn um eins, und wg.Wait() blockiert, bis er null erreicht. Ruf Add vor dem Start jeder Goroutine auf, defer wg.Done() in ihr und Wait dort, wo alles fertig sein muss.

Sollte ich eine WaitGroup als Wert oder per Pointer übergeben?

Per Pointer (*sync.WaitGroup), oder lass Goroutinen sie in einer Closure einfangen. Eine Kopie hat ihren eigenen Zähler, also erreicht Done auf der Kopie nie das Original, und Wait blockiert für immer. go vet meldet den Fehler als „passes lock by value“.

Was verursacht „sync: negative WaitGroup counter“?

Mehr Aufrufe von Done als von Add. Meist ruft eine Goroutine Done zweimal auf (einmal mit defer und einmal explizit), oder Add(1) wird auf einem Pfad übersprungen. Das Programm löst eine Panic aus, da der Zähler nichts Wahres mehr aussagen kann.

Wie bekomme ich Fehler aus Goroutinen, die mit einer WaitGroup gestartet wurden?

Eine WaitGroup transportiert weder Ergebnisse noch Fehler. Gib jeder Goroutine ihren eigenen Platz in einem Slice von Fehlern und fasse sie nach Wait zusammen (zum Beispiel mit errors.Join), oder nimm golang.org/x/sync/errgroup, dessen Wait den ersten Fehler zurückgibt und die anderen über einen Context abbrechen kann.

Verwandte Konzepte