retry

Documentation

Overview

Package retry provides utilities for retrying functions.

Index

• Variables
• func BackoffNanos(retry int, jitter bool, backoffFactor float64, initialBackoff time.Duration, ...) int64
• func NonRetryableError(err error) error
• func RetryableError(err error) error
• type Configuration
  • func (c Configuration) NewOptions(scope tally.Scope) Options
  • func (c Configuration) NewRetrier(scope tally.Scope) Retrier
• type ContinueFn
• type Fn
• type Options
  • func NewOptions() Options
• type Retrier
  • func NewRetrier(opts Options) Retrier
• type RngFn

Examples

• Retrier

Variables

var (
	// ErrWhileConditionFalse is returned when the while condition to a while retry
	// method evaluates false.
	ErrWhileConditionFalse = errors.New("retry while condition evaluated to false")
)

Functions

func BackoffNanos

func BackoffNanos(
	retry int,
	jitter bool,
	backoffFactor float64,
	initialBackoff time.Duration,
	maxBackoff time.Duration,
	rngFn RngFn,
) int64

BackoffNanos calculates the backoff for a retry in nanoseconds.

func NonRetryableError

func NonRetryableError(err error) error

NonRetryableError returns a non-retryable error.

func RetryableError

func RetryableError(err error) error

RetryableError returns a retryable error.

Types

type Configuration

type Configuration struct {
	// Initial retry backoff.
	InitialBackoff time.Duration `yaml:"initialBackoff" validate:"min=0"`

	// Backoff factor for exponential backoff.
	BackoffFactor float64 `yaml:"backoffFactor" validate:"min=0"`

	// Maximum backoff time.
	MaxBackoff time.Duration `yaml:"maxBackoff" validate:"min=0"`

	// Maximum number of retry attempts.
	MaxRetries int `yaml:"maxRetries"`

	// Whether to retry forever until either the attempt succeeds,
	// or the retry condition becomes false.
	Forever *bool `yaml:"forever"`

	// Whether jittering is applied during retries.
	Jitter *bool `yaml:"jitter"`
}

Configuration configures options for retry attempts.

func (Configuration) NewOptions

func (c Configuration) NewOptions(scope tally.Scope) Options

NewOptions creates a new retry options based on the configuration.

func (Configuration) NewRetrier

func (c Configuration) NewRetrier(scope tally.Scope) Retrier

NewRetrier creates a new retrier based on the configuration.

type ContinueFn

type ContinueFn func(attempt int) bool

ContinueFn is a function that returns whether to continue attempting an operation.

type Fn

type Fn func() error

Fn is a function that can be retried.

type Options

type Options interface {
	// SetMetricsScope sets the metrics scope.
	SetMetricsScope(value tally.Scope) Options

	// MetricsScope returns the metrics scope.
	MetricsScope() tally.Scope

	// SetInitialBackoff sets the initial delay duration.
	SetInitialBackoff(value time.Duration) Options

	// InitialBackoff gets the initial delay duration.
	InitialBackoff() time.Duration

	// SetBackoffFactor sets the backoff factor multiplier when moving to next attempt.
	SetBackoffFactor(value float64) Options

	// BackoffFactor gets the backoff factor multiplier when moving to next attempt.
	BackoffFactor() float64

	// SetMaxBackoff sets the maximum backoff delay.
	SetMaxBackoff(value time.Duration) Options

	// MaxBackoff returns the maximum backoff delay.
	MaxBackoff() time.Duration

	// SetMaxRetries sets the maximum retry attempts.
	SetMaxRetries(value int) Options

	// Max gets the maximum retry attempts.
	MaxRetries() int

	// SetForever sets whether to retry forever until either the attempt succeeds,
	// or the retry condition becomes false.
	SetForever(value bool) Options

	// Forever returns whether to retry forever until either the attempt succeeds,
	// or the retry condition becomes false.
	Forever() bool

	// SetJitter sets whether to jitter between the current backoff and the next
	// backoff when moving to next attempt.
	SetJitter(value bool) Options

	// Jitter gets whether to jitter between the current backoff and the next
	// backoff when moving to next attempt.
	Jitter() bool

	// SetRngFn sets the RngFn.
	SetRngFn(value RngFn) Options

	// RngFn returns the RngFn.
	RngFn() RngFn
}

Options is a set of retry options.

func NewOptions

func NewOptions() Options

NewOptions creates new retry options.

type Retrier

type Retrier interface {
	// Options returns the options used to construct the retrier, useful
	// for changing instrumentation options, etc while preserving other options.
	Options() Options

	// Attempt will attempt to perform a function with retries.
	Attempt(fn Fn) error

	// Attempt will attempt to perform a function with retries.
	AttemptWhile(continueFn ContinueFn, fn Fn) error
}

Retrier is a executor that can retry attempts on executing methods.

Example

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/m3db/m3/src/x/retry"
)

func main() {
	var (
		opts    = retry.NewOptions()
		retrier = retry.NewRetrier(opts)
		context = context.Background()
	)

	continueFn := func(attempt int) bool {
		// Check if the context has been canceled.
		select {
		case <-context.Done():
			return false
		default:
			return true
		}
	}

	var attempts int
	fn := func() error {
		// Perform some work which may fail.

		if attempts++; attempts == 3 {
			fmt.Printf("Attempt %v succeeded", attempts)

			return nil
		}
		return errors.New("test")
	}

	if err := retrier.AttemptWhile(continueFn, fn); err != nil {
		log.Fatal(err)
	}
}

Output:

Attempt 3 succeeded

func NewRetrier

func NewRetrier(opts Options) Retrier

NewRetrier creates a new retrier.

type RngFn

type RngFn func(n int64) int64

RngFn returns a non-negative pseudo-random number in [0,n).