contract

type Clock ¶

type Clock interface {
	Now() time.Time

	NewTicker(interval time.Duration) Ticker
}

Clock abstracts the current time and the creation of tickers. NewTicker panics on a non-positive interval, and the Ticker it returns must be stopped by the consumer — see the Ticker contract.

A word on the frozen clock every test wires: its ticker is driven by REAL wall time — the tick cadence and the frozen timeline are two different timelines. Advance and TravelTo never fire a tick and never suppress one; each tick that does fire carries the frozen clock's current Now at delivery time, so a tick racing a TravelTo may carry either the pre-travel or the post-travel instant. A test that needs a tick must wait out the real interval: the ticker underneath is a real time.Ticker, so advancing the frozen clock past an interval does not make a tick arrive any sooner than it would have.

type Ticker ¶

type Ticker interface {
	Channel() <-chan time.Time

	Stop()
}

Ticker is the contract every clock's NewTicker answers with, and it carries obligations on both sides.

For the implementer: Stop must be idempotent — consumers stop a ticker from teardown paths that may run more than once — and it must NOT close the channel: time.Ticker leaves its channel open forever, and a consumer that selects on a stopped ticker's channel would spin on the zero value from a closed one. After Stop returns, no new tick may be produced; a tick accepted into the channel before Stop may still be read afterwards, exactly as with time.Ticker.

For the consumer: Stop is mandatory, not optional. An implementation is allowed to own a relay goroutine (the frozen clock's does), and abandoning such a ticker without Stop leaks that goroutine and pins the ticker and its clock for the life of the process — a cost the system clock's ticker does not have, which is exactly why the contract demands Stop for every implementation.