README.md
1# Exponential Backoff [![GoDoc][godoc image]][godoc] [![Build Status][travis image]][travis]
2
3This is a Go port of the exponential backoff algorithm from [Google's HTTP Client Library for Java][google-http-java-client].
4
5[Exponential backoff][exponential backoff wiki]
6is an algorithm that uses feedback to multiplicatively decrease the rate of some process,
7in order to gradually find an acceptable rate.
8The retries exponentially increase and stop increasing when a certain threshold is met.
9
10## How To
11
12We define two functions, `Retry()` and `RetryNotify()`.
13They receive an `Operation` to execute, a `BackOff` algorithm,
14and an optional `Notify` error handler.
15
16The operation will be executed, and will be retried on failure with delay
17as given by the backoff algorithm. The backoff algorithm can also decide when to stop
18retrying.
19In addition, the notify error handler will be called after each failed attempt,
20except for the last time, whose error should be handled by the caller.
21
22```go
23// An Operation is executing by Retry() or RetryNotify().
24// The operation will be retried using a backoff policy if it returns an error.
25type Operation func() error
26
27// Notify is a notify-on-error function. It receives an operation error and
28// backoff delay if the operation failed (with an error).
29//
30// NOTE that if the backoff policy stated to stop retrying,
31// the notify function isn't called.
32type Notify func(error, time.Duration)
33
34func Retry(Operation, BackOff) error
35func RetryNotify(Operation, BackOff, Notify)
36```
37
38## Examples
39
40See more advanced examples in the [godoc][advanced example].
41
42### Retry
43
44Simple retry helper that uses the default exponential backoff algorithm:
45
46```go
47operation := func() error {
48 // An operation that might fail.
49 return nil // or return errors.New("some error")
50}
51
52err := Retry(operation, NewExponentialBackOff())
53if err != nil {
54 // Handle error.
55 return err
56}
57
58// Operation is successful.
59return nil
60```
61
62### Ticker
63
64```go
65operation := func() error {
66 // An operation that might fail
67 return nil // or return errors.New("some error")
68}
69
70b := NewExponentialBackOff()
71ticker := NewTicker(b)
72
73var err error
74
75// Ticks will continue to arrive when the previous operation is still running,
76// so operations that take a while to fail could run in quick succession.
77for range ticker.C {
78 if err = operation(); err != nil {
79 log.Println(err, "will retry...")
80 continue
81 }
82
83 ticker.Stop()
84 break
85}
86
87if err != nil {
88 // Operation has failed.
89 return err
90}
91
92// Operation is successful.
93return nil
94```
95
96## Getting Started
97
98```bash
99# install
100$ go get github.com/cenk/backoff
101
102# test
103$ cd $GOPATH/src/github.com/cenk/backoff
104$ go get -t ./...
105$ go test -v -cover
106```
107
108[godoc]: https://godoc.org/github.com/cenk/backoff
109[godoc image]: https://godoc.org/github.com/cenk/backoff?status.png
110[travis]: https://travis-ci.org/cenk/backoff
111[travis image]: https://travis-ci.org/cenk/backoff.png
112
113[google-http-java-client]: https://github.com/google/google-http-java-client
114[exponential backoff wiki]: http://en.wikipedia.org/wiki/Exponential_backoff
115
116[advanced example]: https://godoc.org/github.com/cenk/backoff#example_
117
