linger

README

Linger

Linger is a set of timeout and retry utilities for Go.

Documentation

Overview

Package linger contains a set of utilities for dealing with common and repetitive timeout and retry logic.

Index

• Constants
• func Coalesce(values ...time.Duration) (v time.Duration, ok bool)
• func CoalesceT(values ...time.Time) (v time.Time, ok bool)
• func ContextWithTimeout(ctx context.Context, durations ...time.Duration) (context.Context, func())
• func ContextWithTimeoutX(ctx context.Context, x DurationTransform, durations ...time.Duration) (context.Context, func())
• func Divide(d time.Duration, v float64) time.Duration
• func Earliest(times ...time.Time) time.Time
• func First(p DurationPredicate, values ...time.Duration) (v time.Duration, ok bool)
• func FirstT(p TimePredicate, values ...time.Time) (v time.Time, ok bool)
• func FromContextDeadline(ctx context.Context) (d time.Duration, ok bool)
• func FromSeconds(s float64) time.Duration
• func FullJitter(d time.Duration) time.Duration
• func Identity(d time.Duration) time.Duration
• func Latest(times ...time.Time) time.Time
• func Limit(d, a, b time.Duration) time.Duration
• func LimitT(t, a, b time.Time) time.Time
• func Longest(durations ...time.Duration) time.Duration
• func Multiply(d time.Duration, v float64) time.Duration
• func MustCoalesce(values ...time.Duration) time.Duration
• func MustCoalesceT(values ...time.Time) time.Time
• func MustFirst(p DurationPredicate, values ...time.Duration) time.Duration
• func MustFirstT(p TimePredicate, values ...time.Time) time.Time
• func Negative(d time.Duration) bool
• func NonZero(d time.Duration) bool
• func NonZeroT(t time.Time) bool
• func Positive(d time.Duration) bool
• func Rand(a, b time.Duration) time.Duration
• func Shortest(durations ...time.Duration) time.Duration
• func Sleep(ctx context.Context, durations ...time.Duration) error
• func SleepUntil(ctx context.Context, times ...time.Time) error
• func SleepUntilX(ctx context.Context, x DurationTransform, times ...time.Time) error
• func SleepX(ctx context.Context, x DurationTransform, durations ...time.Duration) error
• type DurationPredicate
• type DurationTransform
  • func Coalescer(values ...time.Duration) DurationTransform
  • func Defaulter(p DurationPredicate, values ...time.Duration) DurationTransform
  • func Divider(v float64) DurationTransform
  • func Limiter(a, b time.Duration) DurationTransform
  • func Multiplier(v float64) DurationTransform
  • func ProportionalJitter(p float64) DurationTransform
• type TimePredicate

Constants

const (
	// MinDuration is the smallest duration that can be represented with the
	// time.Duration type.
	MinDuration = time.Duration(math.MinInt64)

	// MaxDuration is the largest duration that can be represented with the
	// time.Duration type.
	MaxDuration = time.Duration(math.MaxInt64)
)

Functions

func Coalesce

func Coalesce(values ...time.Duration) (v time.Duration, ok bool)

Coalesce returns the first of its arguments that is positive.

If none of the arguments are positive, v is the zero-value and ok is false.

func CoalesceT

func CoalesceT(values ...time.Time) (v time.Time, ok bool)

CoalesceT returns the first of its arguments that is non-zero.

If none of the arguments are non-zero, v is the zero-value and ok is false.

func ContextWithTimeout

func ContextWithTimeout(
	ctx context.Context,
	durations ...time.Duration,
) (context.Context, func())

ContextWithTimeout returns a context with a deadline some duration after the current time.

The timeout duration is computed by finding the first of the supplied durations that is positive. It uses a zero duration if none of the supplied durations are positive.

func ContextWithTimeoutX

func ContextWithTimeoutX(
	ctx context.Context,
	x DurationTransform,
	durations ...time.Duration,
) (context.Context, func())

ContextWithTimeoutX returns a context with a deadline some duration after the current time.

The timeout duration is computed by finding the first of the supplied durations that is positive, then applying the transform x. It uses a zero duration if none of the supplied durations are positive.

The transform can be used to apply jitter to the timeout duration, for example, by using one of the built-in jitter transforms such as FullJitter() or ProportionalJitter().

func Divide

func Divide(d time.Duration, v float64) time.Duration

Divide returns the result of dividing d by v.

func Earliest

func Earliest(times ...time.Time) time.Time

Earliest returns the earliest of the given times.

It returns the zero-value if no times are supplied.

func First

func First(p DurationPredicate, values ...time.Duration) (v time.Duration, ok bool)

First returns the first of its arguments for which the predicate function p returns true.

If the p returns false for all values, v is the zero-value and ok is false.

func FirstT

func FirstT(p TimePredicate, values ...time.Time) (v time.Time, ok bool)

FirstT returns the first of its arguments for which the predicate function p returns true.

If the p returns false for all values, v is the zero-value and ok is false.

func FromContextDeadline

func FromContextDeadline(ctx context.Context) (d time.Duration, ok bool)

FromContextDeadline returns the duration until the deadline of ctx is reached.

ok is false if ctx does not have a deadline.

func FromSeconds

func FromSeconds(s float64) time.Duration

FromSeconds returns a duration equivalent to the given number of seconds.

func FullJitter

func FullJitter(d time.Duration) time.Duration

FullJitter is a DurationTransform that applies "full jitter" to the input duration.

The output duration is a random duration between 0 and the input duration, inclusive.

func Identity

func Identity(d time.Duration) time.Duration

Identity is a DurationTransform that returns the input duration unchanged.

func Latest

func Latest(times ...time.Time) time.Time

Latest returns the latest of the given times.

It returns the zero-value if no times are supplied.

func Limit

func Limit(d, a, b time.Duration) time.Duration

Limit returns the duration d, capped between a and b, inclusive.

func LimitT

func LimitT(t, a, b time.Time) time.Time

LimitT returns the time t, capped between a and b, inclusive.

func Longest

func Longest(durations ...time.Duration) time.Duration

Longest returns the largest of the given durations.

It returns MinDuration if no durations are supplied.

func Multiply

func Multiply(d time.Duration, v float64) time.Duration

Multiply returns the result of multiplying d by v.

func MustCoalesce

func MustCoalesce(values ...time.Duration) time.Duration

MustCoalesce returns the first of its arguments that is positive.

It panics if none of the arguments are positive.

func MustCoalesceT

func MustCoalesceT(values ...time.Time) time.Time

MustCoalesceT returns the first of its arguments that is non-zero.

It panics if none of the arguments are non-zero.

func MustFirst

func MustFirst(p DurationPredicate, values ...time.Duration) time.Duration

MustFirst returns the first of its arguments for which the predicate function p returns true.

It panics if p returns false for all values.

func MustFirstT

func MustFirstT(p TimePredicate, values ...time.Time) time.Time

MustFirstT returns the first of its arguments for which the predicate function p returns true.

It panics if p returns false for all values.

func Negative

func Negative(d time.Duration) bool

Negative is a DurationPredicate that returns true if d is negative.

func NonZero

func NonZero(d time.Duration) bool

NonZero is a DurationPredicate that returns true if d is non-zero.

func NonZeroT

func NonZeroT(t time.Time) bool

NonZeroT is a TimePredicate that returns true if t is non-zero.

func Positive

func Positive(d time.Duration) bool

Positive is a DurationPredicate that returns true if d is positive.

func Rand

func Rand(a, b time.Duration) time.Duration

Rand returns a random duration between a and b, inclusive.

func Shortest

func Shortest(durations ...time.Duration) time.Duration

Shortest returns the smallest of the given durations.

It returns MaxDuration if no durations are supplied.

func Sleep

func Sleep(ctx context.Context, durations ...time.Duration) error

Sleep pauses the current goroutine until some duration has elapsed.

The sleep duration computed by finding the first of the supplied durations that is positive. It returns immediately if none of the supplied durations are positive.

It sleeps until the duration elapses or ctx is canceled, whichever is first. If ctx is canceled before the duration elapses it returns ctx.Err(), otherwise it returns nil.

func SleepUntil

func SleepUntil(ctx context.Context, times ...time.Time) error

SleepUntil pauses the current goroutine until a specific time.

The sleep duration is computed by finding the amount of time until the earliest of the supplied times. It returns immediately if the earliest of the times is in the past.

It sleeps until the time is reached or ctx is canceled, whichever is first. If ctx is canceled before the time is reached it returns ctx.Err(), otherwise it returns nil.

func SleepUntilX

func SleepUntilX(
	ctx context.Context,
	x DurationTransform,
	times ...time.Time,
) error

SleepUntilX pauses the current goroutine until a specific time.

The sleep duration is computed by finding the amount of time until the earliest of the supplied times, then applying the transform x. It returns immediately if the earliest of the times is in the past.

The transform can be used to apply jitter to the sleep duration, for example, by using one of the built-in jitter transforms such as FullJitter() or ProportionalJitter().

It sleeps until the time is reached or ctx is canceled, whichever is first. If ctx is canceled before the time is reached it returns ctx.Err(), otherwise it returns nil.

func SleepX

func SleepX(
	ctx context.Context,
	x DurationTransform,
	durations ...time.Duration,
) error

SleepX pauses the current goroutine until some duration has elapsed.

The sleep duration computed by finding the first of the supplied durations that is positive, then applying the transform x. It returns immediately if none of the supplied durations are positive.

The transform can be used to apply jitter to the sleep duration, for example, by using one of the built-in jitter transforms such as FullJitter() or ProportionalJitter().

It sleeps until the duration elapses or ctx is canceled, whichever is first. If ctx is canceled before the duration elapses it returns ctx.Err(), otherwise it returns nil.

Types

type DurationPredicate

type DurationPredicate func(time.Duration) bool

DurationPredicate is a predicate function for time.Duration values.

type DurationTransform

type DurationTransform func(time.Duration) time.Duration

DurationTransform is a function that applies some transformation to time.Duration values.

func Coalescer

func Coalescer(values ...time.Duration) DurationTransform

Coalescer returns a DurationTransform that falls back to the first positive value.

The transform input value is checked first, then each of the given values in order. It panics if none of the values are positive.

func Defaulter

func Defaulter(p DurationPredicate, values ...time.Duration) DurationTransform

Defaulter returns a DurationTransform that falls back to the first value for which the predicate function p returns true.

The transform input value is checked first, then each of the given values in order. It panics if p returns false for all values.

func Divider

func Divider(v float64) DurationTransform

Divider returns a DurationTransform that divides the input duration by v.

func Limiter

func Limiter(a, b time.Duration) DurationTransform

Limiter returns a DurationTransform that limits the input duration between a and b, inclusive.

func Multiplier

func Multiplier(v float64) DurationTransform

Multiplier returns a DurationTransform that multiplies the input duration by v.

func ProportionalJitter

func ProportionalJitter(p float64) DurationTransform

ProportionalJitter returns a DurationTransform that applies "proportional jitter" to the input duration.

The returned transform generates a random jitter amount proportional to the input duration. This jitter amount is added to the input duration to produce the output duration.

The jitter proportion is given by p. For example, a value of 0.1 adds up to 10% to the input duration. p may be negative to indicate that the jitter amount should be subtracted from the input duration.

type TimePredicate

type TimePredicate func(time.Time) bool

TimePredicate is a predicate function for time.Time values.