feat: implement time jumping with Jump

Author: egil

README.md

@@ -10,15 +10,15 @@ During testing, you can move time forward by calling `Advance(TimeSpan)` or `Set
 
 The .NET team has published a similar test-specific time provider, the [`Microsoft.Extensions.Time.Testing.FakeTimeProvider`](https://www.nuget.org/packages/Microsoft.Extensions.Time.Testing.FakeTimeProvider/).
 
-The public API of both `FakeTimeProvider` and `ManualTimeProvider` are identical, but there are some differences in when time is set before timer callbacks. Let's illustrate this with an example:
+The public API of both `FakeTimeProvider` and `ManualTimeProvider` are compatible, but there are some differences in when time is set before timer callbacks. Let's illustrate this with an example:
 
 For example, if we create an `ITimer` with a *due time* and *period* set to **1 second**, the `DateTimeOffset` returned from `GetUtcNow()` during the timer callback may be different depending on the amount passed to `Advance()` (or `SetUtcNow()`).
 
 If we call `Advance(TimeSpan.FromSeconds(1))` three times, effectively moving time forward by three seconds, the timer callback will be invoked once at times `00:01`, `00:02`, and `00:03`, as illustrated in the drawing below. Both `FakeTimeProvider` and `ManualTimeProvider` behaves like this:
 
 ![Advancing time by three seconds in one-second increments.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/advance-1-second.svg)
 
-However, if we instead call `Advance(TimeSpan.FromSeconds(3))` once, the two implementations behave differently. `ManualTimeProvider` will invoke the timer callback at the same time (`00:01`, `00:02`, and `00:03`) as if we had called `Advance(TimeSpan.FromSeconds(1))` three times, as illustrated in the drawing below:
+If we instead call `Advance(TimeSpan.FromSeconds(3))` once, the two implementations behave differently. `ManualTimeProvider` will invoke the timer callback at the same time (`00:01`, `00:02`, and `00:03`) as if we had called `Advance(TimeSpan.FromSeconds(1))` three times, as illustrated in the drawing below:
 
 ![Advancing time by three seconds in one step using ManualTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/ManualTimeProvider-advance-3-seconds.svg)
 
@@ -30,6 +30,16 @@ Technically, both implementations are correct since the `ITimer` abstractions on
 
 However, I strongly prefer the `ManualTimeProvider` approach since it behaves consistently independent of how time is moved forward. It seems much more in the spirit of how a deterministic time provider should behave and avoids users being surprised when writing tests. I imagine users may get stuck for a while trying to debug why the time reported by `GetUtcNow()` is not set as expected due to the subtle difference in behavior of `FakeTimeProvider`.
 
+That said, it can be useful to test that your code behaves correctly if a timer isn't allocated processor time immidiately when it's callback should fire, and for that, `ManualTimeProvider` includes a different method, `Jump`.
+
+### Jumping to a point in time
+
+A real `ITimer`'s callback may not be allocated processor time and be able to fire at the moment it has been scheduled, e.g. if the processor is busy doing other things. The callback will eventaully fire (unless the timer is disposed).
+
+To support testing this scenario, `ManualtTimeProvider` includes a method that will jump time to a specific point, and then invoke all scheduled timer callbacks between the start and end of the jump. This behavior is similar to how `FakeTimeProvider`s `Advance` method works, as described in the previous sectoin.
+
+![Jumping ahead in time by three seconds in one step using ManualTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/jump-3-seconds.svg).
+
 ## Known limitations and issues:
 
 - If running on .NET versions earlier than .NET 8.0, there is a constraint when invoking `CancellationTokenSource.CancelAfter(TimeSpan)` on the `CancellationTokenSource` object returned by `CreateCancellationTokenSource(TimeSpan delay)`. This action will not terminate the initial timer indicated by the `delay` argument initially passed the `CreateCancellationTokenSource` method. However, this restriction does not apply to .NET 8.0 and later versions.

TimeProviderExtensions.lutconfig

@@ -0,0 +1,6 @@
+<LUTConfig Version="1.0">
+  <Repository />
+  <ParallelBuilds>true</ParallelBuilds>
+  <ParallelTestRuns>true</ParallelTestRuns>
+  <TestCaseTimeout>180000</TestCaseTimeout>
+</LUTConfig>

docs/jump-3-seconds.svg

@@ -19,11 +19,12 @@ private sealed class ManualTimerScheduler : IComparable<ManualTimerScheduler>
         private readonly TimerCallback callback;
         private readonly object? state;
         private readonly ManualTimeProvider timeProvider;
-        private TimeSpan period;
         private bool running;
 
         public DateTimeOffset CallbackTime { get; set; }
 
+        public TimeSpan Period { get; private set; }
+
         public ManualTimerScheduler(ManualTimeProvider timeProvider, TimerCallback callback, object? state)
         {
             this.timeProvider = timeProvider;
@@ -53,7 +54,7 @@ internal void Change(TimeSpan dueTime, TimeSpan period)
         {
             Cancel();
 
-            this.period = period;
+            Period = period;
 
             if (dueTime != Timeout.InfiniteTimeSpan)
             {
@@ -67,9 +68,9 @@ internal void TimerElapsed()
 
             callback.Invoke(state);
 
-            if (period != Timeout.InfiniteTimeSpan && period != TimeSpan.Zero)
+            if (Period != Timeout.InfiniteTimeSpan && Period != TimeSpan.Zero)
             {
-                ScheduleCallback(period);
+                ScheduleCallback(Period);
             }
         }