README
¶
Backoff
A package for Optimistic Concurrency Control
Summary
This project is an improvement of the backoff package implemented by cenkalti/backoff. This package provides support for various other backoff algorithms and exposes them in a service-like fashion for use.
Backoff Algorithms such as Exponential Backoff are all part of a branch of computer science known as “Optimistic Concurrency Control”. The focus of these algorithms is to use feedback cycles and process staggering to determine an acceptable time at which a process can successfully complete its intended goal.
Supported Algorithms:
- Exponential Backoff
- Fibonacci (TBD)
- Equal Jitter (TBD)
- Full Jitter (TBD)
- Decorr (TBD)
- Custom Backoff (TBD)
- See the AWS Blog on Exponential Backoff and Jitter for more example information on the abovealgorithms
Installation & Usage
To install backoff, use go get:
go get github.com/defaltd/backoff
Import the backoff package into your code using this template:
package main
import (
"fmt"
"backoff"
)
func SayHello() {
service := backoff.New(&backoff.Policy{
Algorithm: backoff.AlgorithmExponential,
})
service.ExecuteAction(func() error { return client.MakeAPICall("Hello World"); })
}
Contributing
Please feel free to contribute by submitting issues, fork the repository and send pull requests!
When submitting an issue, we ask that you please include a complete test function that demonstrates the issue.
Documentation
¶
Overview ¶
Package backoff is a service that implements a variety of backoff algorithms to provide Optimistic Concurrency Control. This package currently supports the following backoff algorithms:
- Exponential Backoff
Index ¶
- Constants
- type Action
- type Algorithm
- type Clock
- type ExponentialBackoff
- func (bckOff *ExponentialBackoff) ElapsedTime() time.Duration
- func (bckOff *ExponentialBackoff) ExecuteAction(op Action) error
- func (bckOff *ExponentialBackoff) ExecuteFunction(op Function) (interface{}, error)
- func (bckOff *ExponentialBackoff) NextBackOff() time.Duration
- func (bckOff *ExponentialBackoff) Reset()
- func (bckOff *ExponentialBackoff) ResetDefaults()
- func (bckOff *ExponentialBackoff) Setup(policy *Policy)
- type Function
- type Policy
- type Service
- type ServiceAPI
- type SystemClock
Constants ¶
const ( // DefaultExponentialInitialInterval is a constant defining the starting wait time per wait cycle. DefaultExponentialInitialInterval = 500 * time.Millisecond // DefaultExponentialRandFactor is a constant defining the factor by which time fluctuates per wait cycle. DefaultExponentialRandFactor = 0.5 // DefaultExponentialMultiplier is a constant defining the multiplication factor for the interval. DefaultExponentialMultiplier = 1.5 // DefaultExponentialMaxInterval is the maximum wait duration that the backoff wait interval can have per cycle. DefaultExponentialMaxInterval = 60 * time.Second // DefaultExponentialMaxElapsedTime is the maximum time that the backoff can run for before exiting. DefaultExponentialMaxElapsedTime = 15 * time.Minute // DefaultExponentialMaxRetryCount is the maximum number of tries the backoff should execute before exiting. DefaultExponentialMaxRetryCount = 0 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action func() error
An Action is a function with no inputs and requires no return data. The action will be retried using a backoff policy if it returns an error.
type Algorithm ¶
type Algorithm int
Algorithm is a custom type for defining constants that represent available backoff algorithms to choose from.
const ( // AlgorithmExponential is a constant defining the [Exponential Backoff Algorithm](https://en.wikipedia.org/wiki/Exponential_backoff) AlgorithmExponential Algorithm = iota )
type ExponentialBackoff ¶
type ExponentialBackoff struct {
Clock Clock
InitialInterval time.Duration
IntervalMultiplier float64
MaxElapsedTime time.Duration
MaxInterval time.Duration
RandFactor float64
MaxRetryCount int64
// contains filtered or unexported fields
}
ExponentialBackoff is a BackoffServiceAPI that implements the exponential backoff algorithm.
func (*ExponentialBackoff) ElapsedTime ¶
func (bckOff *ExponentialBackoff) ElapsedTime() time.Duration
ElapsedTime determines the total amount of time that the backoff execution has been running.
func (*ExponentialBackoff) ExecuteAction ¶
func (bckOff *ExponentialBackoff) ExecuteAction(op Action) error
ExecuteAction accepts an input of type Action to be executed via an exponential backoff algorithm. The execution of this function is equivalent to a fire and forget strategy.
func (*ExponentialBackoff) ExecuteFunction ¶
func (bckOff *ExponentialBackoff) ExecuteFunction(op Function) (interface{}, error)
ExecuteFunction accepts an input of type Function to be executed via an exponential backoff algorithm. After the function is called successfully, the output of the function is returned.
func (*ExponentialBackoff) NextBackOff ¶
func (bckOff *ExponentialBackoff) NextBackOff() time.Duration
NextBackOff determines the amount of time to wait before executing again. The function also updates certain properties for the next backoff cycle.
func (*ExponentialBackoff) Reset ¶
func (bckOff *ExponentialBackoff) Reset()
Reset is ran prior to executing the start of a backoff cycle in order to properly calculate for elapsed time and other variables.
func (*ExponentialBackoff) ResetDefaults ¶
func (bckOff *ExponentialBackoff) ResetDefaults()
ResetDefaults sets the properties of the backoff service to their API defaults. See constants prefixed with DefaultExponential.
func (*ExponentialBackoff) Setup ¶
func (bckOff *ExponentialBackoff) Setup(policy *Policy)
Setup accepts a Policy struct and sets the backoff execution properties with defaults for properties undeclared.
type Function ¶
type Function func() (interface{}, error)
A Function is a function with no inputs but returns some data and is retried using a backoff policy if it returns an error.
type Policy ¶
type Policy struct {
Algorithm Algorithm
IntervalMultiplier float64
MaxElapsedTime time.Duration
MaxInterval time.Duration
MaxRetryCount int64
RandomizationFactor float64
StartInterval time.Duration
}
A Policy represents the requirements for a backoff retry operation.
type Service ¶
type Service struct {
Policy
ServiceAPI
}
Service is the backoff service for retrying an operation.
type ServiceAPI ¶
type ServiceAPI interface {
Setup(policy *Policy)
ExecuteFunction(op Function) (interface{}, error)
ExecuteAction(op Action) error
NextBackOff() time.Duration
ElapsedTime() time.Duration
ResetDefaults()
Reset()
}
ServiceAPI defines the format of a backoff service. This interface may be used to help mock certain functionality.
func New ¶
func New(policy *Policy) (ServiceAPI, error)
New constructs an instance of the Backoff Service for retrying an operation.
type SystemClock ¶
type SystemClock struct{}
SystemClock is a collections of methods focused on using the default system clock
func (*SystemClock) Now ¶
func (clock *SystemClock) Now() time.Time
Now returns the exact current system time
Source Files