-
Notifications
You must be signed in to change notification settings - Fork 2.8k
/
doc.go
64 lines (63 loc) · 2.28 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
// SPDX-License-Identifier: Apache-2.0
// Copyright Authors of Cilium
// Package completion implements a variant of sync.WaitGroup that is associated
// with a context.Context.
//
// A WaitGroup is created by calling NewWaitGroup with the context:
//
// wg := completion.NewWaitGroup(ctx)
//
// For each concurrent computation to wait for, a Completion is created by
// calling AddCompletion and then passing it to the concurrent computation:
//
// comp1 := wg.AddCompletion()
// DoSomethingConcurrently(..., comp1)
// comp2 := wg.AddCompletion()
// DoSomethingElse(..., comp2)
//
// The Completion type provides the Complete and Completed() methods:
//
// func (c *Completion) Complete()
// func (c *Completion) Completed() <-chan struct{}
//
// The Complete method must be called when the concurrent computation is
// completed, for instance:
//
// func DoSomethingConcurrently(..., comp Completion) {
// ...
// go func() {
// ...
// // Computation is completed successfully.
// comp.Complete(nil)
// }()
// ...
// }
//
// Once all Completions are created, one can wait for the completion of all
// of the Completions by calling Wait:
//
// err := wg.Wait()
//
// Wait blocks until either all Completions are completed, or the context is
// canceled, times out, or any of the concurrent operations associated with
// the WaitGroup fails, whichever happens first. The returned error is
// nil if all the concurrent operations are successfully completed, a non-nil
// error otherwise.
//
// A Completion can also be created with a callback, which is called at most
// once when the Completion is completed before the context is canceled:
//
// comp := wg.AddCompletionWithCallback(func(err error) {
// if err == nil {
// fmt.Println("completed')
// }
// })
//
// The callback is called in the goroutine which calls Complete the first time.
// The callback is called with an non-nil error if the associated concurrent
// operation fails. Error values 'context.DeadlineExceeded' and
// 'context.Canceled' are passed if the WaitGroup's context times out or is
// canceled. Note that the context is canceled also if any of the other
// completions in the WaitGroup fails, and the non-failing completions will
// have their callbacks called with 'context.Canceled'.
package completion