WaitGroup في Golang: Add وDone وWait ومجموعة عمّال

النمط الأساسي

تعدّ sync.WaitGroup الـ goroutines العاملة. ترفع 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])
	}
}

تعمل التنزيلات الثلاثة بالتزامن، فيستغرق البرنامج نحو 10 ms بدل 30. تُطبع النتائج بترتيب المدخلات لأن كل goroutine تكتب فقط في فهرسها من sizes، ولا تقرؤها main إلا بعد Wait.

القيمة الصفرية لـ WaitGroup جاهزة للاستخدام. لا حاجة لدالة بناء.

القواعد الثلاث

استدعِ Add قبل go، لا داخل الـ goroutine. إذا استدعت الـ goroutine الدالة Add بنفسها، قد تصل main إلى Wait قبل أن تبدأ أي goroutine، فترى عددًا صفريًا وتعود بينما لم يبدأ العمل. عندما تعرف العدد مسبقًا، فإن wg.Add(len(files)) مرة واحدة قبل الحلقة مكافئة.

استدعِ Done مع defer في أول سطر من الـ goroutine. الـ goroutine التي تعود مبكرًا بسبب خطأ، أو تسبّب panic، تُنقص العدّاد مع ذلك. غياب Done يترك Wait متوقّفة إلى الأبد. وإذا كانت آخر goroutine متبقّية، يبلغ وقت التشغيل عن fatal error: all goroutines are asleep مع sync.WaitGroup.Wait في الأثر.

لا تنسخ WaitGroup بعد أول استخدام أبدًا. مرّر *sync.WaitGroup إلى الدوال، أو التقط المتغيّر في إغلاق كما سبق.

تمرير WaitGroup إلى دالة

عندما يكون جسم الـ goroutine دالة مسمّاة، مرّر مؤشرًا:

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 كليًا: دعها دالة عادية وأجرِ حسابات 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. السبب المعتاد goroutine فيها defer wg.Done() تستدعي أيضًا wg.Done() صراحة في أحد المسارات.

جمع الأخطاء

لا تفعل WaitGroup إلا العدّ. للأخطاء أعطِ كل goroutine خانتها الخاصة وافحصها بعد 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، فتجمع "خطأ لكل goroutine" دون أي حسابات إضافية.

إذا أردت إيقاف العمل المتبقّي حالما تفشل goroutine واحدة، فاستخدم 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
}

مجموعة عمّال

عدد ثابت من الـ goroutines يقرأ المهام من قناة يُبقي التزامن محدودًا مهما كان عدد المهام. تخبرك الـ 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))
}

ترتيب القطع الثلاث مهم:

• يجب أن تستقبل main النتائج أثناء عمل العمّال. لو استدعت main الدالة wg.Wait() مباشرة قبل القراءة، لتوقّف العمّال عند الإرسال إلى results، ولما وصلوا أبدًا إلى Done، ولحدث جمود في كل شيء. لهذا تعمل Wait في goroutine خاصة بها.
• لا يحدث close(results) إلا بعد Wait، فلا يستطيع أي عامل الإرسال على قناة مغلقة.
• يعمل مغذّي المهام أيضًا في goroutine، فيتداخل التغذية والجمع.

أي عامل عالج أي مهمة يتغيّر من تشغيل إلى آخر، لذا يرتّب البرنامج حسب المهمة قبل الطباعة. وكل ما يطبعه حتمي.

WaitGroup أم قناة أم errgroup

تضيف Go 1.25 الدالة wg.Go(func() { ... })، التي تجري Add(1) وDone المؤجّلة نيابة عنك. أما الشيفرة لـ Go 1.24 وما قبله، ومنها محرّر هذه الصفحة، فتستخدم الشكل الصريح المعروض سابقًا.

أخطاء شائعة

• wg.Add(1) داخل الـ goroutine. قد تعود Wait قبل تنفيذها.
• نسيان Done عند عودة مبكرة. استخدم دائمًا defer wg.Done().
• تمرير الـ WaitGroup بالقيمة. استخدم مؤشرًا؛ ويبلغ go vet عن النسخ.
• الانتظار في الـ goroutine نفسها التي يجب أن تفرّغ قناة. انقل wg.Wait() مع close إلى goroutine منفصلة.
• إعادة استخدام WaitGroup قبل عودة Wait السابقة. ابدأ دورة جديدة من استدعاءات Add فقط بعد انتهاء Wait.