WaitGroup di Golang: Add, Done, Wait, dan Worker Pool

Pola dasarnya

sync.WaitGroup menghitung goroutine yang sedang berjalan. Add menaikkan hitungannya, Done menurunkannya, Wait memblokir sampai hitungannya nol.

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

Tiga download itu berjalan bersamaan, jadi program butuh sekitar 10 ms, bukan 30. Hasilnya dicetak sesuai urutan input karena setiap goroutine hanya menulis ke indeksnya sendiri di sizes, dan main baru membacanya setelah Wait.

Zero value dari WaitGroup sudah siap dipakai. Tidak perlu constructor.

Tiga aturan

Panggil Add sebelum go, bukan di dalam goroutine. Kalau goroutine memanggil Add sendiri, main bisa sampai di Wait sebelum ada goroutine yang mulai, melihat hitungan nol, lalu return padahal pekerjaannya belum dimulai. Kalau kamu sudah tahu jumlahnya sejak awal, wg.Add(len(files)) sekali sebelum perulangan hasilnya sama.

Panggil Done dengan defer di baris pertama goroutine. Goroutine yang return lebih awal karena error, atau panic, tetap menurunkan penghitungnya. Done yang terlupa membuat Wait memblokir selamanya. Kalau itu satu-satunya goroutine yang tersisa, runtime melaporkan fatal error: all goroutines are asleep dengan sync.WaitGroup.Wait di trace-nya.

Jangan pernah menyalin WaitGroup setelah pertama kali dipakai. Kirim *sync.WaitGroup ke fungsi, atau tangkap variabelnya lewat closure seperti di atas.

Mengirim WaitGroup ke fungsi

Kalau badan goroutine berupa fungsi bernama, kirim pointer-nya:

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

Dengan wg sync.WaitGroup sebagai parameter nilai, setiap worker akan memanggil Done pada salinannya sendiri dan main akan memblokir di Wait selamanya. go vet menangkapnya sebelum kamu menjalankan apa pun:

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

Desain yang lebih rapi menjauhkan konkurensi dari worker sepenuhnya: biarkan ia menjadi fungsi biasa, dan lakukan pencatatan Add/Done di closure milik pemanggil. Dengan begitu worker mudah diuji dan dipanggil secara sinkron.

Penghitung negatif

Done sama dengan Add(-1). Kalau hitungannya turun di bawah nol, program akan 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
}

Output-nya adalah recovered: sync: negative WaitGroup counter. Penyebab yang biasa adalah goroutine dengan defer wg.Done() yang juga memanggil wg.Done() secara eksplisit di salah satu jalurnya.

Mengumpulkan error

WaitGroup hanya menghitung. Untuk error, beri setiap goroutine slotnya sendiri dan periksa setelah 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) melewati nilai nil dan mengembalikan nil jika semuanya nil, jadi fungsi ini menggabungkan "satu error per goroutine" tanpa pencatatan tambahan.

Kalau kamu ingin menghentikan pekerjaan yang tersisa begitu ada satu goroutine yang gagal, pakai golang.org/x/sync/errgroup. Ini adalah WaitGroup ditambah error pertama ditambah context yang dibatalkan saat terjadi kegagalan, dan g.SetLimit(n) membatasi konkurensinya. Package ini berada di luar pustaka standar, jadi tidak bisa dijalankan di editor halaman ini:

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
}

Worker pool

Sejumlah goroutine tetap yang membaca job dari sebuah channel menjaga konkurensi tetap terbatas, tidak peduli berapa banyak job-nya. WaitGroup memberi tahu kapan semua worker selesai, dan saat itulah channel hasil boleh ditutup.

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

Urutan ketiga bagian ini penting:

• main harus sedang menerima hasil selama worker berjalan. Kalau main langsung memanggil wg.Wait() sebelum membaca, worker akan terblokir saat mengirim ke results, tidak pernah sampai ke Done, dan semuanya mengalami deadlock. Itulah sebabnya Wait dijalankan di goroutine-nya sendiri.
• close(results) hanya terjadi setelah Wait, jadi tidak ada worker yang bisa mengirim ke channel yang sudah ditutup.
• Pengirim job juga berjalan di sebuah goroutine, jadi proses mengirim dan mengumpulkan berlangsung bersamaan.

Worker mana yang menangani job mana berubah di setiap run, jadi program mengurutkan berdasarkan job sebelum mencetak. Semua yang dicetaknya deterministik.

WaitGroup, channel, atau errgroup

Go 1.25 menambahkan wg.Go(func() { ... }), yang melakukan Add(1) dan Done yang di-defer untukmu. Kode untuk Go 1.24 dan sebelumnya, termasuk editor di halaman ini, memakai bentuk eksplisit seperti di atas.

Kesalahan umum

• wg.Add(1) di dalam goroutine. Wait bisa return sebelum baris itu dijalankan.
• Lupa Done saat return lebih awal. Selalu tulis defer wg.Done().
• Mengirim WaitGroup sebagai nilai. Pakai pointer; go vet menandai penyalinannya.
• Menunggu di goroutine yang sama yang harus mengosongkan channel. Pindahkan wg.Wait() beserta close ke goroutine terpisah.
• Memakai ulang WaitGroup sebelum Wait sebelumnya return. Mulai siklus panggilan Add yang baru hanya setelah Wait selesai.