Documentation
¶
Overview ¶
Package clock is the agent's source of time. Every component reads time through a Clock rather than calling time.Now directly, so runs are reproducible: tests and deterministic replay supply a Manual clock that only advances when told, while production uses System.
This is a deliberate foundational choice - deterministic replay and time-travel debugging are impossible if wall-clock time leaks in at arbitrary call sites.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Clock ¶
type Clock interface {
// Now returns the current time. Implementations should return UTC.
Now() time.Time
}
Clock is the agent's source of the current time.
type Manual ¶
type Manual struct {
// contains filtered or unexported fields
}
Manual is a deterministic Clock for tests and replay: it returns a fixed time that only changes via Advance or Set. It is safe for concurrent use. Manual also implements Timing: timers it hands out fire only when Advance or Set moves the clock past their deadline, so time-based code (the reconciler workqueue) stays fully deterministic with no real sleeping.
func (*Manual) NewTimer ¶
NewTimer returns a timer that fires when the Manual clock is advanced past d from the current time. d <= 0 fires immediately.
func (*Manual) PendingTimers ¶
PendingTimers returns how many timers are armed and not yet fired. It lets a test wait until asynchronously-scheduled work (a queue's backoff timer) has registered before advancing the clock, so time-driven behaviour is deterministic rather than racy.
type System ¶
type System struct{}
System is the production Clock, backed by the wall clock in UTC.
type Timer ¶
type Timer interface {
// C is the channel the timer fires on. It delivers at most one value.
C() <-chan time.Time
// Stop prevents a not-yet-fired timer from firing. It reports whether the
// timer was still pending (true) or had already fired or been stopped (false),
// matching time.Timer.Stop.
Stop() bool
// Reset restarts the timer to fire after d from now. It reports whether the
// timer was still pending before the reset, matching time.Timer.Reset.
Reset(d time.Duration) bool
}
Timer is a single-shot timer whose channel C fires once, when its deadline arrives. It mirrors the slice of time.Timer that delayed-work schedulers need, but is created through a Timing clock so a Manual clock makes timer-based code deterministic (the timer fires on Advance/Set, never on real wall time).
type Timing ¶
type Timing interface {
Clock
// NewTimer returns a timer that fires once after d. A d <= 0 fires immediately.
NewTimer(d time.Duration) Timer
// After is shorthand for NewTimer(d).C().
After(d time.Duration) <-chan time.Time
}
Timing is a Clock that can also schedule timers. Components that delay work (the reconciler workqueue's AddAfter/rate limiting) depend on Timing rather than Clock so tests drive every delay with a Manual clock instead of sleeping. Both System and Manual implement it.
Source Files