decay

Documentation

Overview

Package decay provides a generalized exponential backoff retry implementation.

Index

• Variables
• func Backoff(function TryFunc, options BackoffOptions) error
• type BackoffOptions
• type TryFunc

Variables

var (
	ErrMaximumTimeExceeded = errors.New("maximum backoff time exceeded")
)

Error values which may be returned by Backoff.

Functions

func Backoff

func Backoff(function TryFunc, options BackoffOptions) error

Backoff will attempt to execute function using a configurable exponential backoff algorithm. function is a TryFunc which requires two return parameters - a boolean for optimizing control flow, and an error for reporting failure conditions. If the first parameter is false, the backoff algorithm will abandon further retry attempts and simply return an error. Otherwise, if the returned error is non-nil, the backoff algorithm will sleep for an increasing amount of time, and then retry again later, until the maximum amount of sleep time has been consumed. Once function has executed successfully with no error, the backoff algorithm returns a nil error.

Types

type BackoffOptions

type BackoffOptions struct {
	// MaxSleepTime represents the maximum amount of time
	// the exponential backoff system will spend sleeping,
	// accumulating the amount of time spent asleep between
	// retries.
	//
	// The algorithm starts at an interval of InitialGapSize
	// and increases exponentially (x2 each iteration) from there.
	// With no jitter, a MaxSleepTime of 10 seconds and InitialGapSize
	// of 1 millisecond would suggest a total of 15 attempts
	// (since the very last retry truncates the sleep time to
	// align exactly with MaxSleepTime).
	MaxSleepTime time.Duration

	// InitialGapSize sets the initial amount of time the algorithm
	// will sleep before the first retry (after the first attempt).
	// The actual amount of sleep time will include a random amount
	// of jitter, if MaxJitterSize is non-zero.
	InitialGapSize time.Duration

	// MaxJitterSize limits how much randomness we may
	// introduce in the duration of each retry interval.
	// The purpose of introducing jitter is to mitigate the
	// effect of thundering herds
	MaxJitterSize time.Duration

	// RandomSeed is used for generating a randomly computed
	// jitter size for each retry.
	RandomSeed int64

	// Sleeper is used to cause the process to sleep for
	// a computed amount of time. If not set, a default
	// implementation based on time.Sleep will be used.
	Sleeper libtime.Sleeper
}

BackoffOptions allow for fine-tuning backoff behavior.

type TryFunc

type TryFunc func() (keepRetrying bool, err error)

A TryFunc is what gets executed between retry wait periods during execution of Backoff. The keepRetrying return value is used to control whether a retry attempt should be made. This feature is useful in manipulating control flow in cases where it is known a retry will not be successful.