refactor: expose the wrapped PeriodicTimer as PeriodicTimerWrapper to avoid ambiguity when importing

Author: egil

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0-preview.1]
+
+This release adds a dependency on [Microsoft.Bcl.TimeProvider](https://www.nuget.org/packages/Microsoft.Bcl.TimeProvider) and utilizes the types built-in to that to do much of the work.
+
+When using the `ManualTimeProvider` during testing, be aware of these outstanding issues: https://github.com/dotnet/runtime/issues/85326
+
+- Removed `CancelAfter` extension methods. Instead create a CancellationTokenSource via the method `TimeProvider.CreateCancellationTokenSource(TimeSpan delay)` or in .NET 8, using `new CancellationTokenSource(TimeSpan delay, TimeProvider timeProvider). 
+
+  **NOTE:** If running on .NET versions earlier than .NET 8.0, there is a constraint when invoking `CancellationTokenSource.CancelAfter(TimeSpan)` on the resultant object. This action will not terminate the initial timer indicated by `delay`. However, this restriction does not apply on .NET 8.0 and later versions.
+
 ## [0.8.0]
 
 - Added `TimeProvider.GetElapsedTime(long startingTimestamp)`

README.md

@@ -8,34 +8,40 @@ Currently, the following .NET time-based APIs are supported:
 |----------------------|----------------------|
 | `GetUtcNow()` method | `DateTimeOffset.UtcNow` property |
 | `CreateTimer()` method | `System.Threading.Timer` type |
-| `TimeProvider.CreatePeriodicTimer(TimeSpan)` method (only .NET 6) | `System.Threading.PeriodicTimer` type |
 | `Delay(TimeSpan, CancellationToken)` method | `Task.Delay(TimeSpan, CancellationToken)` method |
-| `CancellationTokenSource.CancelAfter(TimeSpan, TimeProvider)` and `TimeProvider.CreateCancellationTokenSource(TimeSpan delay)` methods | `CancellationTokenSource.CancelAfter(TimeSpan)` method |
-| `Task.WaitAsync(TimeSpan, TimeProvider)` method (only .NET 6)| `Task.WaitAsync(TimeSpan)` method |
-| `Task.WaitAsync(TimeSpan, TimeProvider, CancellationToken)` method (only .NET 6)| `Task.WaitAsync(TimeSpan, CancellationToken)` method |
+| `Task.WaitAsync(TimeSpan, TimeProvider)` method | `Task.WaitAsync(TimeSpan)` method |
+| `Task.WaitAsync(TimeSpan, TimeProvider, CancellationToken)` method | `Task.WaitAsync(TimeSpan, CancellationToken)` method |
+| `TimeProvider.CreatePeriodicTimer(TimeSpan)` method | `System.Threading.PeriodicTimer` type |
+| `TimeProvider.CreateCancellationTokenSource(TimeSpan)` method | `new CancellationTokenSource(TimeSpan)` method |
 
-The implementations of `TimeProvider` is abstract. An instance of `TimeProvider` for production use is availalbe on the `TimeProvider.System` property,
+The implementation of `TimeProvider` is abstract. An instance of `TimeProvider` for production use is available on the `TimeProvider.System` property,
 and `ManualTimeProvider` can be used during testing.
 
 During testing, you can move time forward by calling `ForwardTime(TimeSpan)` or `SetUtcNow(DateTimeOffset)` on `ManualTimeProvider`. This allows
 you to write tests that run fast and predictable, even if the system under test pauses execution for
 multiple minutes using e.g. `TimeProvider.Delay(TimeSpan)`, the replacement for `Task.Delay(TimeSpan)`.
 
+## Known issues and limitations:
+
+- When using the `ManualTimeProvider` during testing to forward time, be aware of this issue: https://github.com/dotnet/runtime/issues/85326.
+- 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 on .NET 8.0 and later versions.
+- To enable controlling `PeriodicTimer` via `TimeProvider` in versions of .NET earlier than .NET 8.0, the `TimeProvider.CreatePeriodicTimer` returns a `PeriodicTimerWrapper` object instead of a `PeriodicTimer` object. The `PeriodicTimerWrapper` type is just a lightweight wrapper around the original `System.Threading.PeriodicTimer` and will behave identically to it. 
+
 ## Installation
 
 Get the latest release from https://www.nuget.org/packages/TimeProviderExtensions
 
 ## Set up in production
 
 To use in production, pass in `TimeProvider.System` to the types that depend on `TimeProvider`. 
-This can be done directly, or via an IoC Container, e.g. .NETs built-in `IServiceCollection` like so:
+This can be done directly or via an IoC Container, e.g. .NETs built-in `IServiceCollection` like so:
 
 ```c#
 services.AddSingleton(TimeProvider.System);
 ```
 
 If you do not want to register the `TimeProvider` with your IoC container, you can instead create
-an additional constructor in the types that use it, which allow you to pass in a `TimeProvider`,
+an additional constructor in the types that use it, which allows you to pass in a `TimeProvider`,
 and in the existing constructor(s) you have, just new up `TimeProvider.System` directly. For example:
 
 ```c#
@@ -54,20 +60,20 @@ public class MyService
 }
 ```
 
-This allows you to explicitly pass in an `ManualTimeProvider` during testing.
+This allows you to explicitly pass in a `ManualTimeProvider` during testing.
 
 ## Example - control time during tests
 
 If a system under test (SUT) uses things like `Task.Delay`, `DateTimeOffset.UtcNow`, `Task.WaitAsync`, or `PeriodicTimer`, 
-it becomes hard to create tests that runs fast and predictably.
+it becomes hard to create tests that run fast and predictably.
 
 The idea is to replace the use of e.g. `Task.Delay` with an abstraction, the `TimeProvider`, that in production
-is represented by the `TimeProvider.System`, that just uses the real `Task.Delay`. During testing it is now possible to
-pass in `ManualTimeProvider`, that allows the test to control the progress of time, making it possible to skip ahead,
+is represented by the `TimeProvider.System`, which just uses the real `Task.Delay`. During testing it is now possible to
+pass in `ManualTimeProvider`, which allows the test to control the progress of time, making it possible to skip ahead,
 e.g. 10 minutes, and also pause time, leading to fast and predictable tests.
 
-As an example, lets test the "Stuff Service" below that performs a specific tasks every 10 second with an additional 
-1 second delay. We have two versions, one that uses the standard types in .NET, and one that uses the `TimeProvider`.
+As an example, let us test the "Stuff Service" below that performs specific tasks every 10 seconds with an additional 
+1-second delay. We have two versions, one that uses the standard types in .NET, and one that uses the `TimeProvider`.
 
 ```c#
 // Version of stuff service that uses the built in DateTimeOffset, PeriodicTimer, and Task.Delay
@@ -93,7 +99,7 @@ public class StuffService
   }
 }
 
-// Version of stuff service that uses the built in TimeProvider
+// Version of stuff service that uses the built-in TimeProvider
 public class StuffServiceUsingTimeProvider
 {
   private static readonly TimeSpan doStuffDelay = TimeSpan.FromSeconds(10);
@@ -144,7 +150,7 @@ public void DoStuff_does_stuff_every_11_seconds()
 }
 ```
 
-This test will run in nanoseconds, and is deterministic.
+This test will run in nanoseconds and is deterministic.
 
 Compare that to the similar test below for `StuffService` that needs to wait for 11 seconds before it can safely assert that the expectation has been met.
 

src/TimeProviderExtensions/PeriodicTimer.cs

@@ -3,22 +3,38 @@
 // Original code: https://github.com/dotnet/runtime/blob/0096ba52e8c86e4d712013f6330a9b8a6496a1e0/src/libraries/System.Private.CoreLib/src/System/Threading/PeriodicTimer.cs
 
 #if NET6_0_OR_GREATER && !NET8_0_OR_GREATER
+using System;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.ExceptionServices;
+using System.Threading.Tasks;
 using System.Threading.Tasks.Sources;
-using System.Timers;
-using TimeProviderExtensions;
 
-namespace System.Threading;
+namespace TimeProviderExtensions;
 
-internal sealed class ManualPeriodicTimer : TimeProviderExtensions.PeriodicTimer
+/// <summary>Provides a periodic timer that enables waiting asynchronously for timer ticks.</summary>
+/// <remarks>
+/// This timer is intended to be used only by a single consumer at a time: only one call to <see cref="WaitForNextTickAsync" />
+/// may be in flight at any given moment.  <see cref="Dispose"/> may be used concurrently with an active <see cref="WaitForNextTickAsync"/>
+/// to interrupt it and cause it to return false. Similarly, <see cref="Period"/> may be used concurrently with a consumer accessing
+/// <see cref="WaitForNextTickAsync"/> in order to change the timer's period.
+/// </remarks>
+internal sealed class PeriodicTimerPort : IDisposable
 {
-    private readonly ITimer timer;
-    private readonly State state;
-    private bool disposed;
+    internal const uint MaxSupportedTimeout = 0xfffffffe;
+    internal const uint UnsignedInfinite = unchecked((uint)-1);
 
-    public ManualPeriodicTimer(TimeSpan period, TimeProvider timeProvider)
+    /// <summary>The underlying timer.</summary>
+    private readonly ITimer _timer;
+    /// <summary>All state other than the _timer, so that the rooted timer's callback doesn't indirectly root itself by referring to _timer.</summary>
+    private readonly State _state;
+
+    /// <summary>Initializes the timer.</summary>
+    /// <param name="period">The period between ticks</param>
+    /// <param name="timeProvider">The <see cref="TimeProvider"/> used to interpret <paramref name="period"/>.</param>
+    /// <exception cref="ArgumentOutOfRangeException"><paramref name="period"/> must be <see cref="Timeout.InfiniteTimeSpan"/> or represent a number of milliseconds equal to or larger than 1 and smaller than <see cref="uint.MaxValue"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="timeProvider"/> is null</exception>
+    internal PeriodicTimerPort(TimeSpan period, TimeProvider timeProvider)
     {
         if (!TryGetMilliseconds(period, out uint ms))
         {
@@ -29,36 +45,64 @@ public ManualPeriodicTimer(TimeSpan period, TimeProvider timeProvider)
         if (timeProvider is null)
         {
             GC.SuppressFinalize(this);
-            ArgumentNullException.ThrowIfNull(timeProvider);
+            throw new ArgumentNullException(nameof(timeProvider));
         }
 
-        state = new State();
+        _state = new State();
         TimerCallback callback = s => ((State)s!).Signal();
 
         using (ExecutionContext.SuppressFlow())
         {
-            timer = timeProvider.CreateTimer(callback, state, period, period);
+            _timer = timeProvider.CreateTimer(callback, _state, period, period);
         }
     }
 
-    public override ValueTask<bool> WaitForNextTickAsync(CancellationToken cancellationToken = default)
-        => state.WaitForNextTickAsync(this, cancellationToken);
-
-    protected override void Dispose(bool disposing)
+    /// <summary>Tries to extract the number of milliseconds from <paramref name="value"/>.</summary>
+    /// <returns>
+    /// true if the number of milliseconds is extracted and stored into <paramref name="milliseconds"/>;
+    /// false if the number of milliseconds would be out of range of a timer.
+    /// </returns>
+    private static bool TryGetMilliseconds(TimeSpan value, out uint milliseconds)
     {
-        if (disposed)
+        long ms = (long)value.TotalMilliseconds;
+        if ((ms >= 1 && ms <= MaxSupportedTimeout) || value == Timeout.InfiniteTimeSpan)
         {
-            return;
+            milliseconds = (uint)ms;
+            return true;
         }
 
-        disposed = true;
-        timer.Dispose();
-        state.Signal(stopping: true);
-        base.Dispose(disposing);
+        milliseconds = 0;
+        return false;
+    }
+
+    /// <summary>Wait for the next tick of the timer, or for the timer to be stopped.</summary>
+    /// <param name="cancellationToken">
+    /// A <see cref="CancellationToken"/> to use to cancel the asynchronous wait. If cancellation is requested, it affects only the single wait operation;
+    /// the underlying timer continues firing.
+    /// </param>
+    /// <returns>A task that will be completed due to the timer firing, <see cref="Dispose"/> being called to stop the timer, or cancellation being requested.</returns>
+    /// <remarks>
+    /// The <see cref="PeriodicTimer"/> behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between
+    /// calls to <see cref="WaitForNextTickAsync"/>.  Similarly, a call to <see cref="Dispose"/> will void any tick not yet consumed. <see cref="WaitForNextTickAsync"/>
+    /// may only be used by one consumer at a time, and may be used concurrently with a single call to <see cref="Dispose"/>.
+    /// </remarks>
+    public ValueTask<bool> WaitForNextTickAsync(CancellationToken cancellationToken = default) =>
+        _state.WaitForNextTickAsync(this, cancellationToken);
+
+    /// <summary>Stops the timer and releases associated managed resources.</summary>
+    /// <remarks>
+    /// <see cref="Dispose"/> will cause an active wait with <see cref="WaitForNextTickAsync"/> to complete with a value of false.
+    /// All subsequent <see cref="WaitForNextTickAsync"/> invocations will produce a value of false.
+    /// </remarks>
+    public void Dispose()
+    {
+        GC.SuppressFinalize(this);
+        _timer.Dispose();
+        _state.Signal(stopping: true);
     }
 
     /// <summary>Ensures that resources are freed and other cleanup operations are performed when the garbage collector reclaims the <see cref="PeriodicTimer" /> object.</summary>
-    ~ManualPeriodicTimer() => Dispose();
+    ~PeriodicTimerPort() => Dispose();
 
     /// <summary>Core implementation for the periodic timer.</summary>
     [SuppressMessage("Reliability", "CA2002:Do not lock on objects with weak identity", Justification = "Code copied from Microsoft.")]
@@ -84,7 +128,7 @@ private sealed class State : IValueTaskSource<bool>
         /// will never tick in such a case, and for the timer's period to be changed, the user's code would need
         /// some other reference to PeriodicTimer keeping it alive, anyway.
         /// </remarks>
-        private ManualPeriodicTimer? _owner;
+        private PeriodicTimerPort? _owner;
         /// <summary>Core of the <see cref="IValueTaskSource{TResult}"/> implementation.</summary>
         private ManualResetValueTaskSourceCore<bool> _mrvtsc;
         /// <summary>Cancellation registration for any active <see cref="WaitForNextTickAsync"/> call.</summary>
@@ -97,7 +141,7 @@ private sealed class State : IValueTaskSource<bool>
         private bool _activeWait;
 
         /// <summary>Wait for the next tick of the timer, or for the timer to be stopped.</summary>
-        public ValueTask<bool> WaitForNextTickAsync(ManualPeriodicTimer owner, CancellationToken cancellationToken)
+        public ValueTask<bool> WaitForNextTickAsync(PeriodicTimerPort owner, CancellationToken cancellationToken)
         {
             lock (this)
             {