repeat

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 28, 2017 License: MIT Imports: 3 Imported by: 0

README

Repeat

GoDoc Build Status Go Report Status

Go implementation of different backoff strategies useful for retrying operations and heartbeating.

Examples

Backoff

Let's imagine that we need to do a REST call on remote server but it could fail with a bunch of different issues. We can repeat failed operation using exponential backoff policies.

Exponential backoff is an algorithm that uses feedback to multiplicatively decrease the rate of some process, in order to gradually find an acceptable rate.

The example below tries to repeat operation 10 times using a full jitter backoff. See algorithm details here.

    // An example operation that do some useful stuff.
    // It fails five first times.
    var last time.Time
    op := func(c int) error {
        printInfo(c, &last)
        if c < 5 {
            return repeat.HintTemporary(errors.New("can't connect to a server"))
        }
        return nil
    }

    // Repeat op on any error, with 10 retries, with a backoff.
    err := repeat.Repeat(
        // Our op with additional call counter.
        repeat.FnWithCounter(op),
        // Force the repetition to stop in case the previous operation
        // returns nil.
        repeat.StopOnSuccess(),
        // 10 retries max.
        repeat.LimitMaxTries(10),
        // Specify a delay that uses a backoff.
        repeat.WithDelay(
            repeat.FullJitterBackoff(500*time.Millisecond).Set(),
        ),
    )

The example of output:

Attempt #0, Delay 0s
Attempt #1, Delay 373.617912ms
Attempt #2, Delay 668.004225ms
Attempt #3, Delay 1.220076558s
Attempt #4, Delay 2.716156336s
Attempt #5, Delay 6.458431017s
Repetition process is finished with: <nil>
Backoff with timeout

The example below is almost the same as the previous one. It adds one important feature - possibility to cancel operation repetition using context's timeout.

    // A context with cancel.
    // Repetition will be cancelled in 3 seconds.
    ctx, cancelFunc := context.WithCancel(context.Background())
    go func() {
        time.Sleep(3 * time.Second)
        cancelFunc()
    }()

    // Repeat op on any error, with 10 retries, with a backoff.
    err := repeat.Repeat(
        ...
        // Specify a delay that uses a backoff.
        repeat.WithDelay(
            repeat.FullJitterBackoff(500*time.Millisecond).Set(),
            repeat.SetContext(ctx),
        ),
        ...
    )

The example of output:

Attempt #0, Delay 0s
Attempt #1, Delay 358.728046ms
Attempt #2, Delay 845.361787ms
Attempt #3, Delay 61.527485ms
Repetition process is finished with: context canceled
Heartbeating

Let's imagine we need to periodically report execution progress to remote server. The example below repeats the operation each second until it will be cancelled using passed context.

    // An example operation that do heartbeat.
    var last time.Time
    op := func(c int) error {
        printInfo(c, &last)
        return nil
    }

    // A context with cancel.
    // Repetition will be cancelled in 7 seconds.
    ctx, cancelFunc := context.WithCancel(context.Background())
    go func() {
        time.Sleep(7 * time.Second)
        cancelFunc()
    }()

    err := repeat.Repeat(
        // Heartbeating op.
        repeat.FnWithCounter(op),
        // Delay with fixed backoff and context.
        repeat.WithDelay(
            repeat.FixedBackoff(time.Second).Set(),
            repeat.SetContext(ctx),
        ),
    )

The example of output:

Attempt #0, Delay 0s
Attempt #1, Delay 1.001129426s
Attempt #2, Delay 1.000155727s
Attempt #3, Delay 1.001131014s
Attempt #4, Delay 1.000500428s
Attempt #5, Delay 1.0008985s
Attempt #6, Delay 1.000417057s
Repetition process is finished with: context canceled
Heartbeating with error timeout

The example below is almost the same as the previous one but it will be cancelled using special error timeout. This timeout resets each time the operations return nil.

    // An example operation that do heartbeat.
    // It fails 5 times after 3 successfull tries.
    var last time.Time
    op := func(c int) error {
        printInfo(c, &last)
        if c > 3 && c < 8 {
            return repeat.HintTemporary(errors.New("can't connect to a server"))
        }
        return nil
    }

    err := repeat.Repeat(
        // Heartbeating op.
        repeat.FnWithCounter(op),
        // Delay with fixed backoff and error timeout.
        repeat.WithDelay(
            repeat.FixedBackoff(time.Second).Set(),
            repeat.SetErrorsTimeout(3*time.Second),
        ),
    )

The example of output:

Attempt #0, Delay 0s
Attempt #1, Delay 1.001634616s
Attempt #2, Delay 1.004912408s
Attempt #3, Delay 1.001021358s
Attempt #4, Delay 1.001249459s
Attempt #5, Delay 1.004320833s
Repetition process is finished with: can't connect to a server

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Cause

func Cause(err error) error

Cause extracts the cause error from TemporaryError and StopError or return the passed one.

func ExponentialBackoffAlgorithm

func ExponentialBackoffAlgorithm(initialDelay time.Duration, maxDelay time.Duration, multiplier float64, jitter float64) func() time.Duration

ExponentialBackoffAlgorithm implements classic caped exponential backoff.

Example (initialDelay=1, maxDelay=30, Multiplier=2, Jitter=0.5): Attempt Delay ------- -------------------------- 0 1 + random [-0.5...0.5] 1 2 + random [-1...1] 2 4 + random [-2...2] 3 8 + random [-4...4] 4 16 + random [-8...8] 5 32 + random [-16...16] 6 64 + random [-32...32] = 30

func FixedBackoffAlgorithm

func FixedBackoffAlgorithm(delay time.Duration) func() time.Duration

FixedBackoffAlgorithm implements backoff with a fixed delay.

func FullJitterBackoffAlgorithm

func FullJitterBackoffAlgorithm(baseDelay time.Duration, maxDelay time.Duration) func() time.Duration

FullJitterBackoffAlgorithm implements caped exponential backoff with jitter. Algorithm is fast because it does not use floating point arithmetics.

Details: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/

Example (BaseDelay=1, maxDelay=30): Call Delay ------- ---------------- 1 random [0...1] 2 random [0...2] 3 random [0...4] 4 random [0...8] 5 random [0...16] 6 random [0...30] 7 random [0...30]

func HintStop

func HintStop(e error) error

HintStop makes a StopError.

func HintTemporary

func HintTemporary(e error) error

HintTemporary makes a TemporaryError.

func Repeat

func Repeat(ops ...Operation) error

Repeat repeat operation until one of them stops the repetition.

It is guaranteed that the first op will be called at least once.

func SetContext

func SetContext(ctx context.Context) func(*DelayOptions)

SetContext allows to set a context instead of default one.

func SetErrorsTimeout

func SetErrorsTimeout(t time.Duration) func(*DelayOptions)

SetErrorsTimeout specifies the maximum timeout for repetition in case of error. This timeout is reset each time when the repetition operation is successfully completed.

Default value is maximum time.Duration value.

Types

type DelayOptions

type DelayOptions struct {
	ErrorsTimeout time.Duration
	Backoff       func() time.Duration
	Context       context.Context
}

DelayOptions holds parameters for a heartbeat process.

type ExponentialBackoffBuilder

type ExponentialBackoffBuilder struct {
	// MaxDelay specifies maximum value of a delay calculated by the
	// algorithm.
	//
	// Default value is maximum time.Duration value.
	MaxDelay time.Duration

	// InitialDelay specifies an initial delay for the algorithm.
	//
	// Default value is equal to 1 second.
	InitialDelay time.Duration

	// Miltiplier specifies a multiplier for the last calculated
	// or specified delay.
	//
	// Default value is 2.
	Multiplier float64

	// Jitter specifies randomization factor [0..1].
	//
	// Default value is 0.
	Jitter float64
	// contains filtered or unexported fields
}

ExponentialBackoffBuilder is an option builder.

func ExponentialBackoff

func ExponentialBackoff(initialDelay time.Duration) *ExponentialBackoffBuilder

ExponentialBackoff create a builder for Delay's option.

func (*ExponentialBackoffBuilder) Set

func (s *ExponentialBackoffBuilder) Set() func(*DelayOptions)

Set creates a Delay' option.

func (*ExponentialBackoffBuilder) WithInitialDelay

WithInitialDelay allows to set InitialDelay.

InitialDelay specifies an initial delay for the algorithm.

func (*ExponentialBackoffBuilder) WithJitter

WithJitter allows to set Jitter.

Jitter specifies randomization factor [0..1].

Default value is 0.

func (*ExponentialBackoffBuilder) WithMaxDelay

WithMaxDelay allows to set MaxDelay.

MaxDelay specifies the maximum value of a delay calculated by the algorithm.

Default value is maximum time.Duration value.

func (*ExponentialBackoffBuilder) WithMultiplier

WithMultiplier allows to set Multiplier.

Miltiplier specifies a multiplier for the last calculated

Default value is 2.

type FixedBackoffBuilder

type FixedBackoffBuilder struct {
	// Delay specifyes fixed delay value.
	Delay time.Duration
}

FixedBackoffBuilder is an option builder.

func FixedBackoff

func FixedBackoff(delay time.Duration) *FixedBackoffBuilder

FixedBackoff create a builder for Delay's option.

func (*FixedBackoffBuilder) Set

func (s *FixedBackoffBuilder) Set() func(*DelayOptions)

Set creates a Delay' option.

type FullJitterBackoffBuilder

type FullJitterBackoffBuilder struct {
	// MaxDelay specifies maximum value of a delay calculated by the
	// algorithm.
	//
	// Default value is maximum time.Duration value.
	MaxDelay time.Duration

	// BaseDelay specifies base of an exponent.
	BaseDelay time.Duration
}

FullJitterBackoffBuilder is an option builder.

func FullJitterBackoff

func FullJitterBackoff(baseDelay time.Duration) *FullJitterBackoffBuilder

FullJitterBackoff create a builder for Delay's option.

func (*FullJitterBackoffBuilder) Set

func (s *FullJitterBackoffBuilder) Set() func(*DelayOptions)

Set creates a Delay' option.

func (*FullJitterBackoffBuilder) WithBaseDelay

WithBaseDelay allows to set BaseDelay.

BaseDelay specifies base of an exponent.

func (*FullJitterBackoffBuilder) WithMaxDelay

WithMaxDelay allows to set MaxDelay.

MaxDelay specifies the maximum value of a delay calculated by the algorithm.

Default value is maximum time.Duration value.

type Operation

type Operation func(error) error

Operation is the type of function for repetition.

func Compose

func Compose(ops ...Operation) Operation

Compose binds all passed operations into a single one.

func ComposeSlice

func ComposeSlice(ops []Operation) Operation

ComposeSlice binds all passed operations into a single one.

func Fn

func Fn(op func() error) Operation

Fn wraps operation with no arguments.

func FnWithCounter

func FnWithCounter(op func(int) error) Operation

FnWithCounter wraps operation with counter only.

func FnWithErrorAndCounter

func FnWithErrorAndCounter(op func(error, int) error) Operation

FnWithErrorAndCounter wraps operation and adds call counter.

func LimitMaxTries

func LimitMaxTries(max int) Operation

LimitMaxTries returns true if attempt number is less then max.

func StopOnSuccess

func StopOnSuccess() Operation

StopOnSuccess returns true in case of error is nil.

func WithDelay

func WithDelay(options ...func(hb *DelayOptions)) Operation

WithDelay constructs HeartbeatPredicate.

type StopError

type StopError struct {
	Cause error
}

StopError allows to stop repetition process without specifying a separate error.

This error never returns to the caller as is, only wrapped error.

func (*StopError) Error

func (e *StopError) Error() string

type TemporaryError

type TemporaryError struct {
	Cause error
}

TemporaryError allows not to stop repetitions process right now.

This error never returns to the caller as is, only wrapped error.

func (*TemporaryError) Error

func (e *TemporaryError) Error() string

Directories

Path Synopsis
examples
backoff command
heartbeat command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL