Go WaitGroup: Difference between revisions
(Created page with " * <tt>[https://golang.org/pkg/sync/#WaitGroup sync.WaitGroup]</tt> A <tt>WaitGroup</tt> is a counting semaphore that waits for a collection of goroutines to finish. The mai...") |
|||
| (27 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
=External= | |||
* https://pkg.go.dev/sync#WaitGroup | |||
=Internal= | |||
* [[Go_Package_sync#WaitGroup|The <tt>sync</tt> package]] | |||
* [[Go_Language_Goroutines#WaitGroup|Goroutines]] | |||
* [[Go Blocking the Main Thread until Ctrl-C is Entered|Blocking the Main Thread until Ctrl-C is Entered]] | |||
=Overview= | |||
A <code>WaitGroup</code> is a [[Concurrent_(Parallel)_Programming#Counting_Semaphore|counting semaphore]] that waits for a set of goroutines to finish, a thread-safe counter. The <code>WaitGroup#Wait()</code> invocation creates a [[Go_Language_Goroutines#Join_Point|join point]] in the program. The primitive does not help with collecting the results of the concurrent operations, it just provides execution synchronization. If results need to be collected, use a channel and a <code>select</code> statement instead. | |||
<span id='Wait'></span>The main goroutine calls <code>Add()</code> to set the number of goroutines to wait for, by incrementing the counting semaphore. Note that the call to <code>Add()</code> must be done before the goroutines tracked by the semaphore are started. Doing otherwise will create a race condition, when one or more of them calls <code>Done()</code> before they're accounted for, leading to "sync: negative WaitGroup counter". It is customary to couple calls to <code>Add()</code> as closely as possible to the goroutines they're helping to track. | |||
< | After calling <code>Add()</code> the main goroutine blocks on <code>Wait()</code>, or it can do some work and then block on <code>Wait()</code> until all other goroutines have finished. When each of the counted goroutines runs, they should call <code>Done()</code> when finished, to decrement the counting semaphore. | ||
</ | <syntaxhighlight lang='go'> | ||
import "sync" | |||
func aFunction(wg *sync.WaitGroup, s string) { | |||
defer wg.Done() | |||
fmt.Println(s) | |||
} | |||
... | |||
wg := sync.WaitGroup{} | |||
wg.Add(2) | |||
go aFunction(&wg, "A") | |||
go aFunction(&wg, "B") | |||
wg.Wait() | |||
fmt.Println("main is done") | |||
</syntaxhighlight> | |||
Result: | |||
<font size=-1> | |||
B | |||
A | |||
main is done | |||
</font> | |||
Note that the <code>WaitGroup</code> instance must be passed to the functions executed on the counted goroutines '''by pointer''', not value, because otherwise a copy of the <code> sync.WaitGroup</code> struct will be made on the secondary goroutine's stack, as [[Go Functions#Pass_by_Value|all arguments are passed by value]], and the <code>Done()</code> will have no effect on the original struct instance. | |||
The same semantics, when just one single goroutine is involved, can be achieved by using an unbuffered channel and discarding the read result: {{Internal|Go_Channels#Wait|Unbuffered Channels and Wait Semantics}} | |||
Latest revision as of 19:22, 17 January 2024
External
Internal
Overview
A WaitGroup is a counting semaphore that waits for a set of goroutines to finish, a thread-safe counter. The WaitGroup#Wait() invocation creates a join point in the program. The primitive does not help with collecting the results of the concurrent operations, it just provides execution synchronization. If results need to be collected, use a channel and a select statement instead.
The main goroutine calls Add() to set the number of goroutines to wait for, by incrementing the counting semaphore. Note that the call to Add() must be done before the goroutines tracked by the semaphore are started. Doing otherwise will create a race condition, when one or more of them calls Done() before they're accounted for, leading to "sync: negative WaitGroup counter". It is customary to couple calls to Add() as closely as possible to the goroutines they're helping to track.
After calling Add() the main goroutine blocks on Wait(), or it can do some work and then block on Wait() until all other goroutines have finished. When each of the counted goroutines runs, they should call Done() when finished, to decrement the counting semaphore.
import "sync"
func aFunction(wg *sync.WaitGroup, s string) {
defer wg.Done()
fmt.Println(s)
}
...
wg := sync.WaitGroup{}
wg.Add(2)
go aFunction(&wg, "A")
go aFunction(&wg, "B")
wg.Wait()
fmt.Println("main is done")
Result:
B A main is done
Note that the WaitGroup instance must be passed to the functions executed on the counted goroutines by pointer, not value, because otherwise a copy of the sync.WaitGroup struct will be made on the secondary goroutine's stack, as all arguments are passed by value, and the Done() will have no effect on the original struct instance.
The same semantics, when just one single goroutine is involved, can be achieved by using an unbuffered channel and discarding the read result: