driver

Documentation

Overview

Package driver holds the two periodic-scan loop shapes, plus the timer and backoff primitives a wake-driven loop builds its own shape from. In both scan shapes a non-positive interval means the driver is off; a wake-driven loop says that some other way, since its intervals are floors rather than cadences.

Index

• func Rearm(t *time.Timer, d time.Duration)
• func Run(ctx context.Context, every time.Duration, step func(context.Context) bool)
• func TickerChan(d time.Duration) (<-chan time.Time, func())
• type Backoff
  • func (b *Backoff) Next() time.Duration
  • func (b *Backoff) Reset()
  • func (b *Backoff) Wait(ctx context.Context) bool

Functions

func Rearm

func Rearm(t *time.Timer, d time.Duration)

Rearm resets t to fire d from now, for a wake-driven loop that re-arms one timer after every pass. Safe on a timer that is still running, one that has fired, and one whose value was never received: since Go 1.23 the timer channel is unbuffered, so Reset cannot leave a stale value behind.

func Run

func Run(ctx context.Context, every time.Duration, step func(context.Context) bool)

Run runs step once eagerly, then on every tick, until ctx is cancelled or step returns false. A non-positive interval turns the driver off, first pass included.

func TickerChan

func TickerChan(d time.Duration) (<-chan time.Time, func())

TickerChan returns a driver's tick channel and its stop func, for a loop that selects over several intervals at once. A non-positive interval returns a nil channel, which blocks forever in a select.

Types

type Backoff

type Backoff struct {
	Base time.Duration
	Max  time.Duration
	// contains filtered or unexported fields
}

Backoff is the retry delay a wake-driven driver uses when a step fails: it doubles from Base and is capped at Max. A non-positive Max means no ceiling to grow toward, so the delay stays at Base rather than collapsing to zero. The zero value is unusable — Base must be positive.

func (*Backoff) Next

func (b *Backoff) Next() time.Duration

Next returns the next delay and doubles it for the call after, saturating at Max.

It saturates rather than doubling past Max because the doubling overflows: 37 doublings of a 100ms base pass time.Duration's range, and a negative cur reads as uninitialized below — which would drop a driver back to Base part way through the outage the backoff exists for.

func (*Backoff) Reset

func (b *Backoff) Reset()

Reset returns the delay to Base; call it after a step that worked.

func (*Backoff) Wait

func (b *Backoff) Wait(ctx context.Context) bool

Wait blocks for the next delay and reports whether it elapsed; false means ctx ended. It advances the delay, so a caller must Reset after a success.