wait

Documentation

Overview

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

Index

• Variables
• func ExponentialBackoff(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, stopCh <-chan struct{})
• func Poll(interval, timeout time.Duration, condition ConditionFunc) error
• func PollImmediate(interval, timeout time.Duration, condition ConditionFunc) error
• func PollInfinite(interval time.Duration, condition ConditionFunc) error
• func Until(f func(), period time.Duration, stopCh <-chan struct{})
• func WaitFor(wait WaitFunc, fn ConditionFunc, done <-chan struct{}) error
• type Backoff
• type ConditionFunc
• type WaitFunc

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 ExponentialBackoff

func ExponentialBackoff(backoff Backoff, condition ConditionFunc) error

ExponentialBackoff repeats a condition check up to steps times, increasing the wait by multipling the previous duration by factor. If jitter is greater than zero, a random amount of each duration is added (between duration and duration*(1+jitter)). If the condition never returns true, ErrWaitTimeout is returned. All other errors terminate immediately.

func Forever

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

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, to allow 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, 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. Catches any panics, and keeps going. f may not be invoked if stop channel is already closed. Pass NeverStop to Until if you don't want it stop.

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. condition will always be invoked at least once but 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. Poll always waits the interval before the first check of the condition.

func PollImmediate

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

PollImmediate is identical to Poll, except that it performs the first check immediately, not waiting interval beforehand.

func PollInfinite

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

PollInfinite polls forever.

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

func WaitFor

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

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 fn returns an error the loop ends and that error is returned, and if fn returns true the loop ends and nil is returned. ErrWaitTimeout will be returned if the channel is closed without fn ever returning true.

Types

type Backoff

type Backoff struct {
	Duration time.Duration
	Factor   float64
	Jitter   float64
	Steps    int
}

Backoff is parameters applied to a Backoff function.

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.

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.