Dokumentacja Go z przykładami: WaitGroup

Q: Jak działa sync.WaitGroup w Go?

WaitGroup to licznik. wg.Add(n) go zwiększa, wg.Done() zmniejsza o jeden, a wg.Wait() blokuje, dopóki nie osiągnie zera. Wywołaj Add przed uruchomieniem każdej goroutine, defer wg.Done() wewnątrz niej, a Wait tam, gdzie wszystko musi być skończone.

Q: Czy WaitGroup przekazywać przez wartość, czy przez wskaźnik?

Przez wskaźnik (*sync.WaitGroup) albo pozwól goroutine przechwycić go w domknięciu. Kopia ma własny licznik, więc Done na kopii nigdy nie dociera do oryginału, a Wait blokuje na zawsze. go vet zgłasza ten błąd jako "passes lock by value".

Q: Co powoduje "sync: negative WaitGroup counter"?

Więcej wywołań Done niż Add. Zwykle goroutine wywołuje Done dwa razy (raz przez defer i raz jawnie) albo na jednej ze ścieżek pominięto Add(1). Program wywołuje panic, bo licznik nie może już powiedzieć niczego prawdziwego.

Podstawowy wzorzec

sync.WaitGroup liczy działające goroutine. Add zwiększa licznik, Done go zmniejsza, a Wait blokuje, dopóki nie wyniesie zera.

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])
	}
}

Trzy pobierania działają współbieżnie, więc program trwa około 10 ms zamiast 30. Wyniki są wypisywane w kolejności wejścia, bo każda goroutine zapisuje tylko własny indeks w sizes, a main odczytuje je dopiero po Wait.

Wartość zerowa WaitGroup jest gotowa do użycia. Bez konstruktora.

Trzy zasady

Wywołuj Add przed go, a nie wewnątrz goroutine. Jeśli goroutine sama wywołuje Add, main może dojść do Wait, zanim którakolwiek goroutine wystartuje, zobaczyć licznik równy zero i zakończyć działanie, zanim praca się zaczęła. Gdy znasz liczbę z góry, jedno wg.Add(len(files)) przed pętlą działa tak samo.

Wywołuj Done przez defer w pierwszej linii goroutine. Goroutine, która wraca wcześniej z powodu błędu albo wywołuje panic, i tak zmniejsza licznik. Brakujące Done zostawia Wait zablokowane na zawsze. Jeśli to jedyna pozostała goroutine, runtime zgłasza fatal error: all goroutines are asleep z sync.WaitGroup.Wait w śladzie stosu.

Nigdy nie kopiuj WaitGroup po pierwszym użyciu. Przekazuj do funkcji *sync.WaitGroup albo przechwyć zmienną w domknięciu, jak powyżej.

Przekazywanie WaitGroup do funkcji

Gdy ciało goroutine to nazwana funkcja, przekaż wskaźnik:

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)
	}
}

Z parametrem wg sync.WaitGroup przekazywanym przez wartość każdy worker wywoływałby Done na własnej kopii, a main blokowałby się w Wait na zawsze. go vet wyłapuje to, zanim cokolwiek uruchomisz:

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

Czystszy projekt w ogóle trzyma współbieżność poza worker: niech to będzie zwykła funkcja, a księgowość Add/Done odbywa się w domknięciu po stronie wywołującego. Wtedy worker łatwo przetestować i wywołać synchronicznie.

Ujemny licznik

Done to Add(-1). Jeśli licznik spadnie poniżej zera, program wywołuje panic:

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
}

Wynik to recovered: sync: negative WaitGroup counter. Zwykle przyczyną jest goroutine z defer wg.Done(), która na jakiejś ścieżce wywołuje też jawnie wg.Done().

Zbieranie błędów

WaitGroup tylko liczy. Dla błędów daj każdej goroutine własne miejsce i sprawdź je po 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) pomija wartości nil i zwraca nil, jeśli wszystkie są nil, więc łączy zasadę „jeden błąd na goroutine” bez dodatkowej księgowości.

Jeśli chcesz zatrzymać pozostałą pracę, gdy tylko jedna goroutine zawiedzie, użyj zamiast tego golang.org/x/sync/errgroup. To WaitGroup plus pierwszy błąd plus kontekst anulowany przy porażce, a g.SetLimit(n) ogranicza współbieżność. Pakiet jest poza biblioteką standardową, więc nie da się go uruchomić w edytorze na tej stronie:

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
}

Pula workerów

Stała liczba goroutine czytających zadania z kanału utrzymuje ograniczoną współbieżność bez względu na liczbę zadań. WaitGroup mówi, kiedy wszyscy workerzy skończyli, czyli kiedy można zamknąć kanał wyników.

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))
}

Kolejność tych trzech elementów ma znaczenie:

main musi odbierać wyniki, gdy workerzy działają. Gdyby main wywołał wg.Wait() bezpośrednio przed czytaniem, workerzy zablokowaliby się na wysyłaniu do results, nigdy nie doszliby do Done i wszystko skończyłoby się zakleszczeniem. Dlatego Wait działa we własnej goroutine.
close(results) następuje dopiero po Wait, więc żaden worker nie może wysłać do zamkniętego kanału.
Podawanie zadań też odbywa się w goroutine, więc podawanie i zbieranie się nakładają.

To, który worker obsłużył które zadanie, zmienia się przy każdym uruchomieniu, więc program przed wypisaniem sortuje po zadaniu. Wszystko, co wypisuje, jest deterministyczne.

WaitGroup, kanał czy errgroup

Potrzeba	Użyj
Czekanie na N goroutine, wyniki w indeksowanych miejscach	`sync.WaitGroup`
Czekanie na jedną goroutine	kanału `done` albo samego kanału wyników
Wyniki przesyłane strumieniowo, gdy się kończą	kanału zamykanego po `wg.Wait()`
Zatrzymanie wszystkiego przy pierwszym błędzie	`errgroup.WithContext`
Zatrzymanie wszystkiego po timeoucie lub anulowaniu przez wywołującego	`context.Context` plus WaitGroup lub errgroup

Go 1.25 dodaje wg.Go(func() { ... }), które robi za ciebie Add(1) i odroczone Done. Kod dla Go 1.24 i wcześniejszych, łącznie z edytorem na tej stronie, używa jawnej formy pokazanej powyżej.

Typowe błędy

wg.Add(1) wewnątrz goroutine. Wait może się zakończyć, zanim to się wykona.
Brak Done przy wcześniejszym powrocie. Zawsze defer wg.Done().
Przekazywanie WaitGroup przez wartość. Użyj wskaźnika; go vet zgłasza kopię.
Czekanie w tej samej goroutine, która musi opróżniać kanał. Przenieś wg.Wait() razem z close do osobnej goroutine.
Ponowne użycie WaitGroup, zanim poprzednie Wait się zakończyło. Nowy cykl wywołań Add zaczynaj dopiero po zakończeniu Wait.

Najczęściej zadawane pytania

Jak działa sync.WaitGroup w Go?

WaitGroup to licznik. wg.Add(n) go zwiększa, wg.Done() zmniejsza o jeden, a wg.Wait() blokuje, dopóki nie osiągnie zera. Wywołaj Add przed uruchomieniem każdej goroutine, defer wg.Done() wewnątrz niej, a Wait tam, gdzie wszystko musi być skończone.

Czy WaitGroup przekazywać przez wartość, czy przez wskaźnik?

Przez wskaźnik (*sync.WaitGroup) albo pozwól goroutine przechwycić go w domknięciu. Kopia ma własny licznik, więc Done na kopii nigdy nie dociera do oryginału, a Wait blokuje na zawsze. go vet zgłasza ten błąd jako "passes lock by value".

Co powoduje "sync: negative WaitGroup counter"?

Więcej wywołań Done niż Add. Zwykle goroutine wywołuje Done dwa razy (raz przez defer i raz jawnie) albo na jednej ze ścieżek pominięto Add(1). Program wywołuje panic, bo licznik nie może już powiedzieć niczego prawdziwego.

Jak odebrać błędy z goroutine uruchomionych z WaitGroup?

WaitGroup nie przenosi wyników ani błędów. Daj każdej goroutine własne miejsce w slice'ie błędów i połącz je po Wait (na przykład przez errors.Join) albo użyj golang.org/x/sync/errgroup, którego Wait zwraca pierwszy błąd i może anulować pozostałe przez kontekst.

Powiązane zagadnienia