Documentation
¶
Overview ¶
Package backoff provides a set of algorithms for determining how long to wait when an operation needs to be retried.
A backoff is produced by a generator with zero or more optional rules attached to it. Rules modify the backoff by, for example, adding jitter, or capping the duration at a certain amount.
You can create a factory for producing new backoffs (starting at their initial value) using Build():
factory := Build(Linear(5 * time.Second))
You can also specify the rules to use:
factory := Build(
Linear(5 * time.Second),
MaxBound(30 * time.Second),
NonSliding,
)
Factories are thread-safe, but Backoff instances are not. Once you have a factory, call New() to get a backoff duration producer:
backoff, err := factory.New()
if err != nil { ... }
for !isOK() {
wait, err := backoff.Next()
if err != nil { ... }
time.Sleep(wait)
// Do work...
}
See also the retry package in this module that leverages this backoff package to make retrying processes easy.
Index ¶
- Variables
- type Backoff
- type DecorrelatedExponentialOption
- type DecorrelatedExponentialOptionFunc
- type DecorrelatedExponentialOptions
- type Factory
- type Generator
- type GeneratorFactory
- func Constant(step time.Duration) GeneratorFactory
- func DecorrelatedExponential(initial time.Duration, factor float64, opts ...DecorrelatedExponentialOption) GeneratorFactory
- func Exponential(initial time.Duration, factor float64) GeneratorFactory
- func Linear(step time.Duration) GeneratorFactory
- func ResetAfter(delegate *Factory, d time.Duration, opts ...ResetAfterOption) GeneratorFactory
- type JitterOption
- type JitterOptionFunc
- type JitterOptions
- type MaxAttemptsReachedError
- type ResetAfterOption
- type ResetAfterOptionFunc
- type ResetAfterOptions
- type Rule
- type RuleFactory
- func EqualJitter(opts ...JitterOption) RuleFactory
- func FullJitter(opts ...JitterOption) RuleFactory
- func Jitter(pct float64, opts ...JitterOption) RuleFactory
- func MaxAttempts(max uint64) RuleFactory
- func MaxBound(max time.Duration) RuleFactory
- func MaxRetries(max uint64) RuleFactory
- func MinBound(min time.Duration) RuleFactory
- type RuleInjector
- type Rules
Constants ¶
This section is empty.
Variables ¶
var Immediate = Constant(0)
Immediate is a generator factory for no backoff. It is equivalent to Constant(0).
Functions ¶
This section is empty.
Types ¶
type Backoff ¶
type Backoff struct {
// contains filtered or unexported fields
}
Backoff is a combination of a generator of backoff durations and zero or more rules that adjust the generated duration amounts.
Methods of this struct are not safe to use across Goroutines, although they may safely guard work done in other Goroutines.
func Once ¶
func Once(gf GeneratorFactory, rfs ...RuleFactory) (*Backoff, error)
Once creates a one-time-use backoff using the given generator factory and rule factories.
type DecorrelatedExponentialOption ¶
type DecorrelatedExponentialOption interface {
// option to the given decorrelated exponential options.
ApplyToDecorrelatedExponentialOptions(target *DecorrelatedExponentialOptions)
}
DecorrelatedExponentialOption is a setter for one or more decorrelated exponential options.
func DecorrelatedExponentialWithRandFactory ¶
func DecorrelatedExponentialWithRandFactory(rf rand.Factory) DecorrelatedExponentialOption
DecorrelatedExponentialWithRandFactory returns a decorrelated exponential option that sets the random number generator source for a decorrelated exponential factory instance.
type DecorrelatedExponentialOptionFunc ¶
type DecorrelatedExponentialOptionFunc func(target *DecorrelatedExponentialOptions)
DecorrelatedExponentialOptionFunc allows a function to be used as a decorrelated exponential option.
func (DecorrelatedExponentialOptionFunc) ApplyToDecorrelatedExponentialOptions ¶
func (deof DecorrelatedExponentialOptionFunc) ApplyToDecorrelatedExponentialOptions(target *DecorrelatedExponentialOptions)
ApplyToDecorrelatedExponentialOptions copies the configuration of this option to the given decorrelated exponential options.
type DecorrelatedExponentialOptions ¶
type DecorrelatedExponentialOptions struct {
}
DecorrelatedExponentialOptions allow for customization of the underlying decorrelated exponential algorithm.
func (*DecorrelatedExponentialOptions) ApplyOptions ¶
func (o *DecorrelatedExponentialOptions) ApplyOptions(opts []DecorrelatedExponentialOption)
ApplyOptions runs each of the given options against this decorrelated exponential options struct.
type Factory ¶
type Factory struct {
// contains filtered or unexported fields
}
Factory is a Goroutine-safe factory for creating backoff instances.
func Build ¶
func Build(gf GeneratorFactory, rfs ...RuleFactory) *Factory
Build creates a Goroutine-safe factory for backoffs from a generator factory and zero or more rule factories.
type Generator ¶
type Generator interface {
// Next returns the next duration to back off by.
Next() (time.Duration, error)
}
Generator produces new durations based on a particular algorithm.
type GeneratorFactory ¶
type GeneratorFactory interface {
// New creates a generator with this factory's configuration.
New() (Generator, error)
}
GeneratorFactory provides a Goroutine-safe factory for creating generators of a particular algorithm.
func Constant ¶
func Constant(step time.Duration) GeneratorFactory
Constant creates a generator factory that uses the same given step duration for each successive backoff.
func DecorrelatedExponential ¶
func DecorrelatedExponential(initial time.Duration, factor float64, opts ...DecorrelatedExponentialOption) GeneratorFactory
DecorrelatedExponential creates a generator factory for a specialized type of exponential backoff algorithm that applies a random jitter to the factor instead of to the value produced.
func Exponential ¶
func Exponential(initial time.Duration, factor float64) GeneratorFactory
Exponential creates a generator factory for backoffs that start at the given initial duration and increase multiplicatively by the specified factor.
func Linear ¶
func Linear(step time.Duration) GeneratorFactory
Linear creates a generator factory that uses the specified step value to use to increase the backoff amount each time.
func ResetAfter ¶
func ResetAfter(delegate *Factory, d time.Duration, opts ...ResetAfterOption) GeneratorFactory
ResetAfter creates a generator factory that replaces a delegate backoff factory with a fresh instance (i.e., resets its internal state) after a certain amount of time has elapsed between calls to Next().
type JitterOption ¶
type JitterOption interface {
// ApplyToJitterOptions copies the configuration of this option to the given
// jitter options.
ApplyToJitterOptions(target *JitterOptions)
}
JitterOption is a setter for one or more jitter options.
func JitterWithRandFactory ¶
func JitterWithRandFactory(rf rand.Factory) JitterOption
JitterWithRandFactory returns a jitter option that sets the random number generator source for a jitter factory instance.
type JitterOptionFunc ¶
type JitterOptionFunc func(target *JitterOptions)
JitterOptionFunc allows a function to be used as a jitter option.
func (JitterOptionFunc) ApplyToJitterOptions ¶
func (jof JitterOptionFunc) ApplyToJitterOptions(target *JitterOptions)
ApplyToJitterOptions copies the configuration of this option to the given jitter options.
type JitterOptions ¶
JitterOptions allow for customization of the underlying jitter algorithm.
func (*JitterOptions) ApplyOptions ¶
func (o *JitterOptions) ApplyOptions(opts []JitterOption)
ApplyOptions runs each of the given options against this jitter options struct.
type MaxAttemptsReachedError ¶
type MaxAttemptsReachedError struct {
N uint64
}
MaxAttemptsReachedError is the error produced by the MaxAttempts rule when the limit has been reached.
func (*MaxAttemptsReachedError) Error ¶
func (e *MaxAttemptsReachedError) Error() string
type ResetAfterOption ¶
type ResetAfterOption interface {
// ApplyToResetAfterOptions configures the specified resetafter options for this option.
ApplyToResetAfterOptions(target *ResetAfterOptions)
}
ResetAfterOption is a setter for one or more reset-after algorithm options.
func ResetAfterWithClock ¶
func ResetAfterWithClock(c clock.PassiveClock) ResetAfterOption
ResetAfterWithClock changes the clock to the specified one.
type ResetAfterOptionFunc ¶
type ResetAfterOptionFunc func(target *ResetAfterOptions)
ResetAfterOptionFunc allows a function to be used as a reset-after algorithm option.
func (ResetAfterOptionFunc) ApplyToResetAfterOptions ¶
func (raof ResetAfterOptionFunc) ApplyToResetAfterOptions(target *ResetAfterOptions)
ApplyToResetAfterOptions configures the specified reset-after algorithm options by calling this function.
type ResetAfterOptions ¶
type ResetAfterOptions struct {
// Clock is the clock implementation used to check the elapsed duration.
Clock clock.PassiveClock
}
ResetAfterOptions allows the behavior of ResetAfter to be customized.
func (*ResetAfterOptions) ApplyOptions ¶
func (o *ResetAfterOptions) ApplyOptions(opts []ResetAfterOption)
ApplyOptions runs each of the given options against this options struct.
type Rule ¶
type Rule interface {
// ApplyBefore allows this rule to intervene before the generator produces a
// new duration.
ApplyBefore() (bool, time.Duration, error)
// ApplyAfter modifies the duration according this rule.
ApplyAfter(initial time.Duration) (time.Duration, error)
}
Rule adjusts a backoff duration by applying additional logic like jitter or bounding.
type RuleFactory ¶
RuleFactory is a Goroutine-safe factory for creating rules that apply to a particular algorithm.
var NonSliding RuleFactory = &nonSlidingRuleFactory{}
NonSliding causes the first iteration of a backoff to be zero instead of an initial backoff amount determined by the generator.
func EqualJitter ¶
func EqualJitter(opts ...JitterOption) RuleFactory
EqualJitter creates a rule factory that applies a random jitter to half of the duration.
func FullJitter ¶
func FullJitter(opts ...JitterOption) RuleFactory
FullJitter creates a rule factory that applies a random jitter to the entire duration.
func Jitter ¶
func Jitter(pct float64, opts ...JitterOption) RuleFactory
Jitter creates a rule factory that applies a random jitter to a portion of the duration. The percentage to apply jitter to should be expressed as an decimal number between 0 and 1, inclusive, where 1 means that the entire duration is subject to jitter.
func MaxAttempts ¶
func MaxAttempts(max uint64) RuleFactory
MaxAttempts creates a rule factory that limits the number of possible attempts made, producing an error every time Next() is called after that.
func MaxBound ¶
func MaxBound(max time.Duration) RuleFactory
MaxBound creates a rule factory that guarantees a duration is never more than a specified value.
func MaxRetries ¶
func MaxRetries(max uint64) RuleFactory
MaxRetries for a given maximum count is the same as calling MaxAttempts(max+1). Sometimes it's easier to think in terms of retries, though.
func MinBound ¶
func MinBound(min time.Duration) RuleFactory
MinBound creates a rule factory that guarantees a duration is never less than a specified value.
type RuleInjector ¶
type RuleInjector interface {
InjectRule(r Rule)
}
RuleInjector allows a backoff to customize rule application, for example, if it needs to use the result of the rule application as part of its algorithm.
type Rules ¶
type Rules []Rule
Rules encodes a list of rules as a single rule.
func (Rules) ApplyAfter ¶
ApplyAfter iterates through the rule set and applies each rule in order.
Source Files