wait

Documentation

Overview

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

Index

• Variables
• func BackoffUntil(f func(), backoff BackoffManager, sliding bool, stopCh <-chan struct{})
• func ExponentialBackoff(backoff Backoff, condition ConditionFunc) error
• func ExponentialBackoffWithContext(ctx context.Context, backoff Backoff, condition ConditionFunc) error
• func Forever(f func(), period time.Duration)
• func Jitter(duration time.Duration, maxFactor float64) time.Duration
• func JitterUntil(f func(), period time.Duration, jitterFactor float64, sliding bool, ...)
• func JitterUntilWithContext(ctx context.Context, f func(context.Context), period time.Duration, ...)
• func NonSlidingUntil(f func(), period time.Duration, stopCh <-chan struct{})
• func NonSlidingUntilWithContext(ctx context.Context, f func(context.Context), period time.Duration)
• func Poll(interval, timeout time.Duration, condition ConditionFunc) error
• func PollImmediate(interval, timeout time.Duration, condition ConditionFunc) error
• func PollImmediateInfinite(interval time.Duration, condition ConditionFunc) error
• func PollImmediateInfiniteWithContext(ctx context.Context, interval time.Duration, ...) error
• func PollImmediateUntil(interval time.Duration, condition ConditionFunc, stopCh <-chan struct{}) error
• func PollImmediateUntilWithContext(ctx context.Context, interval time.Duration, ...) error
• func PollImmediateWithContext(ctx context.Context, interval, timeout time.Duration, ...) error
• func PollInfinite(interval time.Duration, condition ConditionFunc) error
• func PollInfiniteWithContext(ctx context.Context, interval time.Duration, ...) error
• func PollUntil(interval time.Duration, condition ConditionFunc, stopCh <-chan struct{}) error
• func PollUntilWithContext(ctx context.Context, interval time.Duration, ...) error
• func PollWithContext(ctx context.Context, interval, timeout time.Duration, ...) error
• func Until(f func(), period time.Duration, stopCh <-chan struct{})
• func UntilWithContext(ctx context.Context, f func(context.Context), period time.Duration)
• func WaitFor(wait WaitFunc, fn ConditionFunc, done <-chan struct{}) error
• func WaitForWithContext(ctx context.Context, wait WaitWithContextFunc, fn ConditionWithContextFunc) error
• type Backoff
  • func (b *Backoff) Step() time.Duration
• type BackoffManager
  • func NewExponentialBackoffManager(initBackoff, maxBackoff, resetDuration time.Duration, ...) BackoffManager
  • func NewJitteredBackoffManager(duration time.Duration, jitter float64, c clock.Clock) BackoffManager
• type ConditionFunc
  • func (cf ConditionFunc) WithContext() ConditionWithContextFunc
• type ConditionWithContextFunc
• type Group
  • func (g *Group) Start(f func())
  • func (g *Group) StartWithChannel(stopCh <-chan struct{}, f func(stopCh <-chan struct{}))
  • func (g *Group) StartWithContext(ctx context.Context, f func(context.Context))
  • func (g *Group) Wait()
• type WaitFunc
  • func (w WaitFunc) WithContext() WaitWithContextFunc
• type WaitWithContextFunc

Variables

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

ErrWaitTimeout is returned when the condition exited without success.

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.

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

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

Functions

func BackoffUntil

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

func ExponentialBackoffWithContext

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

ExponentialBackoffWithContext works with a request context and a Backoff. It ensures that the retry wait never exceeds the deadline specified by the request context.

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

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.

func PollImmediate

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.

func PollImmediateInfinite

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.

func PollImmediateInfiniteWithContext

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.

func PollImmediateUntil

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.

func PollImmediateUntilWithContext

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.

func PollImmediateWithContext

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.

func PollInfinite

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.

func PollInfiniteWithContext

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.

func PollUntil

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.

func PollUntilWithContext

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.

func PollWithContext

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.

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

func WaitFor

func WaitFor(wait WaitFunc, fn ConditionFunc, done <-chan struct{}) error

WaitFor continually checks 'fn' as driven by 'wait'.

WaitFor gets a channel from 'wait()”, and then invokes 'fn' once for every value placed on the channel and once more when the channel is closed. If the channel is closed and 'fn' returns false without error, WaitFor returns ErrWaitTimeout.

If 'fn' returns an error the loop ends and that error is returned. If 'fn' returns true the loop ends and nil is returned.

ErrWaitTimeout will be returned if the 'done' channel is closed without fn ever returning true.

When the done channel is closed, because the golang `select` statement is "uniform pseudo-random", the `fn` might still run one or multiple time, though eventually `WaitFor` will return.

func WaitForWithContext

func WaitForWithContext(ctx context.Context, wait WaitWithContextFunc, fn ConditionWithContextFunc) error

WaitForWithContext continually checks 'fn' as driven by 'wait'.

WaitForWithContext gets a channel from 'wait()”, and then invokes 'fn' once for every value placed on the channel and once more when the channel is closed. If the channel is closed and 'fn' returns false without error, WaitForWithContext returns ErrWaitTimeout.

If 'fn' returns an error the loop ends and that error is returned. If 'fn' returns true the loop ends and nil is returned.

context.Canceled will be returned if the ctx.Done() channel is closed without fn ever returning true.

When the ctx.Done() channel is closed, because the golang `select` statement is "uniform pseudo-random", the `fn` might still run one or multiple times, though eventually `WaitForWithContext` will return.

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

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

Step (1) returns an amount of time to sleep determined by the original Duration and Jitter and (2) mutates the provided Backoff to update its Steps and Duration.

type BackoffManager

type BackoffManager interface {
	Backoff() clock.Timer
}

BackoffManager manages backoff with a particular scheme based on its underlying implementation. It provides an interface to return 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. The BackoffManager is supposed to be called in a single-threaded environment.

func NewExponentialBackoffManager

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.

func NewJitteredBackoffManager

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.

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

func (cf ConditionFunc) WithContext() ConditionWithContextFunc

WithContext converts a ConditionFunc into a ConditionWithContextFunc

type ConditionWithContextFunc

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

type WaitFunc func(done <-chan struct{}) <-chan struct{}

WaitFunc creates a channel that receives an item every time a test should be executed and is closed when the last test should be invoked.

func (WaitFunc) WithContext

func (w WaitFunc) WithContext() WaitWithContextFunc

WithContext converts the WaitFunc to an equivalent WaitWithContextFunc

type WaitWithContextFunc

type WaitWithContextFunc func(ctx context.Context) <-chan struct{}

WaitWithContextFunc creates a channel that receives an item every time a test should be executed and is closed when the last test should be invoked.

When the specified context gets cancelled or expires the function stops sending item and returns immediately.