Documentation
¶
Overview ¶
Package retry provides functionality for controlling retries.
Exponential Backoff ¶
Backoff duration after $retryAttempt (first attempt is 0) is defined as:
backoff =
min(initialBackoff * pow(multiplier, $retryAttempt), maxBackoff == 0 ? +Inf : maxBackoff) *
(1.0 - randomizationFactor + 2 * rand(0, randomizationFactor))
Retrying Failures ¶
Example 1: Opening connection.
retry.Do(ctx, func() error {
return openConnection(&handle)
})
Retry Loops ¶
Example 1: Event pulling and dispatching.
for r := retry.Start(ctx, WithMaxBackoff(200 * time.Millisecond)); r.Next(); {
events := pull();
if len(events) > 0 {
dispatch(events)
r.Reset()
}
}
return ctx.Err()
Example 2: Retrying CAS operations.
for r := retry.Start(ctx); r.Next(); {
success, err := kv.CompareAndSwap(key, value)
switch {
case err != nil:
return err
case success:
return nil
default:
continue
}
}
return ctx.Err()
Example 3: Waiting for status.
for r := retry.Start(ctx); r.Next(); {
if serverStatus() == StatusRunning {
return true
}
}
return false
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Option ¶
type Option func(r *options)
Option configures retry strategy such as backoff duration or maximal number of attempts.
func WithInitialBackoff ¶
WithInitialBackoff sets initial backoff.
If initial backoff option is not used, then default value of 50 milliseconds is used. If initial backoff is larger than max backoff and the max backoff is nonzero, the initial backoff will be used as the max.
func WithMaxAttempts ¶
WithMaxAttempts sets upper limit on a number of attempts.
Max attempts of 0 indicates no limit.
If max attempts option is not used, then default value of 0 is used.
func WithMaxBackoff ¶
WithMaxBackoff sets upper limit on backoff duration.
Max backoff of 0 indicates no limit.
If max backoff option is not used, then default value of 2 seconds is used.
func WithMultiplier ¶
WithMultiplier sets backoff multiplier controlling how fast backoff duration grows with each retry attempt.
If multiplier option is not used, then default value of 2 is used.
func WithRandomizationFactor ¶
WithRandomizationFactor sets randomization factor.
If randomization factor option is not used, then default value of 0.15 is used.
type Retrier ¶
type Retrier interface {
// Reset the retrier to its initial state, meaning that the next call to
// Next will return immediately and subsequent calls will behave as if
// they had followed the very first attempt.
Reset()
// Next returns whether the retry loop should continue, and blocks for the
// appropriate length of time before yielding back to the caller.
//
// If a context is present, Next will eagerly return false if the context is done.
Next() bool
// CurrentAttempt returns current retry attempt.
//
// First attempt number is 0.
//
// Resetting retrier resets attempts counter.
CurrentAttempt() int
}
Retrier allows controlling a retry loop.
Note that an explict loop using a Retrier can be often replaced with simpler and less error-prone Do() function.
Source Files