jitterbug

README

jitterbug

Tickers with random jitter

Installation

go get -u github.com/lthibault/jitterbug

Usage

Jitterbug is used by instantiating a jitterbug.Ticker with an interval and a jitterbug.Jitter. The former specifies a baseline interval for the ticker, to which a jitter is added by the latter.

package main

import (
    "log"

    "github.com/lthibault/jitterbug"
)

func main() {
    t := jitterbug.New(
        time.Millisecond * 300,
        &jitterbug.Norm{ Stdev: time.Millisecond * 100 },
    )

    // jitterbug.Ticker behaves like time.Ticker
    for tick := <- range t.C {
        log.Println(tick)
    }
}

Jitterbug is compatible with the univariate distributions from GoNum. For example:

t := jitterbug.New(
    time.Millisecond * 300,
    &jitterbug.Univariate{
        Sampler: &distruv.Gamma{
            // Tip: cast time.Duration as float64 when using gonum's distruv
            Alpha: float64(time.Millisecond * 100),
            Beta:  float64(time.Millisecond * 200),
        }
    },
)

Compatible libraries

• GoNum, specifically the univariate distributions.
• Suture can use jitterbug for it's backoff durations.

RFC

If you find this useful please let me know: l.thibault@sentimens.com

Seriously, even if you just used it in your weekend project, I'd like to hear about it :)

Documentation

Index

• type Jitter
• type Norm
  • func (n Norm) Jitter(d time.Duration) time.Duration
• type Sampler
• type Ticker
  • func New(d time.Duration, j Jitter) (t *Ticker)
  • func (t *Ticker) Stop()
• type Uniform
  • func (u Uniform) Jitter(d time.Duration) time.Duration
• type Univariate
  • func (u Univariate) Jitter(d time.Duration) time.Duration

Types

type Jitter

type Jitter interface {
	// Jitter consumes an interval from a ticker and returns the final, jittered
	// duration.
	Jitter(time.Duration) time.Duration
}

Jitter can compute a jitter

type Norm

type Norm struct {
	Source      *rand.Rand
	Mean, Stdev time.Duration
}

Norm is a normal distribution

func (Norm) Jitter

func (n Norm) Jitter(d time.Duration) time.Duration

Jitter the duration by drawing form a normal distribution

type Sampler

type Sampler interface {
	Rand() float64
}

Sampler can sample from any univariate distribution. It is used in conjunction with the Univariate type and is compatible with GoNum: https://godoc.org/gonum.org/v1/gonum/stat/distuv.

type Ticker

type Ticker struct {
	C <-chan time.Time

	Jitter
	Interval time.Duration
	// contains filtered or unexported fields
}

Ticker behaves like time.Ticker

func New

func New(d time.Duration, j Jitter) (t *Ticker)

New Ticker with the base interval d and the jitter source j.

func (*Ticker) Stop

func (t *Ticker) Stop()

Stop the Ticker

type Uniform

type Uniform struct {
	Source *rand.Rand
	Min    time.Duration
}

Uniform distribution

func (Uniform) Jitter

func (u Uniform) Jitter(d time.Duration) time.Duration

Jitter the duration by drawing from a uniform distribution

type Univariate

type Univariate struct {
	Sampler
}

Univariate distribution

func (Univariate) Jitter

func (u Univariate) Jitter(d time.Duration) time.Duration

Jitter the duration by drawing from a univariate distribution