clock

package
v1.19.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 26, 2026 License: MIT Imports: 5 Imported by: 18

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

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 {
	// contains filtered or unexported fields
}

AdvancingClock tracks wall time and can be jumped forward via AdvanceTime. Now() is lazy (wall + offset) so it always reads the current time. A single scheduler goroutine fires pending timers when due; AdvanceTime signals it so jumped-past timers fire immediately.

func NewAdvancingClock

func NewAdvancingClock() *AdvancingClock

NewAdvancingClock creates a clock that advances continuously with the system clock and can also be jumped forward by arbitrary amounts via AdvanceTime. Now() always reflects the latest wall time plus any accumulated manual jumps. Scheduled actions (Timer, Ticker, After, AfterFunc) fire when due in logical time; a manual AdvanceTime that jumps past a due time fires the action immediately.

func (*AdvancingClock) AdvanceTime added in v1.19.0

func (c *AdvancingClock) AdvanceTime(d time.Duration)

AdvanceTime jumps time forward by d. Overdue actions fire when the scheduler next iterates (signalled below).

func (*AdvancingClock) After added in v1.19.0

func (c *AdvancingClock) After(d time.Duration) <-chan time.Time

func (*AdvancingClock) AfterFunc added in v1.19.0

func (c *AdvancingClock) AfterFunc(d time.Duration, f func()) Timer

func (*AdvancingClock) NewTicker added in v1.19.0

func (c *AdvancingClock) NewTicker(d time.Duration) Ticker

func (*AdvancingClock) NewTimer added in v1.19.0

func (c *AdvancingClock) NewTimer(d time.Duration) Timer

func (*AdvancingClock) Now added in v1.19.0

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

func (*AdvancingClock) Since added in v1.19.0

func (c *AdvancingClock) Since(t time.Time) time.Duration

func (*AdvancingClock) SleepCtx added in v1.19.0

func (c *AdvancingClock) SleepCtx(ctx context.Context, d time.Duration) error

func (*AdvancingClock) Start

func (c *AdvancingClock) Start()

func (*AdvancingClock) Stop

func (c *AdvancingClock) Stop()

func (*AdvancingClock) Until added in v1.19.0

func (c *AdvancingClock) Until(t time.Time) time.Duration

func (*AdvancingClock) WaitForNewPendingAction added in v1.19.0

func (c *AdvancingClock) WaitForNewPendingAction(ctx context.Context) bool

WaitForNewPendingAction blocks until a new action is scheduled since the last call to this method, or ctx is done. Intended for tests that need to synchronise with goroutines that schedule timers asynchronously.

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 (*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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL