wait

package module
Version: v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2021 License: BSD-3-Clause Imports: 4 Imported by: 0

README

Tideland Go Wait

GitHub release GitHub license Go Module GoDoc Workflow Go Report Card

Description

Tideland Go Wait provides provides a flexible and controlled waiting for wanted conditions by polling. The function for testing has to be defined, different tickers for the polling can be generated for

  • simple constant intervals,
  • a maximum number of constant intervals,
  • a constant number of intervals with a deadline,
  • c onstant number of intervals with a timeout, and
  • jittering intervals.

Own tickers or changing intervals can be implemented too.

I hope you like it. ;)

Examples

A simple check for an existing file by polling every second for maximal 30 seconds.

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

// Check for existence of a file.
contition := 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)

Contributors

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, - 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 external the polling can be stopped by cancelling the context.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Poll

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

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL