clocks

Documentation

Overview

Package clocks provides a mockable way to measure time and set timers. It also has a nicer timer interface than time.Timer.

Index

• type Alarm
• type Mock
  • func NewMock() *Mock
  • func (c *Mock) Advance(amount time.Duration)
  • func (c *Mock) NewAlarm() Alarm
  • func (c *Mock) Now() Time
  • func (c *Mock) SleepUntil(ctx context.Context, wake time.Time) error
• type Source
• type Time

Examples

• Mock
• Mock (Alarm)

Types

type Alarm

type Alarm interface {
	// Set schedules the alarm to beep at or shortly after the given time. Any
	// previously scheduled wakeups are lost. Set is thread-safe.
	//
	// After calling Set, the caller must use Stop to reclaim resources, even after
	// the alarm beeps.
	Set(wake Time)
	// Stop unschedules the alarm. Upon returning from Stop, the alarm will not beep
	// anymore (unless Set is subsequently called). Stop is thread-safe, and it is
	// safe to call Stop multiple times.
	Stop()
	// WaitCh returns a channel on which the caller may receive an empty value each
	// time the alarm beeps. The alarm will send on the channel up to once per call
	// to Set. The alarm will never close this channel.
	WaitCh() <-chan struct{}
}

An Alarm alerts the user when a given time is reached.

type Mock

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

Mock is a Source that does not advance on its own. It can be used to control a clock for unit tests.

Example

source := NewMock()
fmt.Printf("start: %v\n", source.Now().UnixNano())
source.Advance(time.Second)
fmt.Printf("then: %v\n", source.Now().UnixNano())

Output:

start: 0
then: 1000000000

Example (Alarm)

source := NewMock()
alarm := source.NewAlarm()
defer alarm.Stop()
alarm.Set(source.Now().Add(10 * time.Millisecond))
wait := parallel.Go(func() {
	<-alarm.WaitCh()
	fmt.Printf("Beep!\n")
})
fmt.Printf("No beep yet!\n")
source.Advance(12 * time.Millisecond)
// The mock alarm will fire really soon, but it needs some CPU time to process.
wait()

Output:

No beep yet!
Beep!

func NewMock

func NewMock() *Mock

NewMock returns a new mock clock that is initialized to the Unix epoch. Note that this is not the zero value for time.Time.

func (*Mock) Advance

func (c *Mock) Advance(amount time.Duration)

Advance moves the clock forward by the given amount. Note that this may cause alarms to beep shortly thereafter.

func (*Mock) NewAlarm

func (c *Mock) NewAlarm() Alarm

NewAlarm implements Source.NewAlarm.

func (*Mock) Now

func (c *Mock) Now() Time

Now implements Source.Now.

func (*Mock) SleepUntil

func (c *Mock) SleepUntil(ctx context.Context, wake time.Time) error

SleepUntil implements Source.SleepUntil. Note that a deadline/timeout on the context is measured in wall time, not mocked time.

type Source

type Source interface {
	// Now returns the current time.
	Now() Time
	// NewAlarm creates an alarm that won't yet fire.
	NewAlarm() Alarm
	// Sleep blocks until at least the given time or a context error, whichever
	// comes first. If the context expires, Sleep returns the context error.
	// Otherwise, it waits until Now() returns at least the given time and
	// returns nil.
	//
	// Historical note: this method used to be defined as:
	//     Sleep(context.Context, time.Duration) error
	// but this resulted in a race when using the mock clock. Consider this
	// example:
	//     now := clocks.Mock.Now()
	//     if now.Before(wake) {
	//         clocks.Mock.Sleep(ctx, wake.Sub(now))
	//     }
	// If the mock time advanced between the Now() and the Sleep(), the code
	// would still wait for the mock time to advance again. Switching to
	// SleepUntil with a deadline eliminates this race, and it isn't too
	// inconvenient for other callers.
	SleepUntil(ctx context.Context, wake time.Time) error
}

A Source tell the passage of time. This package provides two sources: Wall and Mock.

var Wall Source = wallClock{}

Wall is the normal clock, as provided by time.Now().

type Time

type Time = time.Time

Time is a convenient alias for time.Time.