feat: provide a way to intercept timer callbacks and replace the default ManualTimer

Author: egil

CHANGELOG.md

@@ -11,6 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Allow `ManualTimeProvider.Start` to be set using property initializers.
 
+- Made the timer type created by `ManualTimeProvider`, the `ManualTimer` type, public, and introduced a protected method `CreateManualTimer` on `ManualTimeProvider`. This enables advanced scenarioes where a custom `ManualTimer` is needed. 
+
+  A custom implementation of `ManualTimer` can override the `Change` method and add custom behavior to it.
+
+  Overriding `CreateManualTimer` makes it possible to intercept a `TimerCallback` and perform actions before and after the timer callback has been invoked.
+
 ## [1.0.0-rc.1]
 
 - Updated Microsoft.Bcl.TimeProvider package dependency to rc.1 version.

docs/TimeProviderExtensions.ManualTimeProvider.md

@@ -214,14 +214,51 @@ the expected number of times, i.e. such that the result of `manualTimeProvider.G
 
 Learn more about this behavior at <seealso href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
 
+<a name='TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider)'></a>
+
+## ManualTimeProvider.CreateManualTimer(TimerCallback, object, ManualTimeProvider) Method
+
+Creates an instance of a [ManualTimer](TimeProviderExtensions.ManualTimer.md 'TimeProviderExtensions.ManualTimer'). This method is called by [CreateTimer(TimerCallback, object, TimeSpan, TimeSpan)](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.CreateTimer(System.Threading.TimerCallback,object,System.TimeSpan,System.TimeSpan) 'TimeProviderExtensions.ManualTimeProvider.CreateTimer(System.Threading.TimerCallback, object, System.TimeSpan, System.TimeSpan)').
+
+```csharp
+protected internal virtual TimeProviderExtensions.ManualTimer CreateManualTimer(System.Threading.TimerCallback callback, object? state, TimeProviderExtensions.ManualTimeProvider timeProvider);
+```
+#### Parameters
+
+<a name='TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).callback'></a>
+
+`callback` [System.Threading.TimerCallback](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.TimerCallback 'System.Threading.TimerCallback')
+
+A delegate representing a method to be executed when the timer fires. The method specified for callback should be reentrant,
+as it may be invoked simultaneously on two threads if the timer fires again before or while a previous callback is still being handled.
+
+<a name='TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).state'></a>
+
+`state` [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object')
+
+An object to be passed to the [callback](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).callback 'TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback, object, TimeProviderExtensions.ManualTimeProvider).callback'). This may be null.
+
+<a name='TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).timeProvider'></a>
+
+`timeProvider` [ManualTimeProvider](TimeProviderExtensions.ManualTimeProvider.md 'TimeProviderExtensions.ManualTimeProvider')
+
+The [ManualTimeProvider](TimeProviderExtensions.ManualTimeProvider.md 'TimeProviderExtensions.ManualTimeProvider') which is used to schedule invocations of the [callback](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).callback 'TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback, object, TimeProviderExtensions.ManualTimeProvider).callback') with.
+
+#### Returns
+[ManualTimer](TimeProviderExtensions.ManualTimer.md 'TimeProviderExtensions.ManualTimer')
+
+### Remarks
+Override this methods to return a custom implementation of [ManualTimer](TimeProviderExtensions.ManualTimer.md 'TimeProviderExtensions.ManualTimer'). This also allows for intercepting and wrapping
+the provided timer [callback](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).callback 'TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback, object, TimeProviderExtensions.ManualTimeProvider).callback') and [state](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback,object,TimeProviderExtensions.ManualTimeProvider).state 'TimeProviderExtensions.ManualTimeProvider.CreateManualTimer(System.Threading.TimerCallback, object, TimeProviderExtensions.ManualTimeProvider).state'), enabling more advanced testing scenarioes.
+
 <a name='TimeProviderExtensions.ManualTimeProvider.CreateTimer(System.Threading.TimerCallback,object,System.TimeSpan,System.TimeSpan)'></a>
 
 ## ManualTimeProvider.CreateTimer(TimerCallback, object, TimeSpan, TimeSpan) Method
 
 Creates a new [System.Threading.ITimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.ITimer 'System.Threading.ITimer') instance, using [System.TimeSpan](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan 'System.TimeSpan') values to measure time intervals.
 
 ```csharp
-public override System.Threading.ITimer CreateTimer(System.Threading.TimerCallback callback, object? state, System.TimeSpan dueTime, System.TimeSpan period);
+public sealed override System.Threading.ITimer CreateTimer(System.Threading.TimerCallback callback, object? state, System.TimeSpan dueTime, System.TimeSpan period);
 ```
 #### Parameters
 

docs/TimeProviderExtensions.ManualTimer.md

@@ -52,7 +52,7 @@ The [ManualTimeProvider](TimeProviderExtensions.ManualTimeProvider.md 'TimeProvi
 
 ## ManualTimer.CallbackTime Property
 
-Gets the next time the timer callback will be invoked, or `null` if the timer is inactive.
+Gets the next time the timer callback will be invoked, or [null](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/null 'https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/null') if the timer is inactive.
 
 ```csharp
 public System.Nullable<System.DateTimeOffset> CallbackTime { get; }
@@ -74,6 +74,22 @@ public System.TimeSpan DueTime { get; set; }
 #### Property Value
 [System.TimeSpan](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan 'System.TimeSpan')
 
+<a name='TimeProviderExtensions.ManualTimer.IsActive'></a>
+
+## ManualTimer.IsActive Property
+
+Gets whether the timer is currently active, i.e. has a future callback invocation scheduled.
+
+```csharp
+public bool IsActive { get; }
+```
+
+#### Property Value
+[System.Boolean](https://docs.microsoft.com/en-us/dotnet/api/System.Boolean 'System.Boolean')
+
+### Remarks
+When [IsActive](TimeProviderExtensions.ManualTimer.md#TimeProviderExtensions.ManualTimer.IsActive 'TimeProviderExtensions.ManualTimer.IsActive') returns [true](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/bool 'https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/bool'), [CallbackTime](TimeProviderExtensions.ManualTimer.md#TimeProviderExtensions.ManualTimer.CallbackTime 'TimeProviderExtensions.ManualTimer.CallbackTime') is not [null](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/null 'https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/null').
+
 <a name='TimeProviderExtensions.ManualTimer.Period'></a>
 
 ## ManualTimer.Period Property

src/TimeProviderExtensions/ManualTimeProvider.cs

@@ -174,13 +174,29 @@ public override DateTimeOffset GetUtcNow()
     /// To move time forward for the returned <see cref="ITimer"/>, call <see cref="Advance(TimeSpan)"/> or <see cref="SetUtcNow(DateTimeOffset)"/> on this time provider.
     /// </para>
     /// </remarks>
-    public override ITimer CreateTimer(TimerCallback callback, object? state, TimeSpan dueTime, TimeSpan period)
+    public sealed override ITimer CreateTimer(TimerCallback callback, object? state, TimeSpan dueTime, TimeSpan period)
     {
-        var result = new ManualTimer(callback, state, this);
+        var result = CreateManualTimer(callback, state, this);
         result.Change(dueTime, period);
         return result;
     }
 
+    /// <summary>
+    /// Creates an instance of a <see cref="ManualTimer"/>. This method is called by <see cref="CreateTimer(TimerCallback, object?, TimeSpan, TimeSpan)"/>.
+    /// </summary>
+    /// <remarks>
+    /// Override this methods to return a custom implementation of <see cref="ManualTimer"/>. This also allows for intercepting and wrapping
+    /// the provided timer <paramref name="callback"/> and <paramref name="state"/>, enabling more advanced testing scenarioes.
+    /// </remarks>
+    /// <param name="callback">
+    /// A delegate representing a method to be executed when the timer fires. The method specified for callback should be reentrant,
+    /// as it may be invoked simultaneously on two threads if the timer fires again before or while a previous callback is still being handled.
+    /// </param>
+    /// <param name="state">An object to be passed to the <paramref name="callback"/>. This may be null.</param>
+    /// <param name="timeProvider">The <see cref="ManualTimeProvider"/> which is used to schedule invocations of the <paramref name="callback"/> with.</param>
+    protected internal virtual ManualTimer CreateManualTimer(TimerCallback callback, object? state, ManualTimeProvider timeProvider)
+        => new ManualTimer(callback, state, timeProvider);
+
     /// <summary>
     /// Sets the local time zone.
     /// </summary>

src/TimeProviderExtensions/ManualTimer.cs

@@ -1,4 +1,5 @@
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.Runtime.CompilerServices;
 
@@ -16,7 +17,18 @@ public class ManualTimer : ITimer
     private ManualTimerScheduler? scheduler;
 
     /// <summary>
-    /// Gets the next time the timer callback will be invoked, or <c>null</c> if the timer is inactive.
+    /// Gets whether the timer is currently active, i.e. has a future callback invocation scheduled.
+    /// </summary>
+    /// <remarks>
+    /// When <see cref="IsActive"/> returns <see langword="true"/>, <see cref="CallbackTime"/> is not <see langword="null"/>.
+    /// </remarks>
+#if NET6_0_OR_GREATER
+    [MemberNotNullWhen(true, nameof(CallbackTime))]
+#endif
+    public bool IsActive => scheduler?.CallbackTime.HasValue ?? false;
+
+    /// <summary>
+    /// Gets the next time the timer callback will be invoked, or <see langword="null"/> if the timer is inactive.
     /// </summary>
     public DateTimeOffset? CallbackTime => scheduler?.CallbackTime;
 

test/TimeProviderExtensions.Tests/ManualTimeProviderTests.cs

@@ -281,5 +281,30 @@ public void ActiveTimers_with_after_timer_state_change()
         sut.Advance(1.Seconds());
 
         sut.ActiveTimers.Should().Be(0);
-    }    
+    }
+
+
+    [Fact]
+    public void CreateManualTimer_with_custom_timer_type()
+    {
+        var sut = new CustomManualTimeProvider();
+
+        using var timer = sut.CreateTimer(_ => { }, null, Timeout.InfiniteTimeSpan, Timeout.InfiniteTimeSpan);
+
+        timer.Should().BeOfType<CustomManualTimer>();
+    }
+
+    private sealed class CustomManualTimeProvider : ManualTimeProvider
+    {
+        protected internal override ManualTimer CreateManualTimer(TimerCallback callback, object? state, ManualTimeProvider timeProvider)
+            => new CustomManualTimer(callback, state, timeProvider);
+    }
+
+    private sealed class CustomManualTimer : ManualTimer
+    {
+        internal CustomManualTimer(TimerCallback callback, object? state, ManualTimeProvider timeProvider)
+            : base(callback, state, timeProvider)
+        {
+        }
+    }
 }