time2

Documentation

Overview

Package time2 provides time related functionality that can be manipulated to facilite deterministic testing.

Index

• func Now(ctx context.Context) time.Time
• func Since(ctx context.Context, t time.Time) time.Duration
• func Sleep(ctx context.Context, duration time.Duration) bool
• func WithClock(ctx context.Context, clk Clock) context.Context
• type Clock
  • func (c Clock) NewTicker(d time.Duration) Ticker
  • func (c Clock) NewTimer(d time.Duration) Timer
  • func (c Clock) Now() time.Time
  • func (c Clock) Since(t time.Time) time.Duration
  • func (c Clock) Sleep(ctx context.Context, d time.Duration) bool
• type Machine
  • func NewMachine(opts ...MachineOption) *Machine
  • func WithNewMachine(ctx context.Context, opts ...MachineOption) (context.Context, *Machine)
  • func (tm *Machine) Advance(d time.Duration)
  • func (tm *Machine) Block(ctx context.Context, minimumTimerCount int) bool
  • func (tm *Machine) BlockThenAdvance(ctx context.Context, minimumTimerCount int, d time.Duration) bool
  • func (tm *Machine) Clock() Clock
  • func (tm *Machine) Now() time.Time
  • func (tm *Machine) Since(t time.Time) time.Duration
• type MachineOption
  • func WithTimeAt(t time.Time) MachineOption
• type Ticker
  • func NewTicker(ctx context.Context, d time.Duration) Ticker
• type Timer
  • func NewTimer(ctx context.Context, d time.Duration) Timer

Functions

func Now

func Now(ctx context.Context) time.Time

Now invokes the method of the same name on the clock set on the context or the real clock when unset.

func Since

func Since(ctx context.Context, t time.Time) time.Duration

Since invokes the method of the same name on the clock set on the context or the real clock when unset.

func Sleep

func Sleep(ctx context.Context, duration time.Duration) bool

Sleep implements sleeping with cancellation using the clock set on the context or the real clock when unset.

func WithClock

func WithClock(ctx context.Context, clk Clock) context.Context

WithClock returns a context that will use the given clock.

Types

type Clock

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

Clock implements a clock. The zero value is valid and uses the real time functions.

func (Clock) NewTicker

func (c Clock) NewTicker(d time.Duration) Ticker

NewTicker provides functionality equivalent to time.NewTicker. It is safe to call on a zero value.

func (Clock) NewTimer

func (c Clock) NewTimer(d time.Duration) Timer

NewTimer provides functionality equivalent to time.NewTimer. It is safe to call on a zero value.

func (Clock) Now

func (c Clock) Now() time.Time

Now provides functionality equivalent to time.Now. It is safe to call on a zero value.

func (Clock) Since

func (c Clock) Since(t time.Time) time.Duration

Since provides functionality equivalent to time.Since. It is safe to call on a zero value.

func (Clock) Sleep

func (c Clock) Sleep(ctx context.Context, d time.Duration) bool

Sleep is a convenience function that provides functionality equivalent to time.Sleep, except that it respects context cancellation. True is returned if the timer expired or false if the context was done.

type Machine

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

Machine provides facilities to manipulate time, timers, and tickers. It is designed for use in deterministic testing of time reliant code. Since deterministism is hard to build when influencing a clock from multiple goroutines, the Machine disallows concurrent access by-design.

func NewMachine

func NewMachine(opts ...MachineOption) *Machine

NewMachine returns a new time machine configured with the given options.

func WithNewMachine

func WithNewMachine(ctx context.Context, opts ...MachineOption) (context.Context, *Machine)

WithNewMachine provides a context that uses a clock controlled by the returned time machine.

func (*Machine) Advance

func (tm *Machine) Advance(d time.Duration)

Advance advances the clock forward, triggering all expired timers/tickers tracked by the time machine. It should not be called concurrently.

func (*Machine) Block

func (tm *Machine) Block(ctx context.Context, minimumTimerCount int) bool

Block blocks execution until the scheduled timer count reaches the provided minimum. Timers are scheduled until triggered or stopped. Tickers are always scheduled until stopped. It should not be called concurrently. Returns false if the context became done while blocking.

func (*Machine) BlockThenAdvance

func (tm *Machine) BlockThenAdvance(ctx context.Context, minimumTimerCount int, d time.Duration) bool

BlockThenAdvance is a convenience method that blocks on the minimum timer count and then advances the clock, triggering any expired timers/tickers. It should not be called concurrently. Returns false if the context became done while blocking.

func (*Machine) Clock

func (tm *Machine) Clock() Clock

Clock returns a clock controlled by the time machine.

func (*Machine) Now

func (tm *Machine) Now() time.Time

Now provides functionality equivalent to time.Now according to the the time machine clock.

func (*Machine) Since

func (tm *Machine) Since(t time.Time) time.Duration

Since provides functionality equivalent to time.Since according to the the time machine clock.

type MachineOption

type MachineOption = func(*machineBackend)

MachineOption allows optional configuration of the Machine.

func WithTimeAt

func WithTimeAt(t time.Time) MachineOption

WithTimeAt uses the provided time as the current time of the time machine.

type Ticker

type Ticker interface {
	Chan() <-chan time.Time
	Reset(d time.Duration)
	Stop()
}

Ticker provides functionality equivalent to time.Ticker.

func NewTicker

func NewTicker(ctx context.Context, d time.Duration) Ticker

NewTicker invokes the method of the same name on the clock set on the context or the real clock when unset.

type Timer

type Timer interface {
	Chan() <-chan time.Time
	Reset(d time.Duration) bool
	Stop() bool
}

Timer provides functionality equivalent to time.Timer.

func NewTimer

func NewTimer(ctx context.Context, d time.Duration) Timer

NewTimer invokes the method of the same name on the clock set on the context or the real clock when unset.