1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# backoff  [](https://pkg.go.dev/github.com/lestrrat-go/backoff/v2)
Idiomatic backoff for Go
This library is an implementation of backoff algorithm for retrying operations
in an idiomatic Go way. It respects `context.Context` natively, and the critical
notifications are done through *channel operations*, allowing you to write code
that is both more explicit and flexibile.
For a longer discussion, [please read this article](https://medium.com/@lestrrat/yak-shaving-with-backoff-libraries-in-go-80240f0aa30c)
# IMPORT
```go
import "github.com/lestrrat-go/backoff/v2"
```
# SYNOPSIS
```go
func ExampleExponential() {
p := backoff.Exponential(
backoff.WithMinInterval(time.Second),
backoff.WithMaxInterval(time.Minute),
backoff.WithJitterFactor(0.05),
)
flakyFunc := func(a int) (int, error) {
// silly function that only succeeds if the current call count is
// divisible by either 3 or 5 but not both
switch {
case a%15 == 0:
return 0, errors.New(`invalid`)
case a%3 == 0 || a%5 == 0:
return a, nil
}
return 0, errors.New(`invalid`)
}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
retryFunc := func(v int) (int, error) {
b := p.Start(ctx)
for backoff.Continue(b) {
x, err := flakyFunc(v)
if err == nil {
return x, nil
}
}
return 0, errors.New(`failed to get value`)
}
retryFunc(15)
}
```
# POLICIES
Policy objects describe a backoff policy, and are factories to create backoff Controller objects.
Controller objects does the actual coordination.
Create a new controller for each invocation of a backoff enabled operation.
This way the controller object is protected from concurrent access (if you have one) and can easily be discarded
## Null
A null policy means there's no backoff.
For example, if you were to support both using and not using a backoff in your code you can say
```go
var p backoff.Policy
if useBackoff {
p = backoff.Exponential(...)
} else {
p = backoff.Null()
}
c := p.Start(ctx)
for backoff.Continue(c) {
if err := doSomething(); err != nil {
continue
}
return
}
```
Instead of
```go
if useBackoff {
p := backoff.Exponential(...)
c := p.Start(ctx)
for backoff.Continue(c) {
if err := doSomething(); err != nil {
continue
}
return
}
} else {
if err := doSomething(); err != nil {
continue
}
}
```
## Constant
A constant policy implements are backoff where the intervals are always the same
## Exponential
This is the most "common" of the backoffs. Intervals between calls are spaced out such that as you keep retrying, the intervals keep increasing.
# FAQ
## I'm getting "package github.com/lestrrat-go/backoff/v2: no Go files in /go/src/github.com/lestrrat-go/backoff/v2"
You are using Go in GOPATH mode, which was the way before [Go Modules](https://blog.golang.org/using-go-modules) were introduced in Go 1.11 (Aug 2018).
GOPATH has slowly been phased out, and in Go 1.14 onwards, Go Modules pretty much Just Work.
Go 1.16 introduced more visible changes that forces users to be aware of the existance of go.mod files.
The short answer when you you get the above error is: **Migrate to using Go Modules**.
This is simple: All you need to do is to include a go.mod (and go.sum) file to your library or app.
For example, if you have previously been doing this:
```
git clone git@github.com:myusername/myawesomeproject.git
cd myawesomeproject
go get ./...
```
First include go.mod and go.sum in your repository:
```
git clone git@github.com:myusername/myawesomeproject.git
cd myawesomeproject
go mod init
go mod tidy
git add go.mod go.sum
git commit -m "Add go.mod and go.sum" -a
git push
```
Then from subsequent calls:
```
git clone git@github.com:myusername/myawesomeproject.git
cd myawesomeproject
go build # or go test, or go run, or whatever.
```
This will tell go to respect tags, and will automatically pick up the latest version of github.com/lestrrat-go/backoff
If you really can't do this, then the quick and dirty workaround is to just copy the files over to /v2 directory of this library
```
BACKOFF=github.com/lestrrat-go/backoff
go get github.com/lestrrat-go/backoff
if [[ if ! -d "$GOPATH/src/$BACKOFF/v2" ]]; then
mkdir "$GOPATH/src/$BACKOFF/v2" # just to make sure it exists
fi
cp "$GOPATH/src/$BACKOFF/*.go" "$GOPATH/src/$BACKOFF/v2"
git clone git@github.com:myusername/myawesomeproject.git
cd myawesomeproject
go get ./...
```
## Why won't you just add the files in /v2?
Because it's hard to maintain multiple sources of truth. Sorry, I don't get paid to do this.
I will not hold anything against you if you decided to fork this to your repository, and move files to your own /v2 directory.
Then, if you have a go.mod in your app, you can just do
```
go mod edit -replace github.com/lestrrat-go/backoff/v2=github.com/myusername/myawesomemfork/v2
```
Oh, wait, then you already have go.mod, so this is a non-issue.
...Yeah, just migrate to using go modules, please?
|
