backoff

README

Backoff

Algorithms to generate intervals.

Example

Backoff is an interface which implements the NextInterval and the Reset methods. The NextInterval method returns a time.Duration according to the algorithm of the backoff and the current state of backoff (generally, state of the backoff includes the number of times the method has been called). The Reset method resets any such state.

b := NewLinearBackoff(time.Second, time.Second, time.Minute)

b.NextInterval() // time.Second * 1
b.NextInterval() // time.Second * 2
b.NextInterval() // time.Second * 3

// ...

b.NextInterval() // time.Minute
b.NextInterval() // time.Minute
b.NextInterval() // time.Minute

// ...

b.Reset()
b.NextInterval() // time.Second * 1

Four algorithms are provided. ZeroBackoff and ConstantBackoff return a constant duration on each call to NextInterval, and Reset is a no-op.

LinearBackoff, shown above, returns a linearly increasing duration according to a minimum interval, and a maximum interval, and the interval to increase by on each call.

ExponentialBackoff returns an exponentially increasing duration according to a minimum interval, a maximum interval, a multiplier, and a random factor. The multiplier dictates the base interval - e.g. (min * multiplier ^ n) on the the nth attempt, and the random factor dictates the interval's jitter such that the interval value i is randomized around i - i * jitter and i + i * jitter.

License

Copyright (c) 2016 Eric Fritz

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• type Backoff
  • func NewConstantBackoff(interval time.Duration) Backoff
  • func NewExponentialBackoff(minInterval, maxInterval time.Duration, configs ...ExponentialConfigFunc) Backoff
  • func NewLinearBackoff(minInterval, addInterval, maxInterval time.Duration) Backoff
  • func NewZeroBackoff() Backoff
• type ExponentialConfigFunc
  • func WithMultiplier(multiplier float64) ExponentialConfigFunc
  • func WithRandomFactor(randFactor float64) ExponentialConfigFunc

Types

type Backoff

type Backoff interface {
	// Mark the next call to NextInterval as the "first" retry in a sequence.
	// If the generated intervals are dependent on the number of consecutive
	// (unsuccessful) retries, previous retries should be forgotten here.
	Reset()

	// Generate the next backoff interval.
	NextInterval() time.Duration

	// Clone creates a copy of the backoff with a nil-internal state. This
	// allows a backoff object to be used as a prototype factory.
	Clone() Backoff
}

Backoff is the interface to a backoff interval generator.

func NewConstantBackoff

func NewConstantBackoff(interval time.Duration) Backoff

NewConstantBackoff creates a backoff interval generator which always returns the same interval.

func NewExponentialBackoff

func NewExponentialBackoff(minInterval, maxInterval time.Duration, configs ...ExponentialConfigFunc) Backoff

NewExponentialBackoff creates an exponential backoff interval generator using the given minimum and maximum interval. The base interval is given by the following function where n is the number of previous failed attempts in the current sequence.

`MinInterval * Multiplier ^ n`

The value returned on each update is given by the following, where base is the value calculated above. A random factor of zero makes the generator deterministic. Some random jitter tends to work well in practice to avoid issues around a thundering herd.

`min(MaxInterval, base +/- (base * RandFactor))`.

func NewLinearBackoff

func NewLinearBackoff(minInterval, addInterval, maxInterval time.Duration) Backoff

NewLinearBackoff creates a backoff interval generator which increases by a constant amount on each unsuccessful retry.

func NewZeroBackoff

func NewZeroBackoff() Backoff

NewZeroBackoff creates a backoff interval generator which always returns a zero interval.

type ExponentialConfigFunc

type ExponentialConfigFunc func(*exponentialBackoff)

ExponentialConfigFunc is a function used to initialize a new exponential backoff.

func WithMultiplier

func WithMultiplier(multiplier float64) ExponentialConfigFunc

WithMultiplier sets the base of the exponential function (default is 2).

func WithRandomFactor

func WithRandomFactor(randFactor float64) ExponentialConfigFunc

WithRandomFactor sets the random factor (default is 0, no randomness).