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