wait

Documentation

Overview

Package wait provides a generic waiting for conditions by polling, some standard tickers for the polling are already pre-defined.

Additionally the package provide a throttle for the limited processing of events per second.

Index

• Constants
• func Poll(ctx context.Context, ticker TickerFunc, condition ConditionFunc) error
• func WithDeadline(ctx context.Context, interval time.Duration, deadline time.Time, ...) error
• func WithInterval(ctx context.Context, interval time.Duration, condition ConditionFunc) error
• func WithJitter(ctx context.Context, interval time.Duration, factor float64, ...) error
• func WithMaxIntervals(ctx context.Context, interval time.Duration, max int, condition ConditionFunc) error
• func WithTimeout(ctx context.Context, interval, timeout time.Duration, condition ConditionFunc) error
• type ConditionFunc
• type Limit
• type Task
• type Throttle
  • func NewThrottle(limit Limit, burst int) *Throttle
  • func (t *Throttle) Process(ctx context.Context, task Task) error
• type TickChangerFunc
• type TickerFunc
  • func MakeDeadlinedIntervalTicker(interval time.Duration, deadline time.Time) TickerFunc
  • func MakeExpiringIntervalTicker(interval, timeout time.Duration) TickerFunc
  • func MakeGenericIntervalTicker(changer TickChangerFunc) TickerFunc
  • func MakeIntervalTicker(interval time.Duration) TickerFunc
  • func MakeJitteringTicker(interval time.Duration, factor float64, timeout time.Duration) TickerFunc
  • func MakeMaxIntervalsTicker(interval time.Duration, max int) TickerFunc

Constants

const (
	// Inf is the infinite rate limit.
	InfLimit = Limit(math.MaxFloat64)
)

Functions

func Poll

func Poll(ctx context.Context, ticker TickerFunc, condition ConditionFunc) error

Poll 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, - a constant number of intervals with a deadline, - a constant number of 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):

// Tick every second for maximal 30 seconds.
ticker := wait.MakeExpiringIntervalTicker(time.Second, 30*time.Second),

// Check for existence of a file.
condition := func() (bool, error) {
    _, err := os.Stat("myfile.txt")
    if err != nil {
        if os.IsNotExist(err) {
            return false, nil
        }
        return false, err
    }
    // Found file.
    return true, nil
}

// And now poll.
wait.Poll(ctx, ticker, condition)

From outside the polling can be stopped by cancelling the context.

func WithDeadline

func WithDeadline(
	ctx context.Context,
	interval time.Duration,
	deadline time.Time,
	condition ConditionFunc,
) error

WithDeadline is convenience for Poll() with MakeDeadlinedIntervalTicker().

func WithInterval

func WithInterval(
	ctx context.Context,
	interval time.Duration,
	condition ConditionFunc,
) error

WithInterval is convenience for Poll() with MakeIntervalTicker().

func WithJitter

func WithJitter(
	ctx context.Context,
	interval time.Duration,
	factor float64,
	timeout time.Duration,
	condition ConditionFunc,
) error

WithJitter is convenience for Poll() with MakeJitteringTicker().

func WithMaxIntervals

func WithMaxIntervals(
	ctx context.Context,
	interval time.Duration,
	max int,
	condition ConditionFunc,
) error

WithMaxIntervals is convenience for Poll() with MakeMaxIntervalsTicker().

func WithTimeout

func WithTimeout(
	ctx context.Context,
	interval, timeout time.Duration,
	condition ConditionFunc,
) error

WithTimeout is convenience for Poll() with MakeExpiringIntervalTicker().

Types

type ConditionFunc

type ConditionFunc func() (bool, error)

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

type Limit = rate.Limit

Limit defines the rate limit of a throttle.

type Task

type Task func() error

Task defines the signarure of a task to be processed.

type Throttle

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

A Throttle limits the processing of tasks per second. It is configured with a limit and a burst. The limit is the maximum number of tasks per second and the burst the maximum number of tasks that can be processed at once. If the limit is InfLimit the throttle is not limited, if it is 0 no tasks can be processed.

func NewThrottle

func NewThrottle(limit Limit, burst int) *Throttle

NewThrottle creates a new Throttle with the specified limit and burst.

func (*Throttle) Process

func (t *Throttle) Process(ctx context.Context, task Task) error

Process processes a task under the context, waiting if necessary.

type TickChangerFunc

type TickChangerFunc func(in time.Duration) (out time.Duration, ok bool)

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

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

TickerFunc 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

func MakeDeadlinedIntervalTicker(interval time.Duration, deadline time.Time) TickerFunc

MakeDeadlinedIntervalTicker returns a ticker signalling in intervals and stopping after a deadline.

func MakeExpiringIntervalTicker

func MakeExpiringIntervalTicker(interval, timeout time.Duration) TickerFunc

MakeExpiringIntervalTicker returns a ticker signalling in intervals and stopping after a timeout.

func MakeGenericIntervalTicker

func MakeGenericIntervalTicker(changer TickChangerFunc) TickerFunc

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

func MakeIntervalTicker(interval time.Duration) TickerFunc

MakeIntervalTicker returns a ticker signalling in intervals.

func MakeJitteringTicker

func MakeJitteringTicker(interval time.Duration, factor float64, timeout time.Duration) TickerFunc

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.

func MakeMaxIntervalsTicker

func MakeMaxIntervalsTicker(interval time.Duration, max int) TickerFunc

MakeMaxIntervalsTicker returns a ticker signalling in intervals. It stops after a maximum number of signals.