github.com/fafucoder/cilium@v1.6.11/pkg/completion/doc.go (about)

     1  // Copyright 2018 Authors of Cilium
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package completion implements a variant of sync.WaitGroup that is associated
    16  // with a context.Context.
    17  //
    18  // A WaitGroup is created by calling NewWaitGroup with the context:
    19  //
    20  //    wg := completion.NewWaitGroup(ctx)
    21  //
    22  // For each concurrent computation to wait for, a Completion is created by
    23  // calling AddCompletion and then passing it to the concurrent computation:
    24  //
    25  //    comp1 := wg.AddCompletion()
    26  //    DoSomethingConcurrently(..., comp1)
    27  //    comp2 := wg.AddCompletion()
    28  //    DoSomethingElse(..., comp2)
    29  //
    30  // The Completion type provides the Complete and Completed() methods:
    31  //
    32  //    func (c *Completion) Complete()
    33  //    func (c *Completion) Completed() <-chan struct{}
    34  //
    35  // The Complete method must be called when the concurrent computation is
    36  // completed, for instance:
    37  //
    38  //    func DoSomethingConcurrently(..., comp Completion) {
    39  //        ...
    40  //        go func() {
    41  //            ...
    42  //            // Computation is completed successfully.
    43  //            comp.Complete(nil)
    44  //        }()
    45  //        ...
    46  //    }
    47  //
    48  // Once all Completions are created, one can wait for the completion of all
    49  // of the Completions by calling Wait:
    50  //
    51  //    err := wg.Wait()
    52  //
    53  // Wait blocks until either all Completions are completed, or the context is
    54  // canceled, times out, or any of the concurrent operations associated with
    55  // the WaitGroup fails, whichever happens first. The returned error is
    56  // nil if all the concurrent operations are successfully completed, a non-nil
    57  // error otherwise.
    58  //
    59  // A Completion can also be created with a callback, which is called at most
    60  // once when the Completion is completed before the context is canceled:
    61  //
    62  //    comp := wg.AddCompletionWithCallback(func(err error) {
    63  //        if err == nil {
    64  //            fmt.Println("completed')
    65  //        }
    66  //    })
    67  //
    68  // The callback is called in the goroutine which calls Complete the first time.
    69  // The callback is called with an non-nil error if the associated concurrent
    70  // operation fails. Error values 'context.DeadlineExceeded' and
    71  // 'context.Canceled' are passed if the WaitGroup's context times out or is
    72  // canceled. Note that the context is canceled also if any of the other
    73  // completions in the WaitGroup fails, and the non-failing completions will
    74  // have their callbacks called with 'context.Canceled'.
    75  package completion