backoff

Documentation

Overview

Package backoff implements backoff algorithms for retrying operations.

Use Retry function for retrying operations that may fail. If Retry does not meet your needs, you can create an own backoff Policy.

See Examples section below for usage examples.

Index

• Constants
• func Permanent(err error) error
• func Retry(p Policy, f func() error) (err error)
• type BackOff
  • func ConstantBackOff(d time.Duration) *BackOff
  • func ExponentialBackOff(initialInterval time.Duration, factor float64) *BackOff
  • func NewBackOff(policy Policy) *BackOff
  • func ZeroBackOff() *BackOff
  • func (b *BackOff) With(opts ...Option) *BackOff
• type Option
  • func Cancel(done <-chan struct{}) Option
  • func Jitter(randomFactor float64) Option
  • func MaxInterval(maxInterval time.Duration) Option
  • func MaxRetries(max int) Option
  • func Timeout(timeout time.Time) Option
• type Policy

Examples

• MaxRetries
• Retry

Constants

const Stop time.Duration = -1

Stop indicates that no more retries should be made for use in NextBackOff().

Functions

func Permanent

func Permanent(err error) error

Permanent wraps the given err in a permanent error signaling that the operation should not be retried.

func Retry

func Retry(p Policy, f func() error) (err error)

Retry calls the function f until it does not return error or the backoff policy stops. The function is guaranteed to be run at least once. If the functions returns a permanent error, the operation is not retried, and the wrapped error is returned. Retry sleeps the goroutine for the duration returned by BackOff after a failed operation returns.

Example

// An operation that may fail.
operation := func() error {
	fmt.Println("do something")
	return nil // or an error
}

err := Retry(ExponentialBackOff(100*time.Millisecond, 1.5), operation)
if err != nil {
	// Handle error.
	return
}

Output:

do something

Types

type BackOff

type BackOff struct {
	Policy
}

BackOff is a backoff policy that can be modified with options.

func ConstantBackOff

func ConstantBackOff(d time.Duration) *BackOff

ConstantBackOff returns a backoff policy that always returns the same backoff delay. This is in contrast to an exponential backoff policy, which returns a delay that grows longer as you call NextBackOff() over and over again.

func ExponentialBackOff

func ExponentialBackOff(initialInterval time.Duration, factor float64) *BackOff

ExponentialBackOff returns a backoff policy that increases the backoff period for each retry attempt using a function that grows exponentially. After each call of NextBackOff() the interval is multiplied by the provided factor starting with initialInterval.

func NewBackOff

func NewBackOff(policy Policy) *BackOff

NewBackOff wraps a backoff policy into a modifiable BackOff.

func ZeroBackOff

func ZeroBackOff() *BackOff

ZeroBackOff returns a fixed backoff policy whose backoff time is always zero, meaning that the operation is retried immediately without waiting, indefinitely.

func (*BackOff) With

func (b *BackOff) With(opts ...Option) *BackOff

With modifies the backoff policy by applying additional options.

type Option

type Option interface {
	// contains filtered or unexported methods
}

An Option configures a BackOff.

func Cancel

func Cancel(done <-chan struct{}) Option

Cancel configures a backoff policy to stop the given channel is closed.

func Jitter

func Jitter(randomFactor float64) Option

Jitter configures a backoff policy to randomly modify the duration by the given factor. The modified duration is a random value in the interval [randomFactor * duration, duration).

func MaxInterval

func MaxInterval(maxInterval time.Duration) Option

MaxInterval configures a backoff policy to not return longer intervals when NextBackOff() is called.

func MaxRetries

func MaxRetries(max int) Option

MaxRetries configures a backoff policy to return Stop if NextBackOff() has been called too many times.

Example

// An operation that may fail.
operation := func() error {
	fmt.Println("do something")
	return errTest
}

p := ConstantBackOff(100 * time.Millisecond).With(MaxRetries(2))
err := Retry(p, operation)
if err != nil {
	// Handle error.
	return
}

Output:

do something
do something
do something

func Timeout

func Timeout(timeout time.Time) Option

Timeout configures a backoff policy to stop when the current time passes the time given with timeout.

type Policy

type Policy interface {
	// NextBackOff returns the duration to wait before retrying the operation,
	// or backoff.Stop to indicate that no more retries should be made.
	NextBackOff() time.Duration

	// New creates a new instance of the policy in its initial state.
	New() Policy
}

Policy is a backoff policy for retrying an operation.