retry

README

retry

retry is a package that enables retrying code.

It has:

• a simple api, only two public functions
• sane defaults
• validation logic to catch errors and optimize allocations
• a thread safe model
• support for context.Context
• 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.ExponentialBackoff, 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.ExponentialBackoff, 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 😢

retry.ItContext

retry also supports calling code that is context aware via retry.ItContext

noopFn := func(ctx context.Context) {}

// can you use the context to set a max amount time to retry for
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()

err := retry.ItContext(ctx, retry.ConstantDelay, func(ctx context.Context) (err error) {
    noopFn(ctx)
    return retry.Me
})

fmt.Printf("%v\n", err)
// Output: context deadline exceeded

For full examples with more documentation see the examples folder

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 *Backoff, fn func() error) (err error)
• func ItContext(ctx context.Context, b *Backoff, fn func(context.Context) error) (err error)
• type Backoff

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 (
	// ConstantDelay is a backoff policy that will attempt a call 5 times with 500 milliseconds between
	// subsequent calls.
	ConstantDelay = &Backoff{
		Attempts:     5,
		InitialDelay: 500 * time.Millisecond,
		Factor:       1,
	}
	// ExponentialBackoff provides a, sane, default exponential backoff policy.
	ExponentialBackoff = &Backoff{
		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 *Backoff, 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.

func ItContext

func ItContext(ctx context.Context, b *Backoff, fn func(context.Context) error) (err error)

ItContext is a the same as `It` but context aware. This methods can be used to set an overall timeout. It will also pass the provided context to the function provided. Thus, any code you call within the retry block can share the same parent context.

Types

type Backoff

type Backoff 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
	// transform that value into a number between 490 and 510 milliseconds.
	Jitter float64
	// contains filtered or unexported fields
}

Backoff 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.