Documentation
¶
Overview ¶
Package wait provides different ways to wait for conditions by polling. The conditions are checked by user defined functions with the signature
func() (ok bool, err error)
Here the bool return value signals if the condition is fulfilled, e.g. a file you're waiting for has been written into the according directory.
This signal for check a condition is returned by a ticker with the signature
func(ctx context.Context) <-chan struct{}
The context is for signalling the ticker to end working, the channel for the signals. Pre-defined tickers support
- simple constant intervals, - a maximum number of constant intervals, - constant intervals with a deadline, - constant intervals with a timeout, and - jittering intervals.
The behaviour of changing intervals can be user defined by functions with the signature
func(in time.Duration) (out time.Duration, ok bool)
Here the argument is the current interval, return values are the wanted interval and if the polling shall continue. For the predefined tickers according convenience functions named With...() exist.
Example (waiting for a file to exist):
wait.Poll(
ctx,
wait.MakeExpiringIntervalTicker(time.Second, 30*time.Second),
func() (bool, error) {
_, err := os.Stat(myFile)
if err == nil {
return true, nil
}
if os.IsNotExist(err) {
return false, nil
}
return false, err
},
)
From external the polling can be stopped by cancelling the context.
Index ¶
- func Poll(ctx context.Context, ticker Ticker, condition Condition) error
- func WithDeadline(ctx context.Context, interval time.Duration, deadline time.Time, ...) error
- func WithInterval(ctx context.Context, interval time.Duration, condition Condition) error
- func WithJitter(ctx context.Context, interval time.Duration, factor float64, ...) error
- func WithMaxIntervals(ctx context.Context, interval time.Duration, max int, condition Condition) error
- func WithTimeout(ctx context.Context, interval, timeout time.Duration, condition Condition) error
- type Condition
- type TickChanger
- type Ticker
- func MakeDeadlinedIntervalTicker(interval time.Duration, deadline time.Time) Ticker
- func MakeExpiringIntervalTicker(interval, timeout time.Duration) Ticker
- func MakeGenericIntervalTicker(changer TickChanger) Ticker
- func MakeIntervalTicker(interval time.Duration) Ticker
- func MakeJitteringTicker(interval time.Duration, factor float64, timeout time.Duration) Ticker
- func MakeMaxIntervalsTicker(interval time.Duration, max int) Ticker
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Poll ¶
Poll checks the condition until it returns true or an error. The ticker sends signals whenever the condition shall be checked. It closes the returned channel when the polling shall stop.
func WithDeadline ¶
func WithDeadline( ctx context.Context, interval time.Duration, deadline time.Time, condition Condition, ) error
WithDeadline is convenience for Poll() with MakeDeadlinedIntervalTicker().
func WithInterval ¶
WithInterval is convenience for Poll() with MakeIntervalTicker().
func WithJitter ¶
func WithJitter( ctx context.Context, interval time.Duration, factor float64, timeout time.Duration, condition Condition, ) error
WithJitter is convenience for Poll() with MakeJitteringTicker().
Types ¶
type Condition ¶
Condition has to be implemented for checking the wanted condition. A positive condition will return true and nil, a negative false and nil. In case of failure during the check false and the error have to be returned. The function will be used by the poll functions.
type TickChanger ¶
TickChanger allows to work with changing intervals. The current one is the argument, the next has to be returned. In case the bool return value is false the ticker will stop.
type Ticker ¶
Ticker defines a function sending signals for each condition check when polling. The ticker can be canceled via the given context. Closing the returned signal channel means that the ticker ended. Sending ticks should be able to handle not received ones in case the condition check of the poller is working.
func MakeDeadlinedIntervalTicker ¶
MakeDeadlinedIntervalTicker returns a ticker signalling in intervals and stopping after a deadline.
func MakeExpiringIntervalTicker ¶
MakeExpiringIntervalTicker returns a ticker signalling in intervals and stopping after a timeout.
func MakeGenericIntervalTicker ¶
func MakeGenericIntervalTicker(changer TickChanger) Ticker
MakeGenericIntervalTicker is a factory for tickers based on time intervals. The given changer is responsible for the intervals and if the ticker shall signal a stopping. The changer is called initially with a duration of zero to allow the changer stopping the ticker even before a first tick.
func MakeIntervalTicker ¶
MakeIntervalTicker returns a ticker signalling in intervals.
func MakeJitteringTicker ¶
MakeJitteringTicker returns a ticker signalling in jittering intervals. This avoids converging on periadoc behavior during condition check. The returned intervals jitter between the given interval and interval + factor * interval. The ticker stops after reaching timeout.
Source Files