Documentation ¶
Overview ¶
Package retry implements flexible retry loops, including support for channel cancellation, mocked time, and composable retry strategies including exponential backoff with jitter.
The basic usage is as follows:
for a := retry.Start(someStrategy, nil); a.Next(); { try() }
See examples for details of suggested usage.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Attempt ¶
type Attempt struct {
// contains filtered or unexported fields
}
Attempt represents a running retry attempt.
func Start ¶
Start begins a new sequence of attempts for the given strategy using the given Clock implementation for time keeping. If clk is nil, the time package will be used to keep time.
func StartWithCancel ¶
StartWithCancel is like Start except that if a value is received on stop while waiting, the attempt will be aborted.
func (*Attempt) Count ¶
Count returns the current attempt count number, starting at 1. It returns 0 if called before Next is called. When the loop has terminated, it holds the total number of retries made.
func (*Attempt) More ¶
More reports whether there are more retry attempts to be made. It does not sleep.
If More returns false, Next will return false. If More returns true, Next will return true except when the attempt has been explicitly stopped via the stop channel.
Example ¶
package main import ( "github.com/terasum/pcookiejar/retry" "time" ) func doSomething() (int, error) { return 0, nil } func shouldRetry(error) bool { return false } func doSomethingWith(int) {} func main() { // This example shows how Attempt.More can be used to help // structure an attempt loop. If the godoc example code allowed // us to make the example return an error, we would uncomment // the commented return statements. attempts := retry.Regular{ Total: 1 * time.Second, Delay: 250 * time.Millisecond, } for attempt := attempts.Start(nil); attempt.Next(); { x, err := doSomething() if shouldRetry(err) && attempt.More() { continue } if err != nil { // return err return } doSomethingWith(x) } // return ErrTimedOut return }
Output:
type Exponential ¶
type Exponential struct { // Initial holds the initial delay. Initial time.Duration // Factor holds the factor that the delay time will be multiplied // by on each iteration. If this is zero, a factor of two will be used. Factor float64 // MaxDelay holds the maximum delay between the start // of attempts. If this is zero, there is no maximum delay. MaxDelay time.Duration // Jitter specifies whether jitter should be added to the // retry interval. The algorithm used is described as "Full Jitter" // in https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ Jitter bool }
Exponential represents an exponential backoff retry strategy. To limit the number of attempts or their overall duration, wrap this in LimitCount or LimitDuration.
Example ¶
package main import ( "github.com/terasum/pcookiejar/retry" "net/http" "time" ) func main() { // This example shows a retry loop that will retry an // HTTP POST request with an exponential backoff // for up to 30s. strategy := retry.LimitTime(30*time.Second, retry.Exponential{ Initial: 10 * time.Millisecond, Factor: 1.5, }, ) for a := retry.Start(strategy, nil); a.Next(); { if reply, err := http.Post("http://example.com/form", "", nil); err == nil { reply.Body.Close() break } } }
Output:
type Regular ¶
type Regular struct { // Total specifies the total duration of the attempt. Total time.Duration // Delay specifies the interval between the start of each try // in the burst. If an try takes longer than Delay, the // next try will happen immediately. Delay time.Duration // Min holds the minimum number of retries. It overrides Total. // To limit the maximum number of retries, use LimitCount. Min int }
Regular represents a strategy that repeats at regular intervals.
type Strategy ¶
type Strategy interface { // NewTimer is called when the strategy is started - it is // called with the time that the strategy is started and returns // an object that is used to find out how long to sleep before // each retry attempt. NewTimer(now time.Time) Timer }
Strategy is implemented by types that represent a retry strategy.
Note: You probably won't need to implement a new strategy - the existing types and functions are intended to be sufficient for most purposes.
func LimitCount ¶
LimitCount limits the number of attempts that the given strategy will perform to n. Note that all strategies will allow at least one attempt.
type Timer ¶
type Timer interface { // NextSleep is called with the time that Next or More has been // called and returns the length of time to sleep before the // next retry. If no more attempts should be made it should // return false, and the returned duration will be ignored. // // Note that NextSleep is called once after each iteration has // completed, assuming the retry loop is continuing. NextSleep(now time.Time) (time.Duration, bool) }
Timer represents a source of timing events for a retry strategy.