Documentation ¶
Overview ¶
The retry package encapsulates the mechanism around retrying commands.
The simple use is to call retry.Call with a function closure.
```go
err := retry.Call(retry.CallArgs{ Func: func() error { ... }, Attempts: 5, Delay: time.Minute, })
```
The bare minimum arguments that need to be specified are: * Func - the function to call * Attempts - the number of times to try Func before giving up * Delay - how long to wait between each try that returns an error
Any error that is returned from the `Func` is considered transient. In order to identify some errors as fatal, pass in a function for the `IsFatalError` CallArgs value.
Exponential backoff is supported by passing a value > 1 for the `BackoffFactor` in the CallArgs. This is treated as a multiplier for the specified `Delay` each time through the loop. To cap the `Delay`, pass a value for the `MaxDelay`.
Index ¶
Constants ¶
const ( // UnlimitedAttempts can be used as a value for `Attempts` to clearly // show to the reader that there is no limit to the number of attempts. UnlimitedAttempts = -1 )
Variables ¶
var ( // RetryStopped is the error that is returned from the retry functions // when the stop channel has been closed. RetryStopped = errors.New("retry stopped") )
Functions ¶
func Call ¶
Call will repeatedly execute the Func until either the function returns no error, the retry count is exceeded or the stop channel is closed.
func IsAttemptsExceeded ¶
IsAttemptsExceeded returns true if the error is a AttemptsExceeded error.
func IsRetryStopped ¶
IsRetryStopped returns true if the error is RetryStopped.
Types ¶
type AttemptsExceeded ¶
type AttemptsExceeded struct {
LastError error
}
AttemptsExceeded is the error that is returned when the retry count has been hit without the function returning a nil error result. The last error returned from the function being retried is available as the LastError attribute.
func (*AttemptsExceeded) Error ¶
func (e *AttemptsExceeded) Error() string
Error provides the implementation for the error interface method.
type CallArgs ¶
type CallArgs struct { // Func is the function that will be retried if it returns an error result. Func func() error // IsFatalError is a function that, if set, will be called for every non- // nil error result from `Func`. If `IsFatalError` returns true, the error // is immediately returned breaking out from any further retries. IsFatalError func(error) bool // NotifyFunc is a function that is called if Func fails, and the attempt // number. The first time this function is called attempt is 1, the second // time, attempt is 2 and so on. NotifyFunc func(lastError error, attempt int) // Attempts specifies the number of times Func should be retried before // giving up and returning the `AttemptsExceeded` error. If a negative // value is specified, the `Call` will retry forever. Attempts int // Delay specifies how long to wait between retries. Delay time.Duration // MaxDelay specifies how longest time to wait between retries. If no // value is specified there is no maximum delay. MaxDelay time.Duration // BackoffFactor is a multiplier used on the Delay each time the function waits. // If not specified, a factor of 1 is used, which means the delay does not increase // each time through the loop. A factor of 2 would indicate that the second delay // would be twice the first, and the third twice the second, and so on. BackoffFactor float64 // Clock defaults to clock.Wall, but allows the caller to pass one in. // Primarily used for testing purposes. Clock clock.Clock // Stop is a channel that can be used to indicate that the waiting should // be interrupted. If Stop is nil, then the Call function cannot be interrupted. // If the channel is closed prior to the Call function being executed, the // Func is still attempted once. Stop <-chan struct{} }
CallArgs is a simple structure used to define the behaviour of the Call function.