1// Package backoff provides an exponential-backoff implementation.
2package backoff
3
4import (
5	"math"
6	"math/rand"
7	"sync/atomic"
8	"time"
9)
10
11// Backoff is a time.Duration counter, starting at Min. After every call to
12// the Duration method the current timing is multiplied by Factor, but it
13// never exceeds Max.
14//
15// Backoff is not generally concurrent-safe, but the ForAttempt method can
16// be used concurrently.
17type Backoff struct {
18	attempt uint64
19	// Factor is the multiplying factor for each increment step
20	Factor float64
21	// Jitter eases contention by randomizing backoff steps
22	Jitter bool
23	// Min and Max are the minimum and maximum values of the counter
24	Min, Max time.Duration
25}
26
27// Duration returns the duration for the current attempt before incrementing
28// the attempt counter. See ForAttempt.
29func (b *Backoff) Duration() time.Duration {
30	d := b.ForAttempt(float64(atomic.AddUint64(&b.attempt, 1) - 1))
31	return d
32}
33
34const maxInt64 = float64(math.MaxInt64 - 512)
35
36// ForAttempt returns the duration for a specific attempt. This is useful if
37// you have a large number of independent Backoffs, but don't want use
38// unnecessary memory storing the Backoff parameters per Backoff. The first
39// attempt should be 0.
40//
41// ForAttempt is concurrent-safe.
42func (b *Backoff) ForAttempt(attempt float64) time.Duration {
43	// Zero-values are nonsensical, so we use
44	// them to apply defaults
45	min := b.Min
46	if min <= 0 {
47		min = 100 * time.Millisecond
48	}
49	max := b.Max
50	if max <= 0 {
51		max = 10 * time.Second
52	}
53	if min >= max {
54		// short-circuit
55		return max
56	}
57	factor := b.Factor
58	if factor <= 0 {
59		factor = 2
60	}
61	//calculate this duration
62	minf := float64(min)
63	durf := minf * math.Pow(factor, attempt)
64	if b.Jitter {
65		durf = rand.Float64()*(durf-minf) + minf
66	}
67	//ensure float64 wont overflow int64
68	if durf > maxInt64 {
69		return max
70	}
71	dur := time.Duration(durf)
72	//keep within bounds
73	if dur < min {
74		return min
75	}
76	if dur > max {
77		return max
78	}
79	return dur
80}
81
82// Reset restarts the current attempt counter at zero.
83func (b *Backoff) Reset() {
84	atomic.StoreUint64(&b.attempt, 0)
85}
86
87// Attempt returns the current attempt counter value.
88func (b *Backoff) Attempt() float64 {
89	return float64(atomic.LoadUint64(&b.attempt))
90}
91
92// Copy returns a backoff with equals constraints as the original
93func (b *Backoff) Copy() *Backoff {
94	return &Backoff{
95		Factor: b.Factor,
96		Jitter: b.Jitter,
97		Min:    b.Min,
98		Max:    b.Max,
99	}
100}
101