backoff

Documentation

Index

• Constants
• Variables
• func FullJitter[T ~int64 | ~int | ~int32 | ~float64 | ~float32](input T) T
• func GetBackoffForNextSchedule(cronSchedule string, scheduledTime time.Time, now time.Time) time.Duration
• func GetBackoffForNextScheduleNonNegative(cronSchedule string, scheduledTime time.Time, now time.Time) *time.Duration
• func IgnoreErrors(errorsToExclude []error) func(error) bool
• func Jitter[T ~int64 | ~int | ~int32 | ~float64 | ~float32](input T, coefficient float64) T
• func ThrottleRetry(operation Operation, policy RetryPolicy, isRetryable IsRetryable) error
• func ThrottleRetryContext(ctx context.Context, operation OperationCtx, policy RetryPolicy, ...) error
• func ValidateSchedule(cronSchedule string) error
• type Clock
• type ConcurrentRetrier
  • func NewConcurrentRetrier(retryPolicy RetryPolicy) *ConcurrentRetrier
  • func (c *ConcurrentRetrier) Failed()
  • func (c *ConcurrentRetrier) Succeeded()
  • func (c *ConcurrentRetrier) Throttle()
• type ExponentialRetryPolicy
  • func NewExponentialRetryPolicy(initialInterval time.Duration) *ExponentialRetryPolicy
  • func (p *ExponentialRetryPolicy) ComputeNextDelay(elapsedTime time.Duration, numAttempts int) time.Duration
  • func (p *ExponentialRetryPolicy) WithBackoffCoefficient(backoffCoefficient float64) *ExponentialRetryPolicy
  • func (p *ExponentialRetryPolicy) WithExpirationInterval(expirationInterval time.Duration) *ExponentialRetryPolicy
  • func (p *ExponentialRetryPolicy) WithInitialInterval(initialInterval time.Duration) *ExponentialRetryPolicy
  • func (p *ExponentialRetryPolicy) WithMaximumAttempts(maximumAttempts int) *ExponentialRetryPolicy
  • func (p *ExponentialRetryPolicy) WithMaximumInterval(maximumInterval time.Duration) *ExponentialRetryPolicy
• type IsRetryable
• type Operation
• type OperationCtx
• type Retrier
  • func NewRetrier(policy RetryPolicy, clock Clock) Retrier
• type RetryPolicy
• type TwoPhaseRetryPolicy
  • func (tp *TwoPhaseRetryPolicy) ComputeNextDelay(elapsedTime time.Duration, numAttempts int) time.Duration

Examples

• ExponentialRetryPolicy.WithMaximumInterval

Constants

const NoBackoff = time.Duration(-1)

NoBackoff is used to represent backoff when no cron backoff is needed

const (
	// NoInterval represents Maximim interval
	NoInterval = 0
)

Variables

var SystemClock = systemClock{}

SystemClock implements Clock interface that uses time.Now().UTC().

Functions

func FullJitter

func FullJitter[T ~int64 | ~int | ~int32 | ~float64 | ~float32](input T) T

FullJitter return random number from 0 to input, inclusive, exclusive

func GetBackoffForNextSchedule

func GetBackoffForNextSchedule(cronSchedule string, scheduledTime time.Time, now time.Time) time.Duration

GetBackoffForNextSchedule calculates the backoff time for the next run given a cronSchedule, current scheduled time, and now.

func GetBackoffForNextScheduleNonNegative

func GetBackoffForNextScheduleNonNegative(cronSchedule string, scheduledTime time.Time, now time.Time) *time.Duration

GetBackoffForNextScheduleNonNegative calculates the backoff time and ensures a non-negative duration.

func IgnoreErrors

func IgnoreErrors(errorsToExclude []error) func(error) bool

IgnoreErrors can be used as IsRetryable handler for Retry function to exclude certain errors from the retry list

func Jitter

func Jitter[T ~int64 | ~int | ~int32 | ~float64 | ~float32](input T, coefficient float64) T

Jitter return random number from (1-coefficient)*input to (1+coefficient)*input, inclusive, exclusive

func ThrottleRetry

func ThrottleRetry(operation Operation, policy RetryPolicy, isRetryable IsRetryable) error

ThrottleRetry is a resource aware version of Retry. Resource exhausted error will be retried using a different throttle retry policy, instead of the specified one.

func ThrottleRetryContext

func ThrottleRetryContext(
	ctx context.Context,
	operation OperationCtx,
	policy RetryPolicy,
	isRetryable IsRetryable,
) error

ThrottleRetryContext is a context and resource aware version of Retry. Context timeout/cancellation errors are never retried, regardless of IsRetryable. Resource exhausted error will be retried using a different throttle retry policy, instead of the specified one. TODO: allow customizing throttle retry policy and what kind of error are categorized as throttle error.

func ValidateSchedule

func ValidateSchedule(cronSchedule string) error

ValidateSchedule validates a cron schedule spec

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock used by ExponentialRetryPolicy implementation to get the current time. Mainly used for unit testing

type ConcurrentRetrier

type ConcurrentRetrier struct {
	sync.Mutex
	// contains filtered or unexported fields
}

ConcurrentRetrier is used for client-side throttling. It determines whether to throttle outgoing traffic in case downstream backend server rejects requests due to out-of-quota or server busy errors.

func NewConcurrentRetrier

func NewConcurrentRetrier(retryPolicy RetryPolicy) *ConcurrentRetrier

NewConcurrentRetrier returns an instance of concurrent backoff retrier.

func (*ConcurrentRetrier) Failed

func (c *ConcurrentRetrier) Failed()

Failed marks client request failed because backend is busy.

func (*ConcurrentRetrier) Succeeded

func (c *ConcurrentRetrier) Succeeded()

Succeeded marks client request succeeded.

func (*ConcurrentRetrier) Throttle

func (c *ConcurrentRetrier) Throttle()

Throttle Sleep if there were failures since the last success call.

type ExponentialRetryPolicy

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

ExponentialRetryPolicy provides the implementation for retry policy using a coefficient to compute the next delay. Formula used to compute the next delay is:

min(initialInterval * pow(backoffCoefficient, currentAttempt), maximumInterval)

func NewExponentialRetryPolicy

func NewExponentialRetryPolicy(initialInterval time.Duration) *ExponentialRetryPolicy

NewExponentialRetryPolicy returns an instance of ExponentialRetryPolicy using the provided initialInterval

func (*ExponentialRetryPolicy) ComputeNextDelay

func (p *ExponentialRetryPolicy) ComputeNextDelay(elapsedTime time.Duration, numAttempts int) time.Duration

ComputeNextDelay returns the next delay interval. This is used by Retrier to delay calling the operation again

func (*ExponentialRetryPolicy) WithBackoffCoefficient

func (p *ExponentialRetryPolicy) WithBackoffCoefficient(backoffCoefficient float64) *ExponentialRetryPolicy

WithBackoffCoefficient sets the coefficient used by ExponentialRetryPolicy to compute next delay for each retry All retries are computed using the following formula: initialInterval * math.Pow(backoffCoefficient, currentAttempt)

func (*ExponentialRetryPolicy) WithExpirationInterval

func (p *ExponentialRetryPolicy) WithExpirationInterval(expirationInterval time.Duration) *ExponentialRetryPolicy

WithExpirationInterval sets the absolute expiration interval for all retries

func (*ExponentialRetryPolicy) WithInitialInterval

func (p *ExponentialRetryPolicy) WithInitialInterval(initialInterval time.Duration) *ExponentialRetryPolicy

WithInitialInterval sets the initial interval used by ExponentialRetryPolicy for the very first retry All later retries are computed using the following formula: initialInterval * math.Pow(backoffCoefficient, currentAttempt)

func (*ExponentialRetryPolicy) WithMaximumAttempts

func (p *ExponentialRetryPolicy) WithMaximumAttempts(maximumAttempts int) *ExponentialRetryPolicy

WithMaximumAttempts sets the maximum number of retry attempts

func (*ExponentialRetryPolicy) WithMaximumInterval

func (p *ExponentialRetryPolicy) WithMaximumInterval(maximumInterval time.Duration) *ExponentialRetryPolicy

WithMaximumInterval sets the maximum interval for each retry. This does *not* cause the policy to stop retrying when the interval between retries reaches the supplied duration. That is what WithExpirationInterval does. Instead, this prevents the interval from exceeding maximumInterval.

Example

ExampleExponentialRetryPolicy_WithMaximumInterval demonstrates example delays with a backoff coefficient of 2 and a maximum interval of 10 seconds. Keep in mind that there is a random jitter in these times, so they are not exactly what you'd expect.

rand.Seed(42)
p1 := NewExponentialRetryPolicy(time.Second).
	WithBackoffCoefficient(2.0).
	WithMaximumInterval(0).
	WithMaximumAttempts(0).
	WithExpirationInterval(0)
p1copy := *p1
p2 := &p1copy
p2 = p2.WithMaximumInterval(time.Second * 10)
var e1, e2 time.Duration
fmt.Printf("%-10s| %15s| %15s\n", "Attempt", "Delay", "Capped Delay")
for attempts := 0; attempts < 10; attempts++ {
	d1 := p1.ComputeNextDelay(e1, attempts)
	d2 := p2.ComputeNextDelay(e2, attempts)
	e1 += d1
	e2 += d2
	_, _ = fmt.Printf(
		"%-10d| %14.1fs| %14.1fs\n",
		attempts,
		d1.Round(100*time.Millisecond).Seconds(),
		d2.Round(100*time.Millisecond).Seconds(),
	)
}

Output:

Attempt   |           Delay|    Capped Delay
0         |            0.0s|            0.0s
1         |            0.8s|            0.9s
2         |            1.7s|            1.6s
3         |            3.3s|            3.2s
4         |            7.2s|            7.2s
5         |           15.1s|            9.6s
6         |           26.2s|            8.8s
7         |           62.8s|            9.4s
8         |          112.8s|            9.5s
9         |          219.7s|            8.3s

type IsRetryable

type IsRetryable func(error) bool

IsRetryable handler can be used to exclude certain errors during retry

type Operation

type Operation func() error

Operation to retry

type OperationCtx

type OperationCtx func(context.Context) error

OperationCtx plays the same role as Operation but for context-aware retryable functions.

type Retrier

type Retrier interface {
	NextBackOff() time.Duration
	Reset()
}

Retrier manages the state of retry operation

func NewRetrier

func NewRetrier(policy RetryPolicy, clock Clock) Retrier

NewRetrier is used for creating a new instance of Retrier

type RetryPolicy

type RetryPolicy interface {
	ComputeNextDelay(elapsedTime time.Duration, numAttempts int) time.Duration
}

RetryPolicy is the API which needs to be implemented by various retry policy implementations

var (
	// DisabledRetryPolicy is a retry policy that never retries
	DisabledRetryPolicy RetryPolicy = &disabledRetryPolicyImpl{}
)

type TwoPhaseRetryPolicy

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

TwoPhaseRetryPolicy implements a policy that first use one policy to get next delay, and once expired use the second policy for the following retry. It can achieve fast retries in first phase then slowly retires in second phase.

func (*TwoPhaseRetryPolicy) ComputeNextDelay

func (tp *TwoPhaseRetryPolicy) ComputeNextDelay(elapsedTime time.Duration, numAttempts int) time.Duration

ComputeNextDelay returns the next delay interval.