Table of Contents

Interface IPrimeTestClock

Namespace
KZDev.SystemClock.PrimeTime.Testing
Assembly
KZDev.SystemClock.PrimeTime.Testing.dll

Extends IPrimeTestTime and IPrimeClock with deterministic virtual time for tests: set the current instant, advance or jump forward with event marching, and optionally run a deadline-driven background runner at a validated rate. Delays, time-based cancellation, interval timers, and day-time timers are evaluated against the same virtual timeline.

public interface IPrimeTestClock : IPrimeTestTime, IPrimeClock, IPrimeTime
Inherited Members

Remarks

Forward marching. Advance(TimeSpan) and strictly forward SetTime(DateTimeOffset) move virtual time to each earliest due instant in order, dispatch delays, expiries, and timers at that instant (callbacks observe that instant in UtcNowDateTimeOffset), then advance to the next due instant until the target is reached. ClockEvents fires once per distinct virtual instant visited during the march.

Automatic runner. Start(TimeSpan?) starts a background loop that waits for the next virtual deadline (including a virtual one-minute ClockEvents heartbeat when idle), maps virtual delay to real time using the run rate, and marches using measured real elapsed time on a shared Stopwatch anchor (not only the intended sleep). Intended real waits shorter than 15 ms are handled by bursting virtual steps without sleeping. Registering new delays, timers, or time expiries, cancelling work, calling Stop(), or persist-on-read from a "now" getter can wake the runner early so sooner deadlines are not missed.

Observability while running. "Now" surfaces on PrimeTestClock linearly project virtual time from the last committed instant and the anchor stopwatch. Reading "now" while the runner is active also persist-on-read: due work up to the projected instant is marched, the committed instant is stored, and the anchor restarts (frequent reads can be costly).

Backward moves. While IsRunning is true, any backward SetTime(DateTimeOffset) throws InvalidOperationException. While stopped, backward moves throw if any interval timer registration is active; permitted backward jumps assign the instant without forward marching and raise ClockEvents once. Day-time timers recompute NextDueUtc so at most one callback occurs per discrete time-of-day occurrence.

Run rate. Explicit rates must be between 100 milliseconds and 1 hour of virtual time per real second (inclusive); null means 1:1. Values outside that range throw ArgumentOutOfRangeException at Start(TimeSpan?) with no clamping.

Methods

Advance(TimeSpan)

Advances virtual time forward by marching to each earliest due instant up to the new horizon, then dispatching delays, time expiries, and timers at each step.

RunFor(TimeSpan)

Starts a bounded automatic run that advances virtual time by duration at a 1:1 real-time pace (one second of virtual time per real second), then stops when that virtual elapsed time is reached.

RunFor(TimeSpan, TimeSpan)

Starts a bounded automatic run that advances virtual time by duration at perSecondRate (virtual time per one real second), then stops when that virtual elapsed time is reached.

SetTime(DateTimeOffset)

Sets the current UTC time of the clock to the specified value. When the clock is not running, this is the time returned by UtcNowDateTimeOffset and related members.

Start(TimeSpan?)

Starts a background runner that advances virtual time toward the next delay, time-expiry, timer due instant, or virtual-minute ClockEvents heartbeat, scaled by the run rate.

Stop()

Stops the automatic runner and clears the monotonic run anchor.

Events

ClockEvents

Occurs when the clock publishes a discriminated lifecycle or virtual-time event.