expbackoff

Documentation

Overview

Package expbackoff implements exponential backoff.

It was copied from the GPL version of Obol which was originally copied from google.golang.org/grpc.

See: - https://github.com/grpc/grpc-go/tree/master/backoff - https://github.com/ObolNetwork/charon/tree/v0.14.0/app/expbackoff

Index

• Variables
• func Backoff(config Config, retries int) time.Duration
• func New(ctx context.Context, opts ...func(*Config)) (backoff func())
• func NewWithAutoReset(ctx context.Context, opts ...func(*Config)) (backoff func())
• func NewWithReset(ctx context.Context, opts ...func(*Config)) (backoff func(), reset func())
• func Retry(ctx context.Context, fn func() error, opts ...func(*Config)) error
• func SetAfterForT(t *testing.T, fn func(d time.Duration) <-chan time.Time)
• func SetRandFloatForT(t *testing.T, fn func() float64)
• func With(c Config) func(*Config)
• func WithFastConfig() func(*Config)
• func WithPeriodicConfig(period time.Duration) func(*Config)
• func WithRetryCheck(check func(error) bool) func(config *Config)
• func WithRetryCount(n int) func(config *Config)
• type Config

Variables

var DefaultConfig = Config{
	BaseDelay:  1.0 * time.Second,
	Multiplier: 1.6,
	Jitter:     0.2,
	MaxDelay:   120 * time.Second,
	// contains filtered or unexported fields
}

DefaultConfig is a backoff configuration with the default values specified at https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md.

This should be useful for callers who want to configure backoff with non-default values only for a subset of the options.

Copied from google.golang.org/grpc@v1.48.0/backoff/backoff.go.

var FastConfig = Config{
	BaseDelay:  100 * time.Millisecond,
	Multiplier: 1.6,
	Jitter:     0.2,
	MaxDelay:   5 * time.Second,
	// contains filtered or unexported fields
}

FastConfig is a common configuration for fast backoff.

Functions

func Backoff

func Backoff(config Config, retries int) time.Duration

Backoff returns the amount of time to wait before the next retry given the number of retries. Copied from google.golang.org/grpc@v1.48.0/internal/backoff/backoff.go.

func New

func New(ctx context.Context, opts ...func(*Config)) (backoff func())

New returns a backoff function configured via functional options applied to DefaultConfig. The backoff function will exponentially sleep longer each time it is called. The backoff function returns immediately after the context is canceled.

Usage:

backoff := expbackoff.New(ctx)
for ctx.Err() == nil {
  resp, err := doThing(ctx)
  if err != nil {
    backoff()
    continue
  } else {
    return resp
  }
}

func NewWithAutoReset

func NewWithAutoReset(ctx context.Context, opts ...func(*Config)) (backoff func())

NewWithAutoReset returns a backoff function configured via functional options applied to DefaultConfig. The backoff function will exponentially sleep longer each time it is called. The backoff function is automatically reset if sufficient time has passed since the last backoff.

This "sufficient delay" is the next backoff duration, so if the next backoff duration is 1s, the backoff will reset to initial duration after 1s of not being called.

func NewWithReset

func NewWithReset(ctx context.Context, opts ...func(*Config)) (backoff func(), reset func())

NewWithReset returns a backoff and a reset function configured via functional options applied to DefaultConfig. The backoff function will exponentially sleep longer each time it is called. Calling the reset function will reset the backoff sleep duration to Config.BaseDelay. The backoff function returns immediately after the context is canceled.

Usage:

backoff, reset := expbackoff.NewWithReset(ctx)
for ctx.Err() == nil {
  resp, err := doThing(ctx)
  if err != nil {
    backoff()
    continue
  } else {
    reset()
    // Do something with the response.
  }
}

func Retry

func Retry(ctx context.Context, fn func() error, opts ...func(*Config)) error

Retry calls the provided function multiple times (default=3) with backoff until: - The function returns nil (Retry returns nil) - The context is canceled (Retry returns the context error) - The retry count is exhausted (Retry returns the last error). - The optional check function returns false (Retry returns the function error).

func SetAfterForT

func SetAfterForT(t *testing.T, fn func(d time.Duration) <-chan time.Time)

SetAfterForT sets the after internal function for testing.

func SetRandFloatForT

func SetRandFloatForT(t *testing.T, fn func() float64)

SetRandFloatForT sets the random float internal function for testing.

func With

func With(c Config) func(*Config)

With configures the backoff with the provided config.

func WithFastConfig

func WithFastConfig() func(*Config)

WithFastConfig configures the backoff with FastConfig.

func WithPeriodicConfig

func WithPeriodicConfig(period time.Duration) func(*Config)

WithPeriodicConfig configures the backoff with periodic backoff.

func WithRetryCheck

func WithRetryCheck(check func(error) bool) func(config *Config)

WithRetryCheck provides a custom error check function for retrying. Note this is only applicable for use with Retry.

func WithRetryCount

func WithRetryCount(n int) func(config *Config)

WithRetryCount sets the number of retries to n. Note this is only applicable for use with Retry.

Types

type Config

type Config struct {
	// BaseDelay is the amount of time to backoff after the first failure.
	BaseDelay time.Duration
	// Multiplier is the factor with which to multiply backoffs after a
	// failed retry. Should ideally be greater than 1.
	Multiplier float64
	// Jitter is the factor with which backoffs are randomized.
	Jitter float64
	// MaxDelay is the upper bound of backoff delay.
	MaxDelay time.Duration
	// contains filtered or unexported fields
}

Config defines the configuration options for backoff.