backoff

Documentation

Overview

Package backoff provides various backoff strategies.

In particular, the package implements Constant, Linear and Exponential backoff strategies as well as some decorators to adjust their behavior. These include setting a Timeout, a delay Cap, an attempt Limit, or adding random Jitter.

Index

• Variables
• type Clock
• type ClockFunc
  • func (f ClockFunc) Time() time.Time
• type Random
• type Strategy
  • func Cap(strategy Strategy, max time.Duration) Strategy
  • func Constant(d time.Duration) Strategy
  • func Exponential(d time.Duration, m float64) Strategy
  • func Jitter(strategy Strategy, spread float64, random Random) Strategy
  • func Limit(strategy Strategy, n int) Strategy
  • func Linear(d time.Duration, k time.Duration) Strategy
  • func Timeout(strategy Strategy, limit time.Duration, clock Clock) Strategy

Variables

var Exit time.Duration = -1

Exit is returned by a backoff Strategy to signal the end of a retry cycle.

Types

type Clock

type Clock interface {
	// Time returns the current time.
	Time() time.Time
}

A Clock is used to determine the reference time in time-based logic.

type ClockFunc

type ClockFunc func() time.Time

A ClockFunc is the functional implementation of the Clock interface.

func (ClockFunc) Time

func (f ClockFunc) Time() time.Time

type Random

type Random func() float64

Random returns a pseudo-random number in the half-open interval [0,1).

type Strategy

type Strategy interface {
	// Delay returns the time to wait after the n-th retry of a failing function
	// call. For implementing time-based algorithms, the function also takes the
	// start time of the retry cycle. To stop the cycle after n attempts, the
	// function must return Exit. Note that the initial attempt corresponds to
	// n = 1.
	Delay(n int, start time.Time) time.Duration
}

Strategy determines the delay between consecutive retries in a backoff scenario. Implementations of this interface should be stateless because they might be used in multiple concurrent goroutines.

var Once Strategy = &constant{Exit}

Once is a backoff Strategy that always returns Exit, i.e. exits after the first attempt. Mostly useful for testing purposes.

func Cap

func Cap(strategy Strategy, max time.Duration) Strategy

Cap wraps a backoff Strategy to cap produced delays at the given maximum. If max <= 0, no limit will be applied.

func Constant

func Constant(d time.Duration) Strategy

Constant returns a backoff Strategy that always returns delay d. The function panics if d < 0.

func Exponential

func Exponential(d time.Duration, m float64) Strategy

Exponential returns a backoff Strategy producing delays that exponentially grow (m > 1), or shrink (m < 1) by the factor m, starting from the specified initial delay d. The function panics if d or m are negative.

func Jitter

func Jitter(strategy Strategy, spread float64, random Random) Strategy

Jitter wraps a backoff Strategy to randomly spread produced delays around in time. The spread factor determines the relative range in which delays are scattered. It must fall in the half-open interval [0,1). For example, a spread of 0.5 results in delays ranging between 50% above and 50% below the values produced by the wrapped strategy. If spread = 0, no jitter will be applied.

func Limit

func Limit(strategy Strategy, n int) Strategy

Limit wraps a backoff Strategy to end the retry cycle after n attempts. If n < 1, no limit will be applied.

func Linear

func Linear(d time.Duration, k time.Duration) Strategy

Linear returns a backoff Strategy producing delays that grow linearly in in steps of k, starting from the specified initial delay d. If k is negative, the delay shrinks to 0 and then stops decreasing. The function panics if d is negative.

func Timeout

func Timeout(strategy Strategy, limit time.Duration, clock Clock) Strategy

Timeout wraps a backoff Strategy to exit the retry cycle after the given duration has passed. The elapsed time is measured relative to the time supplied by clock. If limit <= 0, no timeout will be applied.