clock

Documentation

Overview

Package clock provides an abstraction for time to enable testing of functionality that uses time as an input.

Index

• func MinCheckedTimestamp(clock RWClock, duration time.Duration) uint64
• type AdvancingClock
  • func NewAdvancingClock(advanceEvery time.Duration) *AdvancingClock
  • func (c *AdvancingClock) Start()
  • func (c *AdvancingClock) Stop()
• type Clock
• type DeterministicClock
  • func NewDeterministicClock(now time.Time) *DeterministicClock
  • func (s *DeterministicClock) AdvanceTime(d time.Duration)
  • func (s *DeterministicClock) After(d time.Duration) <-chan time.Time
  • func (s *DeterministicClock) AfterFunc(d time.Duration, f func()) Timer
  • func (s *DeterministicClock) NewTicker(d time.Duration) Ticker
  • func (s *DeterministicClock) NewTimer(d time.Duration) Timer
  • func (s *DeterministicClock) Now() time.Time
  • func (s *DeterministicClock) Since(t time.Time) time.Duration
  • func (s *DeterministicClock) SleepCtx(ctx context.Context, d time.Duration) error
  • func (s *DeterministicClock) WaitForNewPendingTask(ctx context.Context) bool
  • func (s *DeterministicClock) WaitForNewPendingTaskWithTimeout(timeout time.Duration) bool
• type LoopFn
  • func NewLoopFn(clock Clock, fn func(ctx context.Context), onClose func() error, ...) *LoopFn
  • func (lf *LoopFn) Close() error
• type RWClock
• type SimpleClock
  • func NewSimpleClock() *SimpleClock
  • func (c *SimpleClock) Now() time.Time
  • func (c *SimpleClock) Set(v time.Time)
  • func (c *SimpleClock) SetTime(u uint64)
• type SystemTicker
  • func (t *SystemTicker) Ch() <-chan time.Time
• type SystemTimer
  • func (t *SystemTimer) Ch() <-chan time.Time
• type Ticker
• type Timer

Functions

func MinCheckedTimestamp

func MinCheckedTimestamp(clock RWClock, duration time.Duration) uint64

MinCheckedTimestamp returns the minimum checked unix timestamp. If the duration is 0, the returned minimum timestamp is 0. Otherwise, the minimum timestamp is the current unix time minus the duration. The subtraction operation is checked and returns 0 on underflow.

Types

type AdvancingClock

type AdvancingClock struct {
	*DeterministicClock
	// contains filtered or unexported fields
}

func NewAdvancingClock

func NewAdvancingClock(advanceEvery time.Duration) *AdvancingClock

NewAdvancingClock creates a clock that, when started, advances at the same rate as the system clock but can also be advanced arbitrary amounts using the AdvanceTime method. Unlike the system clock, time does not progress smoothly but only increments when AdvancedTime is called or approximately after advanceEvery duration has elapsed. When advancing based on the system clock, the total time the system clock has advanced is added to the current time, preventing time differences from building up over time.

func (*AdvancingClock) Start

func (c *AdvancingClock) Start()

func (*AdvancingClock) Stop

func (c *AdvancingClock) Stop()

type Clock

type Clock interface {
	// Now provides the current local time. Equivalent to time.Now
	Now() time.Time

	// Since returns the time elapsed since t. It is shorthand for time.Now().Sub(t).
	Since(time.Time) time.Duration

	// After waits for the duration to elapse and then sends the current time on the returned channel.
	// It is equivalent to time.After
	After(d time.Duration) <-chan time.Time

	AfterFunc(d time.Duration, f func()) Timer

	// NewTicker returns a new Ticker containing a channel that will send
	// the current time on the channel after each tick. The period of the
	// ticks is specified by the duration argument. The ticker will adjust
	// the time interval or drop ticks to make up for slow receivers.
	// The duration d must be greater than zero; if not, NewTicker will
	// panic. Stop the ticker to release associated resources.
	NewTicker(d time.Duration) Ticker

	// NewTimer creates a new Timer that will send
	// the current time on its channel after at least duration d.
	NewTimer(d time.Duration) Timer

	// SleepCtx sleeps until either ctx is done or the specified duration has elapsed.
	// Returns the ctx.Err if it returns because the context is done.
	SleepCtx(ctx context.Context, d time.Duration) error
}

Clock represents time in a way that can be provided by varying implementations. Methods are designed to be direct replacements for methods in the time package, with some new additions to make common patterns simple.

var SystemClock Clock = systemClock{}

SystemClock provides an instance of Clock that uses the system clock via methods in the time package.

type DeterministicClock

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

func NewDeterministicClock

func NewDeterministicClock(now time.Time) *DeterministicClock

NewDeterministicClock creates a new clock where time only advances when the DeterministicClock.AdvanceTime method is called. This is intended for use in situations where a deterministic clock is required, such as testing or event driven systems.

func (*DeterministicClock) AdvanceTime

func (s *DeterministicClock) AdvanceTime(d time.Duration)

AdvanceTime moves the time forward by the specific duration

func (*DeterministicClock) After

func (s *DeterministicClock) After(d time.Duration) <-chan time.Time

func (*DeterministicClock) AfterFunc

func (s *DeterministicClock) AfterFunc(d time.Duration, f func()) Timer

func (*DeterministicClock) NewTicker

func (s *DeterministicClock) NewTicker(d time.Duration) Ticker

func (*DeterministicClock) NewTimer

func (s *DeterministicClock) NewTimer(d time.Duration) Timer

func (*DeterministicClock) Now

func (s *DeterministicClock) Now() time.Time

func (*DeterministicClock) Since

func (s *DeterministicClock) Since(t time.Time) time.Duration

func (*DeterministicClock) SleepCtx

func (s *DeterministicClock) SleepCtx(ctx context.Context, d time.Duration) error

func (*DeterministicClock) WaitForNewPendingTask

func (s *DeterministicClock) WaitForNewPendingTask(ctx context.Context) bool

WaitForNewPendingTask blocks until a new task is scheduled since the last time this method was called. true is returned if a new task was scheduled, false if the context completed before a new task was added.

func (*DeterministicClock) WaitForNewPendingTaskWithTimeout

func (s *DeterministicClock) WaitForNewPendingTaskWithTimeout(timeout time.Duration) bool

type LoopFn

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

LoopFn is a simple ticker-loop with io.Closer support. Note that ticks adapt; slow function calls may result in lost ticks.

func NewLoopFn

func NewLoopFn(clock Clock, fn func(ctx context.Context), onClose func() error, interval time.Duration) *LoopFn

NewLoopFn creates a periodic function call, which can be closed, with an optional onClose callback to clean up resources.

func (*LoopFn) Close

func (lf *LoopFn) Close() error

Close cancels the context of the ongoing function call, waits for the call to complete, and cancels further calls. Close is safe to call again or concurrently. The onClose callback will be called for each Close call.

type RWClock

type RWClock interface {
	Now() time.Time
}

type SimpleClock

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

func NewSimpleClock

func NewSimpleClock() *SimpleClock

func (*SimpleClock) Now

func (c *SimpleClock) Now() time.Time

func (*SimpleClock) Set

func (c *SimpleClock) Set(v time.Time)

func (*SimpleClock) SetTime

func (c *SimpleClock) SetTime(u uint64)

type SystemTicker

type SystemTicker struct {
	*time.Ticker
}

func (*SystemTicker) Ch

func (t *SystemTicker) Ch() <-chan time.Time

type SystemTimer

type SystemTimer struct {
	*time.Timer
}

func (*SystemTimer) Ch

func (t *SystemTimer) Ch() <-chan time.Time

type Ticker

type Ticker interface {
	// Ch returns the channel for the ticker. Equivalent to time.Ticker.C
	Ch() <-chan time.Time

	// Stop turns off a ticker. After Stop, no more ticks will be sent.
	// Stop does not close the channel, to prevent a concurrent goroutine
	// reading from the channel from seeing an erroneous "tick".
	Stop()

	// Reset stops a ticker and resets its period to the specified duration.
	// The next tick will arrive after the new period elapses. The duration d
	// must be greater than zero; if not, Reset will panic.
	Reset(d time.Duration)
}

A Ticker holds a channel that delivers "ticks" of a clock at intervals

type Timer

type Timer interface {
	// Ch returns the channel for the ticker. Equivalent to time.Timer.C
	Ch() <-chan time.Time

	// Stop prevents the Timer from firing.
	// It returns true if the call stops the timer, false if the timer has already
	// expired or been stopped.
	// Stop does not close the channel, to prevent a read from the channel succeeding
	// incorrectly.
	//
	// For a timer created with AfterFunc(d, f), if t.Stop returns false, then the timer
	// has already expired and the function f has been started in its own goroutine;
	// Stop does not wait for f to complete before returning.
	// If the caller needs to know whether f is completed, it must coordinate
	// with f explicitly.
	Stop() bool
}

Timer represents a single event.