README
¶
backoff
Inspired by line/armeria backoff package.
Usage
package main
import (
"github.com/linxGnu/gumble/backoff"
)
func main() {
builder := backoff.NewBackoffBuilder()
if _, err := builder.Build(); err == nil {
panic(err)
}
// build a fixed attempt backoff
// remember that base backoff is mandatory
builder = NewBackoffBuilder().BaseBackoffSpec("fixed=456")
backoff, err := builder.Build()
if err != nil || backoff == nil {
panic(err)
}
for i := 0; i < 10000; i++ {
if backoff.NextDelayMillis(i) != 456 {
t.FailNow()
}
}
// backoff with jitter
builder = NewBackoffBuilder().
BaseBackoff(fixedBackoff).
WithLimit(5).
WithJitter(0.9).
WithJitterBound(0.9, 1.2)
backoff, err = builder.Build()
if backoff.NextDelayMillis(6) < 0 {
// should stop retrying
stopRetrying()
} else {
panic("wrong backoff")
}
}
Documentation
¶
Overview ¶
Package backoff contains various backoff algorithms/strategies.
Index ¶
- Constants
- Variables
- type AttemptLimitingBackoff
- type Backoff
- type BackoffBuilder
- func (b *BackoffBuilder) BaseBackoff(base Backoff) *BackoffBuilder
- func (b *BackoffBuilder) BaseBackoffSpec(spec string) *BackoffBuilder
- func (b *BackoffBuilder) Build() (r Backoff, err error)
- func (b *BackoffBuilder) WithJitter(jitterRate float64) *BackoffBuilder
- func (b *BackoffBuilder) WithJitterBound(minJitterRate, maxJitterRate float64) *BackoffBuilder
- func (b *BackoffBuilder) WithLimit(limit int) *BackoffBuilder
- type ExponentialBackoff
- type FixedBackoff
- type JitterAddingBackoff
- type RandomBackoff
Constants ¶
const ( // DefaultDelayMillis default delay millis DefaultDelayMillis int64 = 200 // DefaultInitialDelayMillis default initial delay millis DefaultInitialDelayMillis int64 = 200 // DefaultMinDelayMillis default min delay millis DefaultMinDelayMillis int64 = 0 // DefaultMaxDelayMillis default max delay millis DefaultMaxDelayMillis int64 = 10000 // DefaultMultiplier default multiplier DefaultMultiplier float64 = 2.0 // DefaultMinJitterRate default min jitter rate DefaultMinJitterRate float64 = -0.2 // DefaultMaxJitterRate default max jitter rate DefaultMaxJitterRate float64 = 0.2 )
Variables ¶
var ( // ErrInvalidSpecFormat invalid specification format ErrInvalidSpecFormat = fmt.Errorf("Invalid format of specification") )
Functions ¶
This section is empty.
Types ¶
type AttemptLimitingBackoff ¶
type AttemptLimitingBackoff struct {
// contains filtered or unexported fields
}
AttemptLimitingBackoff a backoff which limits the number of attempts up to the specified value.
func NewAttemptLimitingBackoff ¶
func NewAttemptLimitingBackoff(delegate Backoff, limit int) (b *AttemptLimitingBackoff, err error)
NewAttemptLimitingBackoff create new AttemptLimitingBackoff
func (*AttemptLimitingBackoff) NextDelayMillis ¶
func (f *AttemptLimitingBackoff) NextDelayMillis(numAttemptsSoFar int) int64
NextDelayMillis return the number of milliseconds to wait for before attempting a retry.
type Backoff ¶
type Backoff interface {
// NextDelayMillis return the number of milliseconds to wait for before attempting a retry.
NextDelayMillis(numAttemptsSoFar int) int64
}
Backoff control back off between attempts in a single retry operation.
var NoDelayBackoff Backoff = &FixedBackoff{delayMillis: 0}
NoDelayBackoff return a Backoff that will never wait between attempts. In most cases, using Backoff without delay is very dangerous.
var NoRetry Backoff = &FixedBackoff{delayMillis: -1}
NoRetry return a Backoff indicates that no retry
type BackoffBuilder ¶
type BackoffBuilder struct {
// contains filtered or unexported fields
}
BackoffBuilder backoff builder
func NewBackoffBuilder ¶
func NewBackoffBuilder() *BackoffBuilder
NewBackoffBuilder create new backoff builder.
func (*BackoffBuilder) BaseBackoff ¶
func (b *BackoffBuilder) BaseBackoff(base Backoff) *BackoffBuilder
BaseBackoff set base backoff. Base backoff could be chaining WithJitter and WithLimit number of attempts.
func (*BackoffBuilder) BaseBackoffSpec ¶
func (b *BackoffBuilder) BaseBackoffSpec(spec string) *BackoffBuilder
BaseBackoffSpec set specification for building base backoff. Then base backoff could be chaining WithJitter and WithLimit number of attempts.
This is the format for the specification:
// "exponential=initialDelayMillis:maxDelayMillis:multiplier" is for ExponentialBackoff. // multiplier will be 2.0 if it's omitted. // initialDelayMillis will be 200 if its omitted. // maxDelayMillis will be 10000 if its omitted. // // "fixed=delayMillis" is for FixedBackoff. delayMillis will be 200 if its omitted // // "random=minDelayMillis:maxDelayMillis" is for RandomBackoff. // minDelayMillis will be 0 if its omitted. // maxDelayMillis will be 200 if its omitted.
To omit a value, just make it blank but keep separation ':'. For example: "exponential=12::3" means initialDelayMillis = 12, maxDelayMillis is default = 10000 and multiplier = 3
func (*BackoffBuilder) Build ¶
func (b *BackoffBuilder) Build() (r Backoff, err error)
Build backoff
func (*BackoffBuilder) WithJitter ¶
func (b *BackoffBuilder) WithJitter(jitterRate float64) *BackoffBuilder
WithJitter wrap a base backoff, adds a random jitter value to the original delay using full jitter strategy. ThejitterRate is used to calculate the lower and upper bound of the ultimate delay.
The lower bound will be ((1 - jitterRate) * originalDelay) and the upper bound will be ((1 + jitterRate) * originalDelay).
For example, if the delay returned by exponentialBackoff(long, long) is 1000 milliseconds and the provided jitter value is 0.3, the ultimate backoff delay will be chosen between 1000 * (1 - 0.3) and 1000 * (1 + 0.3) by randomer. The rate value should be between 0.0 and 1.0.
func (*BackoffBuilder) WithJitterBound ¶
func (b *BackoffBuilder) WithJitterBound(minJitterRate, maxJitterRate float64) *BackoffBuilder
WithJitterBound similar to WithJitter but with specific min-maxJitterRate
func (*BackoffBuilder) WithLimit ¶
func (b *BackoffBuilder) WithLimit(limit int) *BackoffBuilder
WithLimit wrap base backoff with limiting the number of attempts up to the specified value.
Default: no limit
type ExponentialBackoff ¶
type ExponentialBackoff struct {
// contains filtered or unexported fields
}
ExponentialBackoff wait an exponentially-increasing amount of time between attempts.
func NewExponentialBackoff ¶
func NewExponentialBackoff(initialDelayMillis, maxDelayMillis int64, multiplier float64) (b *ExponentialBackoff, err error)
NewExponentialBackoff create new ExponentialBackoff
func (*ExponentialBackoff) NextDelayMillis ¶
func (f *ExponentialBackoff) NextDelayMillis(numAttemptsSoFar int) (nextDelay int64)
NextDelayMillis return the number of milliseconds to wait for before attempting a retry.
type FixedBackoff ¶
type FixedBackoff struct {
// contains filtered or unexported fields
}
FixedBackoff wait a fixed delay between attempts.
func NewFixedBackoff ¶
func NewFixedBackoff(delayMillis int64) (b *FixedBackoff, err error)
NewFixedBackoff create new fixed backoff
func (*FixedBackoff) NextDelayMillis ¶
func (f *FixedBackoff) NextDelayMillis(numAttemptsSoFar int) int64
NextDelayMillis return the number of milliseconds to wait for before attempting a retry.
type JitterAddingBackoff ¶
type JitterAddingBackoff struct {
// contains filtered or unexported fields
}
JitterAddingBackoff return a Backoff that adds a random jitter value to the original delay using https://www.awsarchitectureblog.com/2015/03/backoff.html full jitter strategy.
func NewJitterAddingBackoff ¶
func NewJitterAddingBackoff(delegate Backoff, minJitterRate, maxJitterRate float64) (b *JitterAddingBackoff, err error)
NewJitterAddingBackoff create new JitterAddingBackoff
func (*JitterAddingBackoff) NextDelayMillis ¶
func (f *JitterAddingBackoff) NextDelayMillis(numAttemptsSoFar int) (nextDelay int64)
NextDelayMillis return the number of milliseconds to wait for before attempting a retry.
type RandomBackoff ¶
type RandomBackoff struct {
// contains filtered or unexported fields
}
RandomBackoff compute backoff delay which is a random value between minDelayMillis} and maxDelayMillis.
func NewRandomBackoff ¶
func NewRandomBackoff(minDelayMillis, maxDelayMillis int64) (b *RandomBackoff, err error)
NewRandomBackoff create new
func (*RandomBackoff) NextDelayMillis ¶
func (f *RandomBackoff) NextDelayMillis(numAttemptsSoFar int) int64
NextDelayMillis return the number of milliseconds to wait for before attempting a retry.
Source Files