The highest tagged major version is
README
¶
Retry
This library supports Go >= 1.17.
Retry calls your function, and if it errors it calls it again with a delay.
Eventually it returns the last error or nil if one call is successful.
l := &retry.Retry{
Attempts: 666,
Delay: time.Millisecond,
}
err := l.Do(func() error {
// do some work.
return nil
})
You can provide multiple functions:
err := l.Do(func() error {
return nil
}, func() error {
return nil
}}
If you want to stop retrying you can return a special error:
err := l.Do(func() error {
if specialCase {
return &retry.StopError{
Err: errors.New("a special stop"),
}
}
return nil
})
The standard behaviour is to delay the amount you set. You can pass any function with this signature to change the delay behaviour:
func(attempt int, delay time.Duration) time.Duration
You can also pass the retry.IncrementalDelay function that would increase the
delay with a jitter to prevent Thundering
herd.
l := &retry.Retry{
Attempts: 666,
Delay: 10 * time.Millisecond,
Method: retry.IncrementalDelay,
}
err := l.Do(func() error {
if specialCase {
return &retry.StopError{
Err: errors.New("a special stop"),
}
}
return nil
})
License
Use of this source code is governed by the Apache 2.0 license. License can be found in the LICENSE file.
Documentation
¶
Overview ¶
Package retry invokes a given function until it succeeds. It sleeps in between attempts based the DelayMethod. It is useful in situations that an action might succeed after a few attempt due to unavailable resources or waiting for a condition to happen.
The default DelayMethod sleeps exactly the same amount of time between attempts. You can use the IncrementalDelay method to increment the delays between attempts. It gives a jitter to the delay to prevent Thundering herd problems. If the delay is 0 in either case, it does not sleep between tries.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IncrementalDelay ¶
IncrementalDelay increases the delay between attempts up to a second. It adds a jitter to prevent Thundering herd. If the delay is 0, it always returns 0.
Example ¶
package main
import (
"fmt"
"time"
"github.com/arsham/retry"
"github.com/pkg/errors"
)
func main() {
// This setup will delay 20ms + 40ms + 80ms + 160ms, and a jitters at 5
// attempts, until on the 6th attempt that it would succeed.
l := &retry.Retry{
Attempts: 6,
Delay: 20 * time.Millisecond,
Method: retry.IncrementalDelay,
}
i := 0
err := l.Do(func() error {
i++
if i < l.Attempts {
return errors.New("ignored error")
}
return nil
})
fmt.Println("Error:", err)
}
Output: Error: <nil>
Types ¶
type DelayMethod ¶
DelayMethod determines how the delay behaves. The current attempt is passed on each iteration, with the delay value of the Retry object.
type Retry ¶
type Retry struct {
Method DelayMethod
Delay time.Duration
Attempts int
}
Retry attempts to call a given function until it succeeds, or returns a StopError value for a certain amount of times. It will delay between calls for any errors based on the provided Method. Retry is concurrent safe and the zero value does not do anything.
func (Retry) Do ¶
Do calls fn until it returns nil or a StopError. It delays and retries if the fn returns any errors or panics. The value fo the returned error, or the Err of a StopError, or an error with the panic message will be returned at the last cycle.
Example ¶
package main
import (
"fmt"
"github.com/arsham/retry"
)
func main() {
l := &retry.Retry{
Attempts: 4,
}
err := l.Do(func() error {
return nil
})
fmt.Println("Error:", err)
}
Output: Error: <nil>
Example (Error) ¶
package main
import (
"fmt"
"time"
"github.com/arsham/retry"
"github.com/pkg/errors"
)
func main() {
l := &retry.Retry{
Attempts: 4,
Delay: time.Nanosecond,
}
err := l.Do(func() error {
return errors.New("some error")
})
fmt.Println("Error:", err)
}
Output: Error: some error
Example (MultipleFuncs) ¶
package main
import (
"fmt"
"time"
"github.com/arsham/retry"
)
func main() {
l := &retry.Retry{
Attempts: 4,
Delay: time.Nanosecond,
}
err := l.Do(func() error {
fmt.Println("Running func 1.")
return nil
}, func() error {
fmt.Println("Running func 2.")
return nil
}, func() error {
fmt.Println("Running func 3.")
return nil
})
fmt.Println("Error:", err)
}
Output: Running func 1. Running func 2. Running func 3. Error: <nil>
Example (StandardMethod) ¶
package main
import (
"fmt"
"time"
"github.com/arsham/retry"
"github.com/pkg/errors"
)
func main() {
l := &retry.Retry{
Attempts: 4,
Delay: time.Nanosecond,
}
i := 0
err := l.Do(func() error {
i++
fmt.Printf("Running iteration %d.\n", i)
if i < 3 {
return errors.New("ignored error")
}
return nil
})
fmt.Println("Error:", err)
}
Output: Running iteration 1. Running iteration 2. Running iteration 3. Error: <nil>
Example (Zero) ¶
package main
import (
"fmt"
"github.com/arsham/retry"
)
func main() {
l := &retry.Retry{}
err := l.Do(func() error {
fmt.Println("this should not happen")
return nil
})
fmt.Println("Error:", err)
}
Output: Error: <nil>
type StopError ¶
type StopError struct {
Err error
}
StopError causes the Do method stop trying and will return the Err. This error then is returned by the Do method.
Example ¶
package main
import (
"fmt"
"github.com/arsham/retry"
"github.com/pkg/errors"
)
func main() {
l := &retry.Retry{
Attempts: 10,
}
i := 0
err := l.Do(func() error {
i++
fmt.Printf("Running iteration %d.\n", i)
if i > 2 {
return retry.StopError{}
}
return errors.New("ignored error")
})
fmt.Println("Error:", err)
}
Output: Running iteration 1. Running iteration 2. Running iteration 3. Error: <nil>
Example (StopErr) ¶
package main
import (
"fmt"
"github.com/arsham/retry"
"github.com/pkg/errors"
)
func main() {
l := &retry.Retry{
Attempts: 10,
}
i := 0
stopErr := &retry.StopError{
Err: errors.New("this is the returned error"),
}
err := l.Do(func() error {
i++
if i > 2 {
return stopErr
}
return errors.New("ignored error")
})
fmt.Println("Error:", err)
fmt.Println("Stopped with:", stopErr)
}
Output: Error: this is the returned error Stopped with: this is the returned error
Source Files