retry

Documentation

Index

• Variables
• func Do(ctx context.Context, c Config, f func() error) error
• func ImmediatelyRetriable(err error) error
• func Retriable(err error) error
• func Sleep(ctx context.Context, duration time.Duration) error
• type Config
• type DelayFn
• type ExpConfig
  • func (ec ExpConfig) Delays() DelayFn
• type Exponential
  • func NewExpBackoff(config ExpConfig) *Exponential
  • func (b *Exponential) Backoff() time.Duration
  • func (b *Exponential) Reset()
• type FixedConfig
  • func (c FixedConfig) Delays() DelayFn
• type RetriableError
  • func (r RetriableError) Error() string
  • func (r RetriableError) Unwrap() error

Variables

var DefaultExpBackoffConfig = ExpConfig{
	Min:   10 * time.Millisecond,
	Max:   1 * time.Minute,
	Scale: 2.0,
}

DefaultExpBackoffConfig is a suggested configuration.

var Immediately = FixedConfig{}

Immediately means retry without any delays.

Functions

func Do

func Do(ctx context.Context, c Config, f func() error) error

Do executes the given function, retrying if necessary.

The given Config is used to calculate the delays before each attempt.

Wrap an error with Retriable to indicate that Do should try again.

If the function returns success, or an error that isn't wrapped, Do returns that value immediately without trying more.

A RetriableError error will be logged unless its message is exactly the same as the previous one.

func ImmediatelyRetriable

func ImmediatelyRetriable(err error) error

ImmediatelyRetriable wraps an error to tell Do that it should keep trying immediately. Returns nil if err is nil.

func Retriable

func Retriable(err error) error

Retriable wraps an error to tell Do that it should keep trying with delay. Returns nil if err is nil.

func Sleep

func Sleep(ctx context.Context, duration time.Duration) error

Sleep waits for the sooner event between two: -- closing the context, the error associated with the context returned -- the duration to elapse, nil returned If duration is 0 or negative the function returns immediately.

Types

type Config

type Config interface {
	// Delays returns a DelayFn representing the sequence of delays to use between attempts.
	// Each call to Delays returns a DelayFn representing an independent sequence.
	Delays() DelayFn
}

Config defines retry intervals.

An implementation of Config is normally stateless.

type DelayFn

type DelayFn func() (delay time.Duration, ok bool)

DelayFn is the type of function that can be called repeatedly to produce delays between attempts. A single value of DelayFn represents a single sequence of delays.

Each call returns the delay before the next attempt, and a boolean value to indicate whether the next attempt is desired. If ok is false, the caller should stop trying and ignore the returned delay value. The caller is not expected to call the function again after receiving false.

In other words, a DelayFn returns a finite or infinite sequence of delays over multiple calls. A false value of the second return value means the end of the sequence.

-- Hey delay function, should I make an attempt? -- Yes, in two seconds (2*time.Second, true). -- Hey delay function, should I make an attempt? -- Yes, in four seconds (4*time.Second, true). -- Hey delay function, should I make an attempt? -- No (0, false).

The delay function must return true as ok from the first call.

Note that the first delay returned by the function is used before the very first attempt. For this reason, in most cases, the first call should return (0, true).

type ExpConfig

type ExpConfig struct {
	Min     time.Duration
	Max     time.Duration
	Scale   float64
	Instant bool // If false, Delays() method will return 0 when first time called and backoff value otherwise.
}

ExpConfig is used to configure exponential backoff.

func (ExpConfig) Delays

func (ec ExpConfig) Delays() DelayFn

Delays implements interface Config.

type Exponential

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

Exponential contains the current state of the backoff logic.

func NewExpBackoff

func NewExpBackoff(config ExpConfig) *Exponential

NewExpBackoff creates new expBackoff.

func (*Exponential) Backoff

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

Backoff returns the duration to wait and updates the inner state.

func (*Exponential) Reset

func (b *Exponential) Reset()

Reset resets the backoff state.

type FixedConfig

type FixedConfig struct {
	// TryAfter is the delay before the first attempt
	TryAfter time.Duration

	// RetryAfter is the delay before each subsequent attempt
	RetryAfter time.Duration

	// MaxAttempts is the maximum number of attempts taken; 0 = unlimited
	MaxAttempts int
}

FixedConfig defines fixed retry intervals.

func (FixedConfig) Delays

func (c FixedConfig) Delays() DelayFn

Delays implements interface Config.

type RetriableError

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

RetriableError means the operation that caused the error should be retried.

func (RetriableError) Error

func (r RetriableError) Error() string

func (RetriableError) Unwrap

func (r RetriableError) Unwrap() error

Unwrap returns the next error in the error chain.