実行できるGoドキュメント: WaitGroup

Q: Goのsync.WaitGroupはどういう仕組みですか？

WaitGroupはカウンタです。wg.Add(n) で増やし、wg.Done() で1つ減らし、wg.Wait() はゼロになるまでブロックします。各ゴルーチンを開始する前に Add を呼び、その中で defer wg.Done() とし、すべての終了が必要な場所で Wait を呼びます。

Q: WaitGroupは値で渡すべきですか、ポインタで渡すべきですか？

ポインタ（*sync.WaitGroup）で渡すか、ゴルーチンにクロージャで捕捉させます。コピーは独自のカウンタを持つので、コピーに対する Done は元に届かず、Wait は永遠にブロックします。go vet はこの間違いを「passes lock by value」として報告します。

Q: 「sync: negative WaitGroup counter」の原因は何ですか？

Add の呼び出しより Done の呼び出しが多いことです。たいていは、ゴルーチンが Done を2回呼んでいる（defer で1回と明示的に1回）か、ある経路で Add(1) が飛ばされています。カウンタがもう正しいことを示せないので、プログラムはpanicします。

Q: WaitGroupで開始したゴルーチンからエラーを受け取るには？

WaitGroupは結果もエラーも運びません。各ゴルーチンにエラーのスライスの専用の枠を与え、Wait の後でまとめる（たとえば errors.Join で）か、golang.org/x/sync/errgroup を使います。errgroupの Wait は最初のエラーを返し、コンテキストを通して他をキャンセルできます。

基本のパターン

sync.WaitGroup は動いているゴルーチンを数えます。Add で数を増やし、Done で減らし、Wait はゼロになるまでブロックします。

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

3つのダウンロードは並行に動くので、プログラムは30ミリ秒ではなく約10ミリ秒で終わります。各ゴルーチンは sizes の自分のインデックスにだけ書き込み、main は Wait の後でしか読まないので、結果は入力の順に表示されます。

WaitGroup のゼロ値はすぐに使えます。コンストラクタはありません。

3つのルール

Add はゴルーチンの中ではなく go の前に呼ぶ。 ゴルーチン自身が Add を呼ぶと、どのゴルーチンも始まる前に main が Wait に到達し、数がゼロに見えて、処理が始まってもいないのに戻ることがあります。数が事前にわかっているなら、ループの前に一度 wg.Add(len(files)) としても同じです。

Done はゴルーチンの最初の行で defer を付けて呼ぶ。 エラーで早めに戻ったりpanicしたりしたゴルーチンでも、カウンタは減ります。Done が欠けると Wait は永遠にブロックします。それが残った唯一のゴルーチンなら、ランタイムはトレースに sync.WaitGroup.Wait を含む fatal error: all goroutines are asleep を報告します。

最初に使った後のWaitGroupは決してコピーしない。 関数には *sync.WaitGroup を渡すか、上のように変数をクロージャで捕捉します。

WaitGroupを関数に渡す

ゴルーチンの本体が名前付きの関数なら、ポインタを渡します。

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

値の引数として wg sync.WaitGroup を受け取ると、各ワーカーは自分のコピーに対して Done を呼び、main は Wait で永遠にブロックします。go vet は何かを実行する前にそれを検出します。

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

よりすっきりした設計は、並行処理を worker からまったく切り離すことです。worker は普通の関数にし、Add/Done の管理は呼び出し側のクロージャで行います。そうすれば worker はテストしやすく、同期的にも呼べます。

負のカウンタ

Done は Add(-1) です。数がゼロを下回ると、プログラムは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
}

出力は recovered: sync: negative WaitGroup counter です。よくある原因は、defer wg.Done() を持つゴルーチンが、ある経路で明示的に wg.Done() も呼んでいることです。

エラーを集める

WaitGroup は数えるだけです。エラーについては、各ゴルーチンに専用の枠を与え、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）は nil の値を飛ばし、すべてが nil なら nil を返すので、余計な管理なしに「ゴルーチンごとに1つのエラー」をまとめられます。

1つのゴルーチンが失敗したらすぐに残りの処理を止めたいなら、代わりに golang.org/x/sync/errgroup を使います。これはWaitGroupに、最初のエラーと、失敗時にキャンセルされるコンテキストを加えたもので、g.SetLimit(n) で並行数も制限できます。標準ライブラリの外にあるので、このページのエディタでは実行できません。

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
}

ワーカープール

チャネルからジョブを読む固定数のゴルーチンを使えば、ジョブがいくつあっても並行数が制限されます。WaitGroupは、すべてのワーカーが終わったこと、つまり結果のチャネルを閉じてよいタイミングを教えてくれます。

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

3つの部品の順序が重要です。

ワーカーが動いている間、main は結果を受信していなければなりません。main が読む前に直接 wg.Wait() を呼ぶと、ワーカーは results への送信でブロックし、Done に到達せず、すべてがデッドロックします。Wait を専用のゴルーチンで実行しているのはこのためです。
close(results) は Wait の後でしか起きないので、どのワーカーも閉じたチャネルに送信することはありません。
ジョブを供給する側もゴルーチンで動くので、供給と収集が重なり合います。

どのワーカーがどのジョブを扱ったかは実行のたびに変わるので、プログラムは表示する前にジョブでソートしています。表示されるものはすべて決定的です。

WaitGroup、チャネル、errgroupの使い分け

必要なこと	使うもの
N個のゴルーチンを待ち、結果をインデックス付きの枠に入れる	`sync.WaitGroup`
1つのゴルーチンを待つ	`done` チャネルか結果のチャネルそのもの
終わった順に結果を流す	`wg.Wait()` の後に閉じるチャネル
最初のエラーですべてを止める	`errgroup.WithContext`
タイムアウトや呼び出し側のキャンセルですべてを止める	`context.Context` とWaitGroupまたはerrgroup

Go 1.25では、Add(1) とdeferした Done を代わりにやってくれる wg.Go(func() { ... }) が追加されます。このページのエディタを含め、Go 1.24以前向けのコードでは上に示した明示的な形を使います。

よくある間違い

ゴルーチンの中で wg.Add(1) する。 それが実行される前に Wait が戻ることがあります。
早期リターンで Done を忘れる。 常に defer wg.Done() とします。
WaitGroupを値で渡す。 ポインタを使います。go vet がコピーを指摘します。
チャネルを空にしなければならないのと同じゴルーチンで待つ。 wg.Wait() と close を別のゴルーチンに移します。
前の Wait が戻る前にWaitGroupを再利用する。 新しい Add の周期は、Wait が終わってから始めます。

よくある質問

Goのsync.WaitGroupはどういう仕組みですか？

WaitGroupはカウンタです。wg.Add(n) で増やし、wg.Done() で1つ減らし、wg.Wait() はゼロになるまでブロックします。各ゴルーチンを開始する前に Add を呼び、その中で defer wg.Done() とし、すべての終了が必要な場所で Wait を呼びます。

WaitGroupは値で渡すべきですか、ポインタで渡すべきですか？

ポインタ（*sync.WaitGroup）で渡すか、ゴルーチンにクロージャで捕捉させます。コピーは独自のカウンタを持つので、コピーに対する Done は元に届かず、Wait は永遠にブロックします。go vet はこの間違いを「passes lock by value」として報告します。

「sync: negative WaitGroup counter」の原因は何ですか？

Add の呼び出しより Done の呼び出しが多いことです。たいていは、ゴルーチンが Done を2回呼んでいる（defer で1回と明示的に1回）か、ある経路で Add(1) が飛ばされています。カウンタがもう正しいことを示せないので、プログラムはpanicします。

WaitGroupで開始したゴルーチンからエラーを受け取るには？

WaitGroupは結果もエラーも運びません。各ゴルーチンにエラーのスライスの専用の枠を与え、Wait の後でまとめる（たとえば errors.Join で）か、golang.org/x/sync/errgroup を使います。errgroupの Wait は最初のエラーを返し、コンテキストを通して他をキャンセルできます。