completion

package
v1.14.0-snapshot.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 16, 2023 License: Apache-2.0 Imports: 3 Imported by: 26

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 generally 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

func NewWaitGroup(ctx context.Context) *WaitGroup

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) Context

func (wg *WaitGroup) Context() context.Context

Context returns the context of all the Completions in the wait group.

func (*WaitGroup) Wait

func (wg *WaitGroup) Wait() error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL