backoff

README

What is it?

go-backoff implements linear, exponential and exponential with full jitter back off algorithms.

Usage

Instantiate and use a Backoff instance for the lifetime of a go routine. Call backoff.Backoff() to put the routine to sleep for the desired amount of time. Use backoff.Reset() to reset counters back to 0.

  // Back off linearly, starting at 250ms, capping at 16 seconds
  linear = backoff.NewLinear(250*time.Millisecond, 16*time.Second)
  // Back off exponentially, starting at 5 seconds, capping at 320 seconds
  exp = backoff.NewExponential(5*time.Second, 320*time.Second)
  // Back off exponentially, starting at 1 minute, with no cap
  expt = backoff.NewExponential(time.Minute, 0)
  // Back off between 0 and exponentially, starting at 30 seconds, capping at 10 minutes
  expj = backoff.NewExponentialFullJitter(30*time.Second, 10*time.Minute)

  ...

  for {
    err := tryDoThing()
    if err != nil {
      glog.Debugf("Backing off %d second(s)", exp.NextDuration/time.Second)
      exp.Backoff()
    } else {
      exp.Reset()
      return
    }
  }

Tests

go get github.com/tools/godep
godep restore
go test

PASS
ok    github.com/diggs/go-backoff 6.319s

Documentation

Index

• type Backoff
  • func NewBackoff(strategy BackoffStrategy, start time.Duration, limit time.Duration) *Backoff
  • func NewExponential(start time.Duration, limit time.Duration) *Backoff
  • func NewExponentialFullJitter(start time.Duration, limit time.Duration) *Backoff
  • func NewLinear(start time.Duration, limit time.Duration) *Backoff
  • func (b *Backoff) Backoff()
  • func (b *Backoff) Reset()
• type BackoffStrategy

Types

type Backoff

type Backoff struct {
	// LastDuration contains the duration that was previously waited, or 0 if no backoff has occurred yet.
	LastDuration time.Duration
	// NextDuration contains the duration that will be waited on the next call to Backoff().
	NextDuration time.Duration
	// contains filtered or unexported fields
}

Backoff tracks the generic state of the configured back off strategy.

func NewBackoff

func NewBackoff(strategy BackoffStrategy, start time.Duration, limit time.Duration) *Backoff

NewBackoff creates a new Backoff using the specified BackoffStrategy, start duration and limit.

func NewExponential

func NewExponential(start time.Duration, limit time.Duration) *Backoff

NewExponential creates a new backoff using the exponential backoff algorithm.

func NewExponentialFullJitter

func NewExponentialFullJitter(start time.Duration, limit time.Duration) *Backoff

NewExponentialFullJitter creates a new backoff using the exponential with full jitter backoff algorithm.

func NewLinear

func NewLinear(start time.Duration, limit time.Duration) *Backoff

NewLinear creates a new backoff using the linear backoff algorithm.

func (*Backoff) Backoff

func (b *Backoff) Backoff()

Backoff causes the current thread/routine to sleep for NextDuration.

func (*Backoff) Reset

func (b *Backoff) Reset()

Reset sets the Backoff to its initial conditions ready to start over.

type BackoffStrategy

type BackoffStrategy interface {
	// GetBackoffDuration calculates the next time.Duration that the current thread will sleep for when backing off.
	// It receives the current backoff count, the initial backoff duration and the last back off duration.
	GetBackoffDuration(int, time.Duration, time.Duration) time.Duration
}

BackoffStrategy can be implemented to provide different backoff algorithms.