backoff

README

Backoff

This package implements concurrency safe and reusable backoff algorithms. All the algorithms will have the optional jitter applied after the delay has been calculated.

Concurrency safety relies on the struct fields not being changed when they might be in use. Once set, the code will not make any changes to the fields.

Algorithms

Algorithm	Formula	Description
Constant	x(n) = b	Causes a constant delay between each adverse event.
Linear	x(n) = b × a	Causes a linearly increasing backoff delay that scales with the number of adverse events.
Exponential	x(n) = b × fⁿ⁻¹	Causes an exponentially increasing backoff delay that scales with the number of adverse events and the factor (f) of at least 2 or higher.

The optional jitter (j) is added to the delay returned by the algorithms. A constant delay with jitter can be expressed as x(n) = n ± j.

What is it for?

Backoff algorithms are used to add a delay between attempts of an operation that can fail but can be repeated. An example is connecting to a database where one failed attempt should not cause the application to just exit. Repeating attempts should not be done at the highest possible speed that an application can do it since it would just cause unnecessary CPU usage and network traffic that can raise alarms in firewalls.

Documentation

Index

• type Backoff
• type ConstantBackoff
  • func Constant() ConstantBackoff
  • func (c ConstantBackoff) Delay(baseDelay time.Duration, _ int64) time.Duration
• type DoFunc
• type ExponentialBackoff
  • func Exponential(factor int64) ExponentialBackoff
  • func (e ExponentialBackoff) Delay(baseDelay time.Duration, adverseEvents int64) time.Duration
• type LinearBackoff
  • func Linear(m float64) LinearBackoff
  • func (l LinearBackoff) Delay(baseDelay time.Duration, adverseEvents int64) time.Duration
• type MaxAdverseEventsReachedError
  • func (e MaxAdverseEventsReachedError) Error() string
• type Retryable
  • func (r *Retryable) Retry(ctx context.Context, do DoFunc) error
  • func (r *Retryable) RetryWithTimeout(ctx context.Context, timeout time.Duration, do DoFunc) error

Types

type Backoff

type Backoff interface {
	// Delay takes two arguments which represent the base delay and the number of adverse events and returns a backoff delay.
	// Jitter will be applied to the returned delay.
	Delay(time.Duration, int64) time.Duration
}

type ConstantBackoff

type ConstantBackoff struct{}

ConstantBackoff implements Backoff where the returned delay will always be the base delay.

func Constant

func Constant() ConstantBackoff

func (ConstantBackoff) Delay

func (c ConstantBackoff) Delay(baseDelay time.Duration, _ int64) time.Duration

Delay returns the base delay given by the caller. The number of adverse events are ignored.

type DoFunc

type DoFunc func(ctx context.Context) error

type ExponentialBackoff

type ExponentialBackoff struct {
	// Factor is used to calculate the exponentially increasing the backoff delay.
	Factor int64
}

ExponentialBackoff satisfies Backoff and will cause exponentially increasing delay.

Formula: x(n) = b × fⁿ⁻¹ ± j, where n is the number of adverse events.

func Exponential

func Exponential(factor int64) ExponentialBackoff

func (ExponentialBackoff) Delay

func (e ExponentialBackoff) Delay(baseDelay time.Duration, adverseEvents int64) time.Duration

type LinearBackoff

type LinearBackoff struct {
	// Slope is the multiplicative factor m in "f(n) = m × n + b" where n is the number of adverse effects and b is the
	// base delay. A slope factor of 1.0 will cause the base delay to be multiplied with the number of adverse events
	// and is therefore at a 45° angle.
	Slope float64
}

LinearBackoff satisfies Backoff and will cause a linearly increasing delay.

func Linear

func Linear(m float64) LinearBackoff

func (LinearBackoff) Delay

func (l LinearBackoff) Delay(baseDelay time.Duration, adverseEvents int64) time.Duration

type MaxAdverseEventsReachedError

type MaxAdverseEventsReachedError struct {
	Max    uint
	Actual int64
}

func (MaxAdverseEventsReachedError) Error

func (e MaxAdverseEventsReachedError) Error() string

type Retryable

type Retryable struct {
	Backoff          Backoff
	MaxAdverseEvents uint
	BaseDelay        time.Duration
	MaxDelay         time.Duration
	Jitter           time.Duration
}

func (*Retryable) Retry

func (r *Retryable) Retry(ctx context.Context, do DoFunc) error

func (*Retryable) RetryWithTimeout

func (r *Retryable) RetryWithTimeout(ctx context.Context, timeout time.Duration, do DoFunc) error

RetryWithTimeout is a wrapper of Retry which will abort the retries when timeout has been reached. This function only provides what you could do yourself by passing a context with a deadline.