jitter

Documentation

Overview

Package jitter provides functionality for adding random variation (jitter) to time durations.

This package is designed to help distributed systems avoid "thundering herd" problems by desynchronizing retry attempts or periodic jobs.

The jitter implementation is "subtractive". It calculates a duration randomly chosen between [d * (1 - p), d], where p is the jitter percentage. This ensures that the returned duration never exceeds the input duration, allowing strict adherence to maximum delay limits (e.g., in backoff strategies).

Index

• type Jitter
  • func New(p float64, r Rand) *Jitter
  • func (j *Jitter) Apply(d time.Duration) time.Duration
  • func (j *Jitter) Floor(d time.Duration, f float64) time.Duration
• type Rand

Types

type Jitter

type Jitter struct {
	// contains filtered or unexported fields
}

Jitter applies subtractive random jitter to a duration.

func New

func New(p float64, r Rand) *Jitter

New creates a new Jitter instance with the given percentage p (0.0 to 1.0) and source of randomness r.

If r is nil, a default thread-safe, seeded generator is used.

func (*Jitter) Apply

func (j *Jitter) Apply(d time.Duration) time.Duration

Apply returns the duration d damped by a random amount based on the jitter percentage.

The result is guaranteed to be in the range [Floor(d), d].

func (*Jitter) Floor

func (j *Jitter) Floor(d time.Duration, f float64) time.Duration

Floor returns the minimum possible duration that Apply could return for the given input d.

This is equivalent to applying maximum jitter (factor = 1.0).

type Rand

type Rand interface {
	// Float64 generates a pseudo-random number in [0.0, 1.0).
	Float64() float64
}

Rand serves as a minimal facade over rand.Rand to ease mocking.