sync.WaitGroup, recoudre les goroutines sync.WaitGroup, stitching goroutines back

Lancer N goroutines est facile ; savoir qu'elles ont toutes fini l'est moins. Le WaitGroup compte, attend, et te rend la main — à condition de l'incrémenter au bon endroit. Le piège classique : Add dans la boucle, et une variable capturée par référence. Launching N goroutines is easy; knowing they've all finished, less so. The WaitGroup counts, waits, and hands control back — provided you increment it in the right place. The classic trap: Add inside the loop, and a variable captured by reference.

Audience
Dev qui sait lancer un go et veut en attendre N sans rien perdre Dev who can launch a go and wants to wait on N without losing a thing
ChapitresChapters
5
LectureReading
≈ 16 min
NiveauLevel
●○○○
Date
Juil 2026 Jul 2026

WaitGroupSynchronisation

SommaireContents ·
№ 01CadrageFraming3 min

Un go, on savait le rejoindre. Mais mille ?One go, we knew how to rejoin. But a thousand?

Au numéro précédent, on a appris à attendre une goroutine : un Wait, un <-done, et le fil est rejoint. Mais le vrai code n'en lance presque jamais une seule — il en sème une par URL, par ligne, par job. Lire N signaux à la main, c'est promettre de compter juste : un de trop, on bloque ; un de moins, on file trop tôt. Il faut un objet qui tienne le compte à notre place.Last issue we learned to wait for a goroutine: a Wait, a <-done, and the thread is rejoined. But real code almost never launches just one — it scatters one per URL, per row, per job. Reading N signals by hand means promising to count right: one too many, you block; one too few, you leave early. You need an object that keeps the count for you.

Le code qui lance N et n'en attend aucuneThe code that launches N and waits for none
func main() {
    for _, u := range urls {
        go fetch(u)   // on en lance N… et puis ?
    }
}                     // main file vers sa fin : aucune des N n'est attendue
Le compteur, en trois tempsThe counter, in three beats
wg.Add(3)
3
avant de lancerbefore launching
⟶
Done × 3Done × 3
wg.Done()
1
chacune en sortanteach on exit
⟶
dernier Donelast Done
wg.Wait()
0
débloque mainunblocks main

Un sync.WaitGroup n'est qu'un compteur partagé : on l'incrémente avant de lancer, chaque goroutine le décrémente en finissant, et Wait dort jusqu'au retour à zéro. Pas de temps, pas de devinette — de la comptabilité.A sync.WaitGroup is just a shared counter: you bump it before launching, each goroutine drops it on finishing, and Wait sleeps until it returns to zero. No time, no guessing — bookkeeping.

Le réflexe du numéroThe issue's reflex

« Add avant le go, Done en defer, Wait une fois. » Trois gestes, un ordre. Tout le reste de ce numéro est ce qui arrive quand on les met dans le mauvais ordre — ou quand la variable de boucle s'invite dans la goroutine."Add before the go, Done in a defer, Wait once." Three moves, one order. The rest of this issue is what happens when you get the order wrong — or when the loop variable sneaks into the goroutine.

Compter, ce n'est pas communiquer.Counting isn't communicating.

Le WaitGroup ne transporte aucune donnée : il ne dit pas ce que chaque goroutine a produit, seulement qu'elles ont toutes fini. Pour récupérer des résultats, il faudra un channel (Vol. 2). Ici, on répond à une seule question — « sont-elles toutes rentrées ? » — et on y répond sans jamais partager autre chose qu'un entier protégé.The WaitGroup carries no data: it doesn't say what each goroutine produced, only that they all finished. To collect results you'll need a channel (Vol. 2). Here we answer one question — 'are they all back?' — and answer it without ever sharing more than one guarded integer.

№ 02Les trois gestesThe three moves5 min

Add, Done, Wait. Trois appels — et un ordre qui ne se négocie pas.Add, Done, Wait. Three calls — and an order that's non-negotiable.

On pourrait compter les fins à la main, un signal par goroutine, et lire N fois. Ça marche — tant qu'on ne se trompe pas de N. Le jour où la boucle change, ou qu'une goroutine sort sans signaler, le compte est faux et le programme se fige. Le WaitGroup remplace ce comptage manuel par trois appels dont la machine garantit la cohérence.You could count the endings by hand, one signal per goroutine, and read N times. It works — as long as you never get N wrong. The day the loop changes, or a goroutine exits without signalling, the count is off and the program freezes. The WaitGroup replaces that manual tally with three calls whose consistency the machine guarantees.

Compter les signaux soi-même — fragile au moindre NCounting signals yourself — fragile to any N
done := make(chan struct{})
for i := 0; i < 3; i++ {
    go func() {
        work()
        done <- struct{}{}   // « moi, j'ai fini »
    }()
}
for i := 0; i < 3; i++ {
    <-done                   // il FAUT lire exactement 3 fois
}                            // 2 : on bloque. 4 : on bloque encore.

Le 3 est écrit deux fois : à l'envoi et à la lecture. Rien ne lie les deux — c'est à toi de les garder synchrones. Ajoute une goroutine en oubliant la seconde boucle, et main reste bloqué sur un <-done qui ne viendra jamais. Le bon compte n'est garanti par personne.The 3 is written twice: at send and at read. Nothing links them — it's on you to keep them in sync. Add a goroutine and forget the second loop, and main stays stuck on a <-done that never comes. Nobody guarantees the count is right.

Pourquoi Done en deferWhy Done in a defer

Une goroutine peut sortir par dix chemins : un return anticipé, une error, un panic récupéré plus haut. Mettre wg.Done() en defer, c'est promettre le décrément sur tous ces chemins. Le poser à la dernière ligne, c'est l'oublier au premier return — et bloquer Wait pour toujours.A goroutine can exit by ten paths: an early return, an error, a panic recovered higher up. Putting wg.Done() in a defer promises the decrement on all of them. Put it on the last line, and you miss it on the first return — freezing Wait forever.

Go 1.25 : wg.Go()Go 1.25: wg.Go()

Depuis Go 1.25, wg.Go(func(){ work() }) fait les trois gestes d'un coup : Add(1), lance la goroutine, et Done() en defer à sa place. Le footgun du « Add au mauvais endroit » disparaît par construction. À utiliser dès que possible — mais il faut d'abord savoir ce que la méthode automatise, sinon on déplace le mystère sans le dissoudre.Since Go 1.25, wg.Go(func(){ work() }) does all three moves at once: Add(1), launches the goroutine, and defers Done() for you. The 'Add in the wrong place' footgun is gone by construction. Reach for it whenever you can — but only once you know what it automates, or you've moved the mystery instead of dissolving it.

Le channel demande « combien ? » et te laisse répondre. Le WaitGroup range la question dans le compteur, pour que tu n'aies plus à la poser.The channel asks "how many?" and leaves you to answer. The WaitGroup files the question inside the counter, so you never ask it again.
№ 03Le piège de la boucleThe loop trap5 min

Dix goroutines, une seule variable. Laquelle liront-elles ?Ten goroutines, one variable. Which one will they read?

Le WaitGroup compte juste : les trois goroutines partent, les trois reviennent. Et pourtant elles traitent toutes la même URL. Le bug n'est pas dans la synchronisation — il est dans ce que la closure capture. Pendant douze ans, c'est le piège qui a fait le plus saigner les débutants comme les seniors en Go.The WaitGroup counts right: three goroutines launch, three return. And yet they all process the same URL. The bug isn't in the synchronization — it's in what the closure captures. For twelve years this was the trap that bled beginners and seniors alike in Go.

La closure capture la variable, pas sa valeurThe closure captures the variable, not its value
urls := []string{"a", "b", "c"}
for _, u := range urls {
    wg.Add(1)
    go func() {
        defer wg.Done()
        fetch(u)        // u : UNE seule variable, partagée par les 3
    }()
}
wg.Wait()
// avant Go 1.22 : souvent "c", "c", "c" — la boucle a fini la première

Jusqu'à Go 1.21, u est une case mémoire réutilisée à chaque tour. La closure ne capture pas la valeur du moment : elle capture la variable. Quand les goroutines s'exécutent enfin, la boucle a souvent déjà fini — u vaut "c" pour tout le monde. Le compteur est juste, le résultat est faux.Through Go 1.21, u is one memory slot reused each iteration. The closure doesn't capture the value at that moment: it captures the variable. By the time the goroutines actually run, the loop has often finished — u is "c" for everyone. The count is right, the result is wrong.

Ce que Go 1.22 a changéWhat Go 1.22 changed

Depuis Go 1.22 (février 2024), la variable de boucle est re-déclarée à chaque itération : le code « buggé » produit désormais "a", "b", "c". Le piège est éteint pour le code neuf — mais il vit encore dans tout dépôt compilé avec un go.mod antérieur à go 1.22, car le comportement suit la version déclarée du module. Connais le piège avant de faire confiance au correctif : le passer en argument reste sans ambiguïté, quelle que soit la version.Since Go 1.22 (Feb 2024), the loop variable is re-declared each iteration: the "buggy" code now yields "a", "b", "c". The trap is off for new code — but it still lives in any repo built with a go.mod older than go 1.22, since the behaviour follows the module's declared version. Know the trap before you trust the fix: passing it as an argument stays unambiguous on any version.

Une closure capture où vit la variable, pas ce qu'elle vaut. Dans une goroutine, ce « où » est partagé — et le temps décide de la valeur.A closure captures where the variable lives, not what it holds. In a goroutine, that "where" is shared — and timing decides the value.
№ 04Où placer le AddWhere to put Add4 min

Une ligne de déplacée, et Wait n'attend plus rien.One line out of place, and Wait waits for nothing.

Le geste a l'air anodin : Add(1) avant le go, ou Add(1) dans la goroutine ? Une ligne plus bas, et tout bascule. Car Wait ne lit pas l'intention — il lit le compteur, à l'instant où on l'appelle. Si l'Add n'a pas encore eu lieu, Wait voit zéro et file. Le programme ne plante pas : il rend juste la main trop tôt, en silence.The move looks harmless: Add(1) before the go, or Add(1) inside the goroutine? One line down, and everything tips. Because Wait doesn't read intent — it reads the counter, at the instant you call it. If the Add hasn't happened yet, Wait sees zero and leaves. The program doesn't crash: it just hands control back too early, silently.

Le compteur monte après la course de WaitThe counter rises after Wait's race
var wg sync.WaitGroup
for i := 0; i < 3; i++ {
    go func() {
        wg.Add(1)          // TROP TARD : Wait a pu passer avant ce Add
        defer wg.Done()
        work()
    }()
}
wg.Wait()                  // peut rendre la main alors que rien n'a démarré

Entre le go et le premier Add(1) à l'intérieur, il y a une fenêtre. Si main atteint Wait() pendant cette fenêtre, le compteur vaut encore 0 : Wait ne bloque pas, et work tourne dans le vide après la fin du programme. C'est une data race sur le compteur lui-même — go run -race la signale.Between the go and the first Add(1) inside, there's a window. If main reaches Wait() during it, the counter is still 0: Wait doesn't block, and work runs into the void after the program ends. It's a data race on the counter itself — go run -race flags it.

Deux autres façons de se brûlerTwo more ways to get burned

Un Done() de trop fait passer le compteur sous zéro : panic: sync: negative WaitGroup counter, immédiat et fatal. Et un WaitGroup se passe toujours par pointeur (*sync.WaitGroup) : le copier — en le passant par valeur à une fonction — duplique le compteur, et chaque moitié attend le mauvais.One Done() too many drops the counter below zero: panic: sync: negative WaitGroup counter, immediate and fatal. And a WaitGroup is always passed by pointer (*sync.WaitGroup): copying it — by passing it by value to a function — duplicates the counter, and each half waits on the wrong one.

go vet veille.go vet is watching.

Le copier-coller d'un WaitGroup est l'une des rares fautes que l'outillage attrape : go vet (via le check copylocks) refuse de laisser passer un sync.WaitGroup copié, parce qu'il embarque un marqueur noCopy qui signale « ne pas copier ». C'est la couche que Go t'offre gratuitement — mais le placement du Add, lui, reste entièrement sur tes épaules. Le compilateur fait confiance ; vet rappelle ; toi, tu tiens l'invariant.Copy-pasting a WaitGroup is one of the few mistakes tooling catches: go vet (via the copylocks check) refuses a copied sync.WaitGroup, because it embeds a noCopy marker that says “do not copy”. That's the layer Go gives you for free — but Add placement stays entirely on your shoulders. The compiler trusts; vet reminds; you hold the invariant.

Wait ne te croit pas sur parole. Il ne compte que les Add déjà arrivés — alors arrive avant lui.Wait won't take your word for it. It counts only the Adds already in — so get there before it does.
№ 05Bilan & éditoWrap-up & editorial2 min

Trois lignes triviales. Quatre façons de les écrire faux.Three trivial lines. Four ways to get them wrong.

Le WaitGroup tient en un compteur et trois appels — c'est ce qui le rend dangereux. Sa simplicité cache une discipline : où placer le Add, comment garantir le Done, ce que la closure capture, et qu'on ne le copie jamais. Le réflexe à emporter n'est pas « connais l'API » mais « sache, pour chaque go de ta boucle, quel Add l'a précédé et quel Done le suivra ».The WaitGroup fits in one counter and three calls — which is what makes it dangerous. Its simplicity hides a discipline: where to put Add, how to guarantee Done, what the closure captures, and never to copy it. The reflex to keep isn't 'know the API' but 'know, for every go in your loop, which Add preceded it and which Done will follow'.

Le gesteThe moveLa règleThe ruleSi tu la ratesIf you miss it
Add(n)Avant le go, depuis la goroutine qui fera le Wait.Before the go, from the goroutine that will Wait.Dans la goroutine : data race, Wait file à zéro avant tout démarrage.Inside the goroutine: data race, Wait leaves at zero before anything starts.
defer Done()Première ligne de la goroutine, en defer.First line of the goroutine, in a defer.Posé en dur en fin de corps : sauté au premier return ou panic, Wait bloque à jamais.Hard-placed at the end: skipped on the first return or panic, Wait blocks forever.
Variable de boucleLoop variablePasse-la en argument : go func(u string){…}(u) (ou Go ≥ 1.22).Pass it as an argument: go func(u string){…}(u) (or Go ≥ 1.22).Capturée : avant Go 1.22, les N goroutines voient la dernière valeur.Captured: before Go 1.22, all N goroutines see the last value.
Le passagePassing itToujours par pointeur — *sync.WaitGroup.Always by pointer — *sync.WaitGroup.Copié par valeur : deux compteurs, chaque moitié attend le mauvais (go vet le voit).Copied by value: two counters, each half waits on the wrong one (go vet catches it).
Le WaitGroup ne sait pas ce que tes goroutines ont fait — seulement qu'elles ont fini. Pour le « quoi », il faudra communiquer.The WaitGroup doesn't know what your goroutines did — only that they finished. For the "what", you'll have to communicate.
Mot de l'éditeurFrom the editor

La discipline tient dans l'ordre, pas dans l'API.The discipline lives in the order, not the API.

On présente sync.WaitGroup comme l'outil « facile » de la synchronisation : trois méthodes, aucune valeur de retour à gérer. Et c'est vrai — jusqu'à ce qu'on déplace un Add d'une ligne, qu'on oublie un defer sur un chemin d'erreur, ou qu'on capture une variable de boucle. Aucun de ces bugs n'est dans l'API ; tous sont dans l'ordre et le lieu des trois gestes. C'est exactement la promesse du volume : Go te donne un mécanisme simple et te confie l'invariant qu'il ne vérifie pas. Le compteur est trivial ; le savoir où le bouger ne l'est pas.sync.WaitGroup is sold as the 'easy' synchronization tool: three methods, no return value to juggle. And it's true — until you move an Add by one line, miss a defer on an error path, or capture a loop variable. None of these bugs is in the API; all are in the order and the place of the three moves. That's the volume's promise exactly: Go hands you a simple mechanism and entrusts you with the invariant it won't check. The counter is trivial; knowing where to move it is not.

Prochain numéro : la goroutine qui fuit. Celle qui ne plante pas, ne s'imprime nulle part, et ne décrémente jamais son WaitGroup — parce qu'elle est bloquée pour toujours sur un envoi que plus personne ne lira. La fuite la plus silencieuse de Go : on va la rendre visible, la mesurer, et la fermer.Next issue: the goroutine that leaks. The one that doesn't crash, shows up in no log, and never decrements its WaitGroup — because it's blocked forever on a send no one will ever read. Go's quietest leak: we'll make it visible, measure it, and shut it down.