backoff

Documentation

Overview

Package backoff contains a configurable retry-functionality using either exponential or constant backoff

Index

• Constants
• func NewErrCannotRetry(err error) error
• func Retry(f Retryable) error
• type Backoff
  • func NewBackoff() *Backoff
  • func (b Backoff) Retry(f Retryable) error
  • func (b *Backoff) WithMaxIterationTime(v time.Duration) *Backoff
  • func (b *Backoff) WithMaxIterations(v uint64) *Backoff
  • func (b *Backoff) WithMaxTotalTime(v time.Duration) *Backoff
  • func (b *Backoff) WithMinIterationTime(v time.Duration) *Backoff
  • func (b *Backoff) WithMultiplier(v float64) *Backoff
• type ErrCannotRetry
  • func (e ErrCannotRetry) Error() string
  • func (e ErrCannotRetry) Unwrap() error
• type Retryable

Constants

const (
	// DefaultMaxIterations contains the default value to use for number of iterations: infinite
	DefaultMaxIterations uint64 = 0
	// DefaultMaxIterationTime contains the default value to use for maximum iteration time
	DefaultMaxIterationTime = 60 * time.Second
	// DefaultMaxTotalTime contains the default value to use for maximum execution time: infinite
	DefaultMaxTotalTime time.Duration = 0
	// DefaultMinIterationTime contains the default value to use for initial iteration time
	DefaultMinIterationTime = 100 * time.Millisecond
	// DefaultMultipler contains the default multiplier to apply to iteration time after each iteration
	DefaultMultipler float64 = 1.5
)

Functions

func NewErrCannotRetry

func NewErrCannotRetry(err error) error

NewErrCannotRetry wraps the given error into an ErrCannotRetry and should be used to break from a Retry() function when the retry should stop immediately

func Retry

func Retry(f Retryable) error

Retry is a convenience wrapper to execute the retry with default values (see exported constants)

Types

type Backoff

type Backoff struct {
	MaxIterations    uint64
	MaxIterationTime time.Duration
	MaxTotalTime     time.Duration
	MinIterationTime time.Duration
	Multiplier       float64
}

Backoff holds the configuration for backoff function retries

func NewBackoff

func NewBackoff() *Backoff

NewBackoff creates a new Backoff configuration with default values (see constants)

func (Backoff) Retry

func (b Backoff) Retry(f Retryable) error

Retry executes the function and waits for it to end successul or for the given limites to be reached. The returned error uses Go1.13 wrapping of errors and can be unwrapped into the error of the function itself.

To break free from the Retry function ignoring the remaining retries return an ErrCannotRetry containing the original error. At this point the ErrCannotRetry will NOT be returned but unwrapped. So returning NewErrCannotRetry(errors.New("foo")) will give you the errors.New("foo") as a return value from Retry.

func (*Backoff) WithMaxIterationTime

func (b *Backoff) WithMaxIterationTime(v time.Duration) *Backoff

WithMaxIterationTime is a wrapper around setting the MaxIterationTime and then returning the Backoff object to use in chained creation

func (*Backoff) WithMaxIterations

func (b *Backoff) WithMaxIterations(v uint64) *Backoff

WithMaxIterations is a wrapper around setting the MaxIterations and then returning the Backoff object to use in chained creation

func (*Backoff) WithMaxTotalTime

func (b *Backoff) WithMaxTotalTime(v time.Duration) *Backoff

WithMaxTotalTime is a wrapper around setting the MaxTotalTime and then returning the Backoff object to use in chained creation

func (*Backoff) WithMinIterationTime

func (b *Backoff) WithMinIterationTime(v time.Duration) *Backoff

WithMinIterationTime is a wrapper around setting the MinIterationTime and then returning the Backoff object to use in chained creation

func (*Backoff) WithMultiplier

func (b *Backoff) WithMultiplier(v float64) *Backoff

WithMultiplier is a wrapper around setting the Multiplier and then returning the Backoff object to use in chained creation

type ErrCannotRetry

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

ErrCannotRetry wraps the original error and signals the backoff should be stopped now as a retry i.e. would be harmful or would make no sense

func (ErrCannotRetry) Error

func (e ErrCannotRetry) Error() string

func (ErrCannotRetry) Unwrap

func (e ErrCannotRetry) Unwrap() error

type Retryable

type Retryable func() error

Retryable is a function which takes no parameters and yields an error when it should be retried and nil when it was successful