wait

package
v0.31.3 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2024 License: Apache-2.0 Imports: 8 Imported by: 22,241

Documentation

Overview

Package wait provides tools for polling or listening for changes to a condition.

Index

Constants

This section is empty.

Variables

View Source 
var ErrWaitTimeout = ErrorInterrupted(errors.New("timed out waiting for the condition"))

ErrWaitTimeout is returned when the condition was not satisfied in time.

Deprecated: This type will be made private in favor of Interrupted() for checking errors or ErrorInterrupted(err) for returning a wrapped error.

View Source 
var ForeverTestTimeout = time.Second * 30

For any test of the style: 

...
<- time.After(timeout):
   t.Errorf("Timed out")

The value for timeout should effectively be "forever." Obviously we don't want our tests to truly lock up forever, but 30s is long enough that it is effectively forever for the things that can slow down a run on a heavily contended machine (GC, seeks, etc), but not so long as to make a developer ctrl-c a test run if they do happen to break that test.

View Source 
var NeverStop <-chan struct{} = make(chan struct{})

NeverStop may be passed to Until to make it never stop.

View Source 
var (
	// RealTimer can be passed to methods that need a clock.Timer.
	RealTimer = clock.RealClock{}.NewTimer
)

Functions

func BackoffUntil added in v0.18.0 

func BackoffUntil(f func(), backoff BackoffManager, sliding bool, stopCh <-chan struct{})

BackoffUntil loops until stop channel is closed, run f every duration given by BackoffManager.

If sliding is true, the period is computed after f runs. If it is false then period includes the runtime for f.

func ContextForChannel added in v0.25.0 

func ContextForChannel(parentCh <-chan struct{}) context.Context

ContextForChannel provides a context that will be treated as cancelled when the provided parentCh is closed. The implementation returns context.Canceled for Err() if and only if the parentCh is closed.

func ErrorInterrupted added in v0.27.0 

func ErrorInterrupted(cause error) error

ErrorInterrupted returns an error that indicates the wait was ended early for a given reason. If no cause is provided a generic error will be used but callers are encouraged to provide a real cause for clarity in debugging.

func ExponentialBackoff 

func ExponentialBackoff(backoff Backoff, condition ConditionFunc) error

ExponentialBackoff repeats a condition check with exponential backoff.

It repeatedly checks the condition and then sleeps, using `backoff.Step()` to determine the length of the sleep and adjust Duration and Steps. Stops and returns as soon as: 1. the condition check returns true or an error, 2. `backoff.Steps` checks of the condition have been done, or 3. a sleep truncated by the cap on duration has been completed. In case (1) the returned error is what the condition function returned. In all other cases, ErrWaitTimeout is returned.

Since backoffs are often subject to cancellation, we recommend using ExponentialBackoffWithContext and passing a context to the method.

func ExponentialBackoffWithContext added in v0.19.8 

func ExponentialBackoffWithContext(ctx context.Context, backoff Backoff, condition ConditionWithContextFunc) error

ExponentialBackoffWithContext repeats a condition check with exponential backoff. It immediately returns an error if the condition returns an error, the context is cancelled or hits the deadline, or if the maximum attempts defined in backoff is exceeded (ErrWaitTimeout). If an error is returned by the condition the backoff stops immediately. The condition will never be invoked more than backoff.Steps times.

func Forever 

func Forever(f func(), period time.Duration)

Forever calls f every period for ever.

Forever is syntactic sugar on top of Until.

func Interrupted added in v0.27.0 

func Interrupted(err error) bool

Interrupted returns true if the error indicates a Poll, ExponentialBackoff, or Until loop exited for any reason besides the condition returning true or an error. A loop is considered interrupted if the calling context is cancelled, the context reaches its deadline, or a backoff reaches its maximum allowed steps.

Callers should use this method instead of comparing the error value directly to ErrWaitTimeout, as methods that cancel a context may not return that error.

Instead of: 

err := wait.Poll(...)
if err == wait.ErrWaitTimeout {
    log.Infof("Wait for operation exceeded")
} else ...

Use: 

err := wait.Poll(...)
if wait.Interrupted(err) {
    log.Infof("Wait for operation exceeded")
} else ...

func Jitter 

func Jitter(duration time.Duration, maxFactor float64) time.Duration

Jitter returns a time.Duration between duration and duration + maxFactor * duration.

This allows clients to avoid converging on periodic behavior. If maxFactor is 0.0, a suggested default value will be chosen.

func JitterUntil 

func JitterUntil(f func(), period time.Duration, jitterFactor float64, sliding bool, stopCh <-chan struct{})

JitterUntil loops until stop channel is closed, running f every period.

If jitterFactor is positive, the period is jittered before every run of f. If jitterFactor is not positive, the period is unchanged and not jittered.

If sliding is true, the period is computed after f runs. If it is false then period includes the runtime for f.

Close stopCh to stop. f may not be invoked if stop channel is already closed. Pass NeverStop to if you don't want it stop.

func JitterUntilWithContext 

func JitterUntilWithContext(ctx context.Context, f func(context.Context), period time.Duration, jitterFactor float64, sliding bool)

JitterUntilWithContext loops until context is done, running f every period.

If jitterFactor is positive, the period is jittered before every run of f. If jitterFactor is not positive, the period is unchanged and not jittered.

If sliding is true, the period is computed after f runs. If it is false then period includes the runtime for f.

Cancel context to stop. f may not be invoked if context is already expired.

func NonSlidingUntil 

func NonSlidingUntil(f func(), period time.Duration, stopCh <-chan struct{})

NonSlidingUntil loops until stop channel is closed, running f every period.

NonSlidingUntil is syntactic sugar on top of JitterUntil with zero jitter factor, with sliding = false (meaning the timer for period starts at the same time as the function starts).

func NonSlidingUntilWithContext 

func NonSlidingUntilWithContext(ctx context.Context, f func(context.Context), period time.Duration)

NonSlidingUntilWithContext loops until context is done, running f every period.

NonSlidingUntilWithContext is syntactic sugar on top of JitterUntilWithContext with zero jitter factor, with sliding = false (meaning the timer for period starts at the same time as the function starts).

func Poll deprecated 

func Poll(interval, timeout time.Duration, condition ConditionFunc) error

Poll tries a condition func until it returns true, an error, or the timeout is reached.

Poll always waits the interval before the run of 'condition'. 'condition' will always be invoked at least once.

Some intervals may be missed if the condition takes too long or the time window is too short.

If you want to Poll something forever, see PollInfinite.

Deprecated: This method does not return errors from context, use PollUntilContextTimeout. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollImmediate deprecated 

func PollImmediate(interval, timeout time.Duration, condition ConditionFunc) error

PollImmediate tries a condition func until it returns true, an error, or the timeout is reached.

PollImmediate always checks 'condition' before waiting for the interval. 'condition' will always be invoked at least once.

Some intervals may be missed if the condition takes too long or the time window is too short.

If you want to immediately Poll something forever, see PollImmediateInfinite.

Deprecated: This method does not return errors from context, use PollUntilContextTimeout. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollImmediateInfinite deprecated 

func PollImmediateInfinite(interval time.Duration, condition ConditionFunc) error

PollImmediateInfinite tries a condition func until it returns true or an error

PollImmediateInfinite runs the 'condition' before waiting for the interval.

Some intervals may be missed if the condition takes too long or the time window is too short.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollImmediateInfiniteWithContext deprecated added in v0.22.0 

func PollImmediateInfiniteWithContext(ctx context.Context, interval time.Duration, condition ConditionWithContextFunc) error

PollImmediateInfiniteWithContext tries a condition func until it returns true or an error or the specified context gets cancelled or expired.

PollImmediateInfiniteWithContext runs the 'condition' before waiting for the interval.

Some intervals may be missed if the condition takes too long or the time window is too short.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollImmediateUntil deprecated 

func PollImmediateUntil(interval time.Duration, condition ConditionFunc, stopCh <-chan struct{}) error

PollImmediateUntil tries a condition func until it returns true, an error or stopCh is closed.

PollImmediateUntil runs the 'condition' before waiting for the interval. 'condition' will always be invoked at least once.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollImmediateUntilWithContext deprecated added in v0.22.0 

func PollImmediateUntilWithContext(ctx context.Context, interval time.Duration, condition ConditionWithContextFunc) error

PollImmediateUntilWithContext tries a condition func until it returns true, an error or the specified context is cancelled or expired.

PollImmediateUntilWithContext runs the 'condition' before waiting for the interval. 'condition' will always be invoked at least once.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollImmediateWithContext deprecated added in v0.22.0 

func PollImmediateWithContext(ctx context.Context, interval, timeout time.Duration, condition ConditionWithContextFunc) error

PollImmediateWithContext tries a condition func until it returns true, an error, or the timeout is reached or the specified context expires, whichever happens first.

PollImmediateWithContext always checks 'condition' before waiting for the interval. 'condition' will always be invoked at least once.

Some intervals may be missed if the condition takes too long or the time window is too short.

If you want to immediately Poll something forever, see PollImmediateInfinite.

Deprecated: This method does not return errors from context, use PollUntilContextTimeout. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollInfinite deprecated 

func PollInfinite(interval time.Duration, condition ConditionFunc) error

PollInfinite tries a condition func until it returns true or an error

PollInfinite always waits the interval before the run of 'condition'.

Some intervals may be missed if the condition takes too long or the time window is too short.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollInfiniteWithContext deprecated added in v0.22.0 

func PollInfiniteWithContext(ctx context.Context, interval time.Duration, condition ConditionWithContextFunc) error

PollInfiniteWithContext tries a condition func until it returns true or an error

PollInfiniteWithContext always waits the interval before the run of 'condition'.

Some intervals may be missed if the condition takes too long or the time window is too short.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollUntil deprecated 

func PollUntil(interval time.Duration, condition ConditionFunc, stopCh <-chan struct{}) error

PollUntil tries a condition func until it returns true, an error or stopCh is closed.

PollUntil always waits interval before the first run of 'condition'. 'condition' will always be invoked at least once.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollUntilContextCancel added in v0.27.0 

func PollUntilContextCancel(ctx context.Context, interval time.Duration, immediate bool, condition ConditionWithContextFunc) error

PollUntilContextCancel tries a condition func until it returns true, an error, or the context is cancelled or hits a deadline. condition will be invoked after the first interval if the context is not cancelled first. The returned error will be from ctx.Err(), the condition's err return value, or nil. If invoking condition takes longer than interval the next condition will be invoked immediately. When using very short intervals, condition may be invoked multiple times before a context cancellation is detected. If immediate is true, condition will be invoked before waiting and guarantees that condition is invoked at least once, regardless of whether the context has been cancelled.

func PollUntilContextTimeout added in v0.27.0 

func PollUntilContextTimeout(ctx context.Context, interval, timeout time.Duration, immediate bool, condition ConditionWithContextFunc) error

PollUntilContextTimeout will terminate polling after timeout duration by setting a context timeout. This is provided as a convenience function for callers not currently executing under a deadline and is equivalent to: 

deadlineCtx, deadlineCancel := context.WithTimeout(ctx, timeout)
err := PollUntilContextCancel(deadlineCtx, interval, immediate, condition)

The deadline context will be cancelled if the Poll succeeds before the timeout, simplifying inline usage. All other behavior is identical to PollUntilContextCancel.

func PollUntilWithContext deprecated added in v0.22.0 

func PollUntilWithContext(ctx context.Context, interval time.Duration, condition ConditionWithContextFunc) error

PollUntilWithContext tries a condition func until it returns true, an error or the specified context is cancelled or expired.

PollUntilWithContext always waits interval before the first run of 'condition'. 'condition' will always be invoked at least once.

Deprecated: This method does not return errors from context, use PollUntilContextCancel. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func PollWithContext deprecated added in v0.22.0 

func PollWithContext(ctx context.Context, interval, timeout time.Duration, condition ConditionWithContextFunc) error

PollWithContext tries a condition func until it returns true, an error, or when the context expires or the timeout is reached, whichever happens first.

PollWithContext always waits the interval before the run of 'condition'. 'condition' will always be invoked at least once.

Some intervals may be missed if the condition takes too long or the time window is too short.

If you want to Poll something forever, see PollInfinite.

Deprecated: This method does not return errors from context, use PollUntilContextTimeout. Note that the new method will no longer return ErrWaitTimeout and instead return errors defined by the context package. Will be removed in a future release.

func Until 

func Until(f func(), period time.Duration, stopCh <-chan struct{})

Until loops until stop channel is closed, running f every period.

Until is syntactic sugar on top of JitterUntil with zero jitter factor and with sliding = true (which means the timer for period starts after the f completes).

func UntilWithContext 

func UntilWithContext(ctx context.Context, f func(context.Context), period time.Duration)

UntilWithContext loops until context is done, running f every period.

UntilWithContext is syntactic sugar on top of JitterUntilWithContext with zero jitter factor and with sliding = true (which means the timer for period starts after the f completes).

Types

type Backoff 

type Backoff struct {
	// The initial duration.
	Duration time.Duration
	// Duration is multiplied by factor each iteration, if factor is not zero
	// and the limits imposed by Steps and Cap have not been reached.
	// Should not be negative.
	// The jitter does not contribute to the updates to the duration parameter.
	Factor float64
	// The sleep at each iteration is the duration plus an additional
	// amount chosen uniformly at random from the interval between
	// zero and `jitter*duration`.
	Jitter float64
	// The remaining number of iterations in which the duration
	// parameter may change (but progress can be stopped earlier by
	// hitting the cap). If not positive, the duration is not
	// changed. Used for exponential backoff in combination with
	// Factor and Cap.
	Steps int
	// A limit on revised values of the duration parameter. If a
	// multiplication by the factor parameter would make the duration
	// exceed the cap then the duration is set to the cap and the
	// steps parameter is set to zero.
	Cap time.Duration
}

Backoff holds parameters applied to a Backoff function.

func (Backoff) DelayFunc added in v0.27.0 

func (b Backoff) DelayFunc() DelayFunc

DelayFunc returns a function that will compute the next interval to wait given the arguments in b. It does not mutate the original backoff but the function is safe to use only from a single goroutine.

func (Backoff) DelayWithReset added in v0.27.0 

func (b Backoff) DelayWithReset(c clock.Clock, resetInterval time.Duration) DelayFunc

DelayWithReset returns a DelayFunc that will return the appropriate next interval to wait. Every resetInterval the backoff parameters are reset to their initial state. This method is safe to invoke from multiple goroutines, but all calls will advance the backoff state when Factor is set. If Factor is zero, this method is the same as invoking b.DelayFunc() since Steps has no impact without Factor. If resetInterval is zero no backoff will be performed as the same calling DelayFunc with a zero factor and steps.

func (*Backoff) Step 

func (b *Backoff) Step() time.Duration

Step returns an amount of time to sleep determined by the original Duration and Jitter. The backoff is mutated to update its Steps and Duration. A nil Backoff always has a zero-duration step.

func (Backoff) Timer added in v0.27.0 

func (b Backoff) Timer() Timer

Timer returns a timer implementation appropriate to this backoff's parameters for use with wait functions.

type BackoffManager added in v0.18.0 

type BackoffManager interface {
	// Backoff returns a shared clock.Timer that is Reset on every invocation. This method is not
	// safe for use from multiple threads. It returns a timer for backoff, and caller shall backoff
	// until Timer.C() drains. If the second Backoff() is called before the timer from the first
	// Backoff() call finishes, the first timer will NOT be drained and result in undetermined
	// behavior.
	Backoff() clock.Timer
}

BackoffManager manages backoff with a particular scheme based on its underlying implementation.

func NewExponentialBackoffManager deprecated added in v0.18.0 

func NewExponentialBackoffManager(initBackoff, maxBackoff, resetDuration time.Duration, backoffFactor, jitter float64, c clock.Clock) BackoffManager

NewExponentialBackoffManager returns a manager for managing exponential backoff. Each backoff is jittered and backoff will not exceed the given max. If the backoff is not called within resetDuration, the backoff is reset. This backoff manager is used to reduce load during upstream unhealthiness.

Deprecated: Will be removed when the legacy Poll methods are removed. Callers should construct a Backoff struct, use DelayWithReset() to get a DelayFunc that periodically resets itself, and then invoke Timer() when calling wait.BackoffUntil.

Instead of: 

bm := wait.NewExponentialBackoffManager(init, max, reset, factor, jitter, clock)
...
wait.BackoffUntil(..., bm.Backoff, ...)

Use: 

delayFn := wait.Backoff{
  Duration: init,
  Cap:      max,
  Steps:    int(math.Ceil(float64(max) / float64(init))), // now a required argument
  Factor:   factor,
  Jitter:   jitter,
}.DelayWithReset(reset, clock)
wait.BackoffUntil(..., delayFn.Timer(), ...)

func NewJitteredBackoffManager deprecated added in v0.18.0 

func NewJitteredBackoffManager(duration time.Duration, jitter float64, c clock.Clock) BackoffManager

NewJitteredBackoffManager returns a BackoffManager that backoffs with given duration plus given jitter. If the jitter is negative, backoff will not be jittered.

Deprecated: Will be removed when the legacy Poll methods are removed. Callers should construct a Backoff struct and invoke Timer() when calling wait.BackoffUntil.

Instead of: 

bm := wait.NewJitteredBackoffManager(duration, jitter, clock)
...
wait.BackoffUntil(..., bm.Backoff, ...)

Use: 

wait.BackoffUntil(..., wait.Backoff{Duration: duration, Jitter: jitter}.Timer(), ...)

type ConditionFunc 

type ConditionFunc func() (done bool, err error)

ConditionFunc returns true if the condition is satisfied, or an error if the loop should be aborted.

func (ConditionFunc) WithContext added in v0.22.0 

func (cf ConditionFunc) WithContext() ConditionWithContextFunc

WithContext converts a ConditionFunc into a ConditionWithContextFunc

type ConditionWithContextFunc added in v0.22.0 

type ConditionWithContextFunc func(context.Context) (done bool, err error)

ConditionWithContextFunc returns true if the condition is satisfied, or an error if the loop should be aborted.

The caller passes along a context that can be used by the condition function.

type DelayFunc added in v0.27.0 

type DelayFunc func() time.Duration

DelayFunc returns the next time interval to wait.

func (DelayFunc) Concurrent added in v0.27.0 

func (fn DelayFunc) Concurrent() DelayFunc

Concurrent returns a version of this DelayFunc that is safe for use by multiple goroutines that wish to share a single delay timer.

func (DelayFunc) Timer added in v0.27.0 

func (fn DelayFunc) Timer(c clock.Clock) Timer

Timer takes an arbitrary delay function and returns a timer that can handle arbitrary interval changes. Use Backoff{...}.Timer() for simple delays and more efficient timers.

func (DelayFunc) Until added in v0.27.0 

func (fn DelayFunc) Until(ctx context.Context, immediate, sliding bool, condition ConditionWithContextFunc) error

Until takes an arbitrary delay function and runs until cancelled or the condition indicates exit. This offers all of the functionality of the methods in this package.

type Group 

type Group struct {
	// contains filtered or unexported fields
}

Group allows to start a group of goroutines and wait for their completion.

func (*Group) Start 

func (g *Group) Start(f func())

Start starts f in a new goroutine in the group.

func (*Group) StartWithChannel 

func (g *Group) StartWithChannel(stopCh <-chan struct{}, f func(stopCh <-chan struct{}))

StartWithChannel starts f in a new goroutine in the group. stopCh is passed to f as an argument. f should stop when stopCh is available.

func (*Group) StartWithContext 

func (g *Group) StartWithContext(ctx context.Context, f func(context.Context))

StartWithContext starts f in a new goroutine in the group. ctx is passed to f as an argument. f should stop when ctx.Done() is available.

func (*Group) Wait 

func (g *Group) Wait()

type Timer added in v0.27.0 

type Timer interface {
	// C returns a channel that will receive a struct{} each time the timer fires.
	// The channel should not be waited on after Stop() is invoked. It is allowed
	// to cache the returned value of C() for the lifetime of the Timer.
	C() <-chan time.Time
	// Next is invoked by wait functions to signal timers that the next interval
	// should begin. You may only use Next() if you have drained the channel C().
	// You should not call Next() after Stop() is invoked.
	Next()
	// Stop releases the timer. It is safe to invoke if no other methods have been
	// called.
	Stop()
}

Timer abstracts how wait functions interact with time runtime efficiently. Test code may implement this interface directly but package consumers are encouraged to use the Backoff type as the primary mechanism for acquiring a Timer. The interface is a simplification of clock.Timer to prevent misuse. Timers are not expected to be safe for calls from multiple goroutines.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.