backoff

README

Backoff

A simple exponential backoff counter in Go (Golang)

Install

$ go get -v github.com/jpillora/backoff

Usage

Backoff is a time.Duration counter. It starts at Min. After every call to Duration() it is multiplied by Factor. It is capped at Max. It returns to Min on every call to Reset(). Jitter adds randomness (see below). Used in conjunction with the time package.

---

Simple example

b := &backoff.Backoff{
	//These are the defaults
	Min:    100 * time.Millisecond,
	Max:    10 * time.Second,
	Factor: 2,
	Jitter: false,
}

fmt.Printf("%s\n", b.Duration())
fmt.Printf("%s\n", b.Duration())
fmt.Printf("%s\n", b.Duration())

fmt.Printf("Reset!\n")
b.Reset()

fmt.Printf("%s\n", b.Duration())

100ms
200ms
400ms
Reset!
100ms

---

Example using net package

b := &backoff.Backoff{
    Max:    5 * time.Minute,
}

for {
	conn, err := net.Dial("tcp", "example.com:5309")
	if err != nil {
		d := b.Duration()
		fmt.Printf("%s, reconnecting in %s", err, d)
		time.Sleep(d)
		continue
	}
	//connected
	b.Reset()
	conn.Write([]byte("hello world!"))
	// ... Read ... Write ... etc
	conn.Close()
	//disconnected
}

---

Example using Jitter

Enabling Jitter adds some randomization to the backoff durations. See Amazon's writeup of performance gains using jitter. Seeding is not necessary but doing so gives repeatable results.

import "math/rand"

b := &backoff.Backoff{
	Jitter: true,
}

rand.Seed(42)

fmt.Printf("%s\n", b.Duration())
fmt.Printf("%s\n", b.Duration())
fmt.Printf("%s\n", b.Duration())

fmt.Printf("Reset!\n")
b.Reset()

fmt.Printf("%s\n", b.Duration())
fmt.Printf("%s\n", b.Duration())
fmt.Printf("%s\n", b.Duration())

100ms
106.600049ms
281.228155ms
Reset!
100ms
104.381845ms
214.957989ms

Documentation

https://godoc.org/github.com/jpillora/backoff

Credits

Forked from some JavaScript written by @tj

Documentation

Overview

Package backoff provides an exponential-backoff implementation.

Index

• type Backoff
  • func (b *Backoff) Attempt() float64
  • func (b *Backoff) Copy() *Backoff
  • func (b *Backoff) Duration() time.Duration
  • func (b *Backoff) ForAttempt(attempt float64) time.Duration
  • func (b *Backoff) Reset()

Types

type Backoff

type Backoff struct {

	// Factor is the multiplying factor for each increment step.
	//
	// Defaults to 2.
	Factor float64

	// Jitter eases contention by randomizing backoff steps.
	//
	// Defaults to false.
	Jitter bool

	// Minimum value of the counter.
	//
	// Defaults to 100 milliseconds.
	Min time.Duration

	// Maximum value of the counter.
	//
	// Defaults to 10 seconds.
	Max time.Duration
	// contains filtered or unexported fields
}

Backoff is a time.Duration counter, starting at Min. After every call to the Duration method the current timing is multiplied by Factor, but it never exceeds Max.

Backoff is not generally concurrent-safe, but the ForAttempt method can be used concurrently.

func (*Backoff) Attempt

func (b *Backoff) Attempt() float64

Attempt returns the current attempt counter value.

func (*Backoff) Copy

func (b *Backoff) Copy() *Backoff

Copy returns a backoff with equals constraints as the original

func (*Backoff) Duration

func (b *Backoff) Duration() time.Duration

Duration returns the duration for the current attempt before incrementing the attempt counter. See ForAttempt.

func (*Backoff) ForAttempt

func (b *Backoff) ForAttempt(attempt float64) time.Duration

ForAttempt returns the duration for a specific attempt. This is useful if you have a large number of independent Backoffs, but don't want use unnecessary memory storing the Backoff parameters per Backoff. The first attempt should be 0.

ForAttempt is concurrent-safe.

func (*Backoff) Reset

func (b *Backoff) Reset()

Reset restarts the current attempt counter at zero.