retry

README

retry

retry is a package that enables retrying code.

It has:

• a simple api(currently one public method)
• sane defaults
• validation logic to catch errors and optimize allocations
• a thread safe model
• a fun ergonomic syntax(at least I think soo 😆)

Installation

go get github.com/codyoss/retry

Examples

An example calling a function that does not return an error:

var result int
retry.It(retry.DefaultExponentialBackoff, func() (err error) {
    result = squareOnThirdAttempt()
    if result == 0 {
        return retry.Me
    }
    return
})
fmt.Println(result)
//Output: 9

An example calling a function that returns an error:

var result int
retry.It(retry.DefaultExponentialBackoff, func() (err error) {
    result, err = squareOnThirdAttempt()
    return
})
fmt.Println(result)
// Output: 9

An example of what happens when retries are exceeded:

// Create your own retry policy. It can be used across goroutines safely.
b := &retry.ExponentialBackoff{
    Attempts:     5,
    InitialDelay: 0 * time.Millisecond,
}
attempt := 0

// final error will be returned if retries are exceeded
err := retry.It(b, func() error {
    attempt++
    return fmt.Errorf("I failed %d times 😢", attempt)
})
fmt.Println(err)
// Output: I failed 5 times 😢

For full examples see the examples folder

TODOs

• Add one more method that supports a passed in context
• take some feedback

Disclaimer

Until this api hits v0.1.0 it might change a bit. After that I will try to keep things rather stable. After I have gotten enough feedback I will v1.0.0 and make the same promise Go does. Cheers!

Documentation

Overview

Package retry provides an simple api to retry function calls in a thread safe way.

Index

• Constants
• Variables
• func It(b *ExponentialBackoff, fn func() error) (err error)
• type ExponentialBackoff

Constants

const (
	// Forever is a shorthand for a time.Duration of one year. This value can be used as an input to ExponentialBackoff
	// for the MaxDelay field should the user not want to ever hit that limit.
	Forever = 365 * 24 * 60 * time.Minute
)

Variables

var (
	// DefaultConstantDelay is a backoff policy that will attempt a call 5 times with 500 milliseconds between
	// subsequent calls.
	DefaultConstantDelay = &ExponentialBackoff{
		Attempts:     5,
		InitialDelay: 500 * time.Millisecond,
		Factor:       1,
	}
	// DefaultExponentialBackoff provides a sane exponential backoff policy.
	DefaultExponentialBackoff = &ExponentialBackoff{
		Attempts:     5,
		InitialDelay: 500 * time.Millisecond,
		MaxDelay:     8 * time.Second,
		Factor:       2.0,
		Jitter:       0.1,
	}

	// Me is an error that can be returned in from a function. To be used in the function passed to It if no other
	// error makes sense or if you don't care to return that actual error. This is error variable is simply sugar.
	Me = errors.New("Retry me")
)

Functions

func It

func It(b *ExponentialBackoff, fn func() error) (err error)

It takes an ExponentialBackoff and a func that returns an err. If the function passed to this method returns an error it will be retired. It the number of attempts from the ExponentialBackoff is exceeded the final error the func returns will be returned.

This function makes use of closures so any variables you would like to capture should be declared outside the invocation of this method.

Types

type ExponentialBackoff

type ExponentialBackoff struct {
	// Attempts it the max number of times a function will be retried. Will always be treaded as a value >= 1.
	Attempts int
	// InitialDelay is the starting delay should the first attempt fail.
	InitialDelay time.Duration
	// MaxDelay is the max amount of time to try in between retry attempts.
	MaxDelay time.Duration
	// Factor is the amount that will be multiplied to the previous delay to calculate the next delay. This value
	// will always be treaded as a value >= 1.0. A value of 2.0 would be a standard exponential backoff.
	Factor float64
	// Jitter is a way to add a bit of randomness into your delay. Setting this value helps avoid what is known as the
	// thundering herd problem. For example if a value of .1 is set and your delay is 500 milliseconds the Jitter would
	// tranform that value into a number between 490 and 510 milliseconds.
	Jitter float64
	// contains filtered or unexported fields
}

ExponentialBackoff holds the configuration of a backoff policy. Once values are set and this backoff is used any modification to this struct will not affect behavior. Fields get frozen to un-exported variables upon first use.