Documentation ¶
Overview ¶
Package backoff implments backoff algorithms for retrying operations.
Users first create an appropriate `Policy` object, and when the operation that needs retrying is about to start, they kick the actual backoff
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Continue ¶
func Continue(c Controller) bool
Continue is a convenience function to check when we can fire the next invocation of the desired backoff code
for backoff.Continue(c) { ... your code ... }
Types ¶
type CommonOption ¶ added in v2.0.6
type CommonOption interface { ExponentialOption ConstantOption }
CommonOption is an option that can be passed to any of the backoff policies.
func WithJitterFactor ¶
func WithJitterFactor(v float64) CommonOption
WithJitterFactor enables some randomness (jittering) in the computation of the backoff intervals. This value must be between 0.0 < v < 1.0. If a value outside of this range is specified, the value will be silently ignored and jittering is disabled.
This option can be passed to ExponentialPolicy or ConstantPolicy constructor
func WithRNG ¶
func WithRNG(v Random) CommonOption
WithRNG specifies the random number generator used for jittering. If not provided one will be created, but if you want a truly random jittering, make sure to provide one that you explicitly initialized
type ConstantInterval ¶
type ConstantInterval struct {
// contains filtered or unexported fields
}
func NewConstantInterval ¶
func NewConstantInterval(options ...ConstantOption) *ConstantInterval
func (*ConstantInterval) Next ¶
func (g *ConstantInterval) Next() time.Duration
type ConstantOption ¶ added in v2.0.5
type ConstantOption interface { Option // contains filtered or unexported methods }
ConstantOption is an option that is used by the Constant policy.
func WithInterval ¶
func WithInterval(v time.Duration) ConstantOption
WithInterval specifies the constant interval used in ConstantPolicy and ConstantInterval. The default value is 1 minute.
type ConstantPolicy ¶
type ConstantPolicy struct {
// contains filtered or unexported fields
}
func NewConstantPolicy ¶
func NewConstantPolicy(options ...Option) *ConstantPolicy
func (*ConstantPolicy) Start ¶
func (p *ConstantPolicy) Start(ctx context.Context) Controller
type Controller ¶
type Controller interface { Done() <-chan struct{} Next() <-chan struct{} }
type ControllerOption ¶ added in v2.0.4
type ControllerOption interface { ConstantOption ExponentialOption CommonOption // contains filtered or unexported methods }
ControllerOption is an option that may be passed to Policy objects, but are ultimately passed down to the Controller objects. (Normally you do not have to care about the distinction)
func WithMaxRetries ¶
func WithMaxRetries(v int) ControllerOption
WithMaxRetries specifies the maximum number of attempts that can be made by the backoff policies. By default each policy tries up to 10 times.
If you would like to retry forever, specify "0" and pass to the constructor of each policy.
This option can be passed to all policy constructors except for NullPolicy
type ExponentialInterval ¶
type ExponentialInterval struct {
// contains filtered or unexported fields
}
func NewExponentialInterval ¶
func NewExponentialInterval(options ...ExponentialOption) *ExponentialInterval
func (*ExponentialInterval) Next ¶
func (g *ExponentialInterval) Next() time.Duration
type ExponentialOption ¶ added in v2.0.5
type ExponentialOption interface { Option // contains filtered or unexported methods }
ExponentialOption is an option that is used by the Exponential policy.
func WithMaxInterval ¶
func WithMaxInterval(v time.Duration) ExponentialOption
WithMaxInterval specifies the maximum duration used in exponential backoff The default value is 1 minute.
func WithMinInterval ¶
func WithMinInterval(v time.Duration) ExponentialOption
WithMinInterval specifies the minimum duration used in exponential backoff. The default value is 500ms.
func WithMultiplier ¶
func WithMultiplier(v float64) ExponentialOption
WithMultiplier specifies the factor in which the backoff intervals are increased. By default this value is set to 1.5, which means that for every iteration a 50% increase in the interval for every iteration (up to the value specified by WithMaxInterval). this value must be greater than 1.0. If the value is less than equal to 1.0, the default value of 1.5 is used.
type ExponentialPolicy ¶
type ExponentialPolicy struct {
// contains filtered or unexported fields
}
func NewExponentialPolicy ¶
func NewExponentialPolicy(options ...ExponentialOption) *ExponentialPolicy
func (*ExponentialPolicy) Start ¶
func (p *ExponentialPolicy) Start(ctx context.Context) Controller
type IntervalGenerator ¶
type NullPolicy ¶
type NullPolicy struct{}
NullPolicy does not do any backoff. It allows the caller to execute the desired code once, and no more
func NewNull ¶
func NewNull() *NullPolicy
func (*NullPolicy) Start ¶
func (p *NullPolicy) Start(ctx context.Context) Controller
type Policy ¶
type Policy interface {
Start(context.Context) Controller
}
Policy is an interface for the backoff policies that this package implements. Users must create a controller object from this policy to actually do anything with it
func Constant ¶
Constant creates a new ConstantPolicy object
Example ¶
package main import ( "context" "errors" "time" backoff "github.com/lestrrat-go/backoff/v2" ) func main() { p := backoff.Constant(backoff.WithInterval(time.Second)) flakyFunc := func(a int) (int, error) { // silly function that only succeeds if the current call count is // divisible by either 3 or 5 but not both switch { case a%15 == 0: return 0, errors.New(`invalid`) case a%3 == 0 || a%5 == 0: return a, nil } return 0, errors.New(`invalid`) } ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() retryFunc := func(v int) (int, error) { b := p.Start(ctx) for backoff.Continue(b) { x, err := flakyFunc(v) if err == nil { return x, nil } } return 0, errors.New(`failed to get value`) } retryFunc(15) }
Output:
func Exponential ¶
func Exponential(options ...ExponentialOption) Policy
Constant creates a new ExponentialPolicy object
Example ¶
package main import ( "context" "errors" "time" backoff "github.com/lestrrat-go/backoff/v2" ) func main() { p := backoff.Exponential( backoff.WithMinInterval(time.Second), backoff.WithMaxInterval(time.Minute), backoff.WithJitterFactor(0.05), ) flakyFunc := func(a int) (int, error) { // silly function that only succeeds if the current call count is // divisible by either 3 or 5 but not both switch { case a%15 == 0: return 0, errors.New(`invalid`) case a%3 == 0 || a%5 == 0: return a, nil } return 0, errors.New(`invalid`) } ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() retryFunc := func(v int) (int, error) { b := p.Start(ctx) for backoff.Continue(b) { x, err := flakyFunc(v) if err == nil { return x, nil } } return 0, errors.New(`failed to get value`) } retryFunc(15) }
Output: