README
¶
Backoff
Go package that provides a context-aware exponential backoff.
Usage
b := backoff.New(3, 2, 1*time.Second, 5*time.Second)
// Avoid generating a new context every time Next is called.
ctx := context.Background()
for b.Next(ctx) {
// Do something.
//
// break if successful, continue on failure
}
ref; example_test.go
Installation
go get github.com/matthewpi/backoff
Documentation
¶
Overview ¶
Package backoff provides a context-aware exponential backoff timer.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backoff ¶
type Backoff struct {
// MaxAttempts is the max number of attempts that can occur. If set to 0
// the number of attempts will not be limited.
MaxAttempts uint
// Factor is the factor at which Min will increase after each failed attempt.
Factor float64
// Min is the initial backoff time to wait after the first failed attempt.
Min time.Duration
// Max is the maximum time to wait before retrying.
Max time.Duration
// Timer is used for mocking in unit tests. For normal use, this should
// always be set to the result of `NewRealTimer()`, if you are creating
// a Backoff using the `New` function, this will be set by default.
Timer Timer
// contains filtered or unexported fields
}
Backoff represents an exponential backoff.
func New ¶
New returns a new Backoff instance.
Example ¶
package main
import (
"context"
"time"
"github.com/matthewpi/backoff"
)
func main() {
b := backoff.New(3, 2, 1*time.Second, 5*time.Second)
// Avoid generating a new context every time Next is called.
ctx := context.Background()
for b.Next(ctx) {
// Do something.
//
// break if successful, continue on failure
}
}
func (*Backoff) Duration ¶
Duration returns the duration to wait for the current attempt. Useful for logging when the next attempt will occur.
func (*Backoff) Next ¶
Next increments the attempt, then waits for the duration of the attempt. Once the duration has passed, Next returns true. Next will return false if the attempt will exceed the MaxAttempts limit or if the given context has been cancelled.
This function was designed to be used as follows:
for b.Next(ctx) {
// Do work, `continue` on soft-failure, `break` on success or non-retryable error.
}
type Timer ¶
type Timer interface {
// C returns the channel where the current time will be sent when the timer
// fires. Calling C before Start will return nil, if you ever find yourself
// nil-checking the result of this function, you are likely using this
// interface incorrectly.
C() <-chan time.Time
// Start starts a timer using the specified duration. If Start is being
// called for the first time it will create a new underlying timer,
// otherwise it will reset the existing timer to a new duration.
//
// If you are re-using the same timer by calling Start multiple times,
// ensure that the channel returned by Timer#C() was drained or that
// Timer#Stop() was called properly according to its documentation.
//
// Essentially always ensure that the channel was drained if a value was
// ever sent.
Start(time.Duration)
// Stop prevents the Timer from firing.
// It returns true if the call stops the timer, false if the timer has
// already expired or been stopped.
// Stop does not close the channel, to prevent a read from the channel
// succeeding incorrectly.
//
// To ensure the channel is empty after a call to Stop, check the
// return value and drain the channel.
// For example, assuming the program has not received from t.C already:
//
// if !t.Stop() {
// <-t.C()
// }
//
// This cannot be done concurrent to other receives from the Timer's
// channel or other calls to the Timer's Stop method.
Stop() bool
}
Timer is used as an abstraction to swap out the timer implementation used by Backoff. Most users will not need to implement this interface, it is used for mocking during tests.
Source Files