backoff

README

Backoff

import (
    // ...
    "github.com/bitdabbler/backoff"
)

Purpose

backoff is a tiny Go library enabling simple and consistent exponential backoff with jitter.

Basic Usage

    b := backoff.CoerceNew()

    for i := 0; i < maxRetries; i++ {
        ok := somethingFailableAndRetryable()
        if !ok {
            b.Sleep()
        }
    } 

Details

Constructors

1. func CoerceNew(options ...BackoffOption) *Backoff
2. func New(options ...BackoffOption) (*Backoff, error)

The CoerceNew constructor clamps option inputs to valid values to guarantee that it returns a valid Backoff.

Options

Option	Default
backoff.WithInitialDelay(time.Duration)	default 100ms
backoff.WithBaseDelay(time.Duration)	default 100ms
backoff.WithExponentialLimit(time.Duration)	default 3 mins
backoff.WithJitterFactor(float64)	default 0.3

If the initial backoff is 0, then the second backoff will use the base backoff value, and then grow exponentially in each subsequent backoff round.

Documentation

Overview

Package backoff provides a backoff object that makes it easy to consistently apply exponential backoff with jitter.

Ex.
b, err := NewBackoff(
  WithInitialDelay(0),
  WithBaseDelay(time.Millisecond * 500),
  WithExponentialLimit(time.Second * 60), // stop growing exponentially after 1 min
)
if err != nil {
    log.Fatalln(err)
}
b.Sleep() // immediately retry because initial delay = 0
b.Sleep() // wait 425~575ms, base delay of 500ms +/- 15%, the default jitter
b.Sleep() // wait 850~1150ms  		~1s
b.Sleep() // wait 1700~2300ms 		~2s
b.Sleep() // wait 3400-4600ms 		~4s
b.Sleep() // wait 6800~9200ms 		~8s
b.Sleep() // wait 1360~1840ms 		~16s
b.Sleep() // wait 27200~36800ms 	~32s
b.Sleep() // wait 54400~73600ms 	~64s
b.Sleep() // wait 54400~73600ms 	~64s (stopped growing, jitter still applied)

Index

• func WithBaseDelay(d time.Duration) backoffOption
• func WithExponentialLimit(d time.Duration) backoffOption
• func WithInitialDelay(d time.Duration) backoffOption
• func WithJitterFactor(jitterFactor float64) backoffOption
• type Backoff
  • func CoerceNew(options ...backoffOption) *Backoff
  • func New(options ...backoffOption) (*Backoff, error)
  • func (b *Backoff) PeekDelay() time.Duration
  • func (b *Backoff) Sleep()

Functions

func WithBaseDelay

func WithBaseDelay(d time.Duration) backoffOption

WithBaseDelay configuration BackoffOption allows customization of the backoff delay (before jitter), used after the initial delay, if the initial delay is 0 (so, on the second call to `backoff.Sleep()` in that case). The default is 100ms.

The base delay must be > 0, and is only used if the initial delay is 0.

func WithExponentialLimit

func WithExponentialLimit(d time.Duration) backoffOption

WithExponentialLimit configuration BackoffOption allows customization of the backoff delay beyond which it stops growing exponentially. It is possible to set the limit to 0, in which case the it will never grow beyond the base delay. though jitter will still be applied in all cases. The default is 3 minutes.

func WithInitialDelay

func WithInitialDelay(d time.Duration) backoffOption

WithInitialDelay configuration BackoffOption allows customization of the initial backoff delay (before jitter). It is safe to set this to 0, allowing the first retry to occur immediately, then after the first delay it will still grow exponentially from the `BaseDelay`. The default initial backoff delay is 100ms.

func WithJitterFactor

func WithJitterFactor(jitterFactor float64) backoffOption

WithJitterFactor configuration BackoffOption allows customization of the jitter factor. The value must be in the range [0,1). Jitter is applied uniformly randomly about the backoff delay, so 0.3 represents the backoff delay being adjusted by +/- 15%. The default is 0.3.

Types

type Backoff

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

Backoff provides exponential backoff with jitter. By default, the initial backoff is 100ms, the jitter factor is 0.3 (so +/- 15%), and exponential growth stops once the backoff reaches 3 minutes.

func CoerceNew

func CoerceNew(options ...backoffOption) *Backoff

CoerceNew creates a new exponential backoff object, coercing invalid options to valid values, to guarantee that it returns a valid backoff.

func New

func New(options ...backoffOption) (*Backoff, error)

New creates a new exponential backoff object. Use the Sleep() method to pause using exponential backoff with jitter. The default initial delay is 100ms, with a jitter of +/- 30%, and exponential growth until the delay reaches 3 minutes.

func (*Backoff) PeekDelay

func (b *Backoff) PeekDelay() time.Duration

PeekDelay allows the caller to query the hext delay without performing the backoff (i.e. without pausing execution or growing the backoff delay).

func (*Backoff) Sleep

func (b *Backoff) Sleep()

Sleep pauses execution on the current thread. The duration of the sleep increases exponentially, up to a limit, and random jitter is applied to mitigate the thundering herd problem.