Version: v1.2.0 Latest Latest

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

Go to latest
Published: Aug 18, 2022 License: Apache-2.0 Imports: 3 Imported by: 0



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.



This section is empty.


View Source
var Exit time.Duration = -1

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


This section is empty.


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 added in v1.2.0

type ClockFunc func() time.Time

A ClockFunc is the functional implementation of the Clock interface.

func (ClockFunc) Time added in v1.2.0

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL