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 (c *AdvancingClock) AdvanceTime(d time.Duration)
- func (c *AdvancingClock) After(d time.Duration) <-chan time.Time
- func (c *AdvancingClock) AfterFunc(d time.Duration, f func()) Timer
- func (c *AdvancingClock) NewTicker(d time.Duration) Ticker
- func (c *AdvancingClock) NewTimer(d time.Duration) Timer
- func (c *AdvancingClock) Now() time.Time
- func (c *AdvancingClock) Since(t time.Time) time.Duration
- func (c *AdvancingClock) SleepCtx(ctx context.Context, d time.Duration) error
- func (c *AdvancingClock) Start()
- func (c *AdvancingClock) Stop()
- func (c *AdvancingClock) Until(t time.Time) time.Duration
- func (c *AdvancingClock) WaitForNewPendingAction(ctx context.Context) bool
- type Clock
- type 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
- type RWClock
- type SimpleClock
- type SystemTicker
- type SystemTimer
- type Ticker
- type Timer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MinCheckedTimestamp ¶
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) 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) Now ¶
func (s *DeterministicClock) Now() time.Time
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.
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 ¶
func (*SystemTicker) Ch ¶
func (t *SystemTicker) Ch() <-chan time.Time
type SystemTimer ¶
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.