Documentation
¶
Overview ¶
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'.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Completion ¶
type Completion struct {
// contains filtered or unexported fields
}
Completion provides the Complete callback to be called when an asynchronous computation is completed.
func NewCompletion ¶
func NewCompletion(cancel context.CancelFunc, callback func(err error)) *Completion
NewCompletion creates a Completion which calls a function upon Complete(). 'cancel' is called if the associated operation fails for any reason.
func (*Completion) Complete ¶
func (c *Completion) Complete(err error) error
Complete notifies of the completion of the asynchronous computation. Idempotent. If the operation completed successfully 'err' is passed as nil. Returns the error state the completion completed with, which is gnerally different from 'err' if already completed.
func (*Completion) Completed ¶
func (c *Completion) Completed() <-chan struct{}
Completed returns a channel that's closed when the completion is completed, i.e. when Complete is called the first time, or when the call to the parent WaitGroup's Wait terminated because the context was canceled.
func (*Completion) Err ¶
func (c *Completion) Err() error
Err returns a non-nil error if the completion ended in error
type WaitGroup ¶
type WaitGroup struct {
// contains filtered or unexported fields
}
WaitGroup waits for a collection of Completions to complete.
func NewWaitGroup ¶
NewWaitGroup returns a new WaitGroup using the given context.
func (*WaitGroup) AddCompletion ¶
func (wg *WaitGroup) AddCompletion() *Completion
AddCompletion creates a new completion, adds it into the wait group, and returns it.
func (*WaitGroup) AddCompletionWithCallback ¶
func (wg *WaitGroup) AddCompletionWithCallback(callback func(err error)) *Completion
AddCompletionWithCallback creates a new completion, adds it to the wait group, and returns it. The callback will be called upon completion. Completion can complete in a failure (err != nil)
func (*WaitGroup) Wait ¶
Wait blocks until all completions added by calling AddCompletion are completed, or the context is canceled, whichever happens first. Returns the context's error if it is cancelled, nil otherwise. No callbacks of the completions in this wait group will be called after this returns. Returns the error value of one of the completions, if available, or the error value of the Context otherwise.
Source Files