refactor: replaced AutoAdvanceAmount with AutoAdvanceBehavior

Author: egil

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   Overriding `CreateManualTimer` makes it possible to intercept a `TimerCallback` and perform actions before and after the timer callback has been invoked.
 
+- Replace `AutoAdvanceAmount` property with the `AutoAdvanceBehavior` property on `ManualTimeProvider`, and introduced the `AutoAdvanceBehavior` type.
+
 ## [1.0.0-rc.1]
 
 - Updated Microsoft.Bcl.TimeProvider package dependency to rc.1 version.

docs/TimeProviderExtensions.AutoAdvanceBehavior.md

@@ -0,0 +1,37 @@
+#### [TimeProviderExtensions](index.md 'index')
+### [TimeProviderExtensions](index.md#TimeProviderExtensions 'TimeProviderExtensions')
+
+## AutoAdvanceBehavior Class
+
+The [AutoAdvanceBehavior](TimeProviderExtensions.AutoAdvanceBehavior.md 'TimeProviderExtensions.AutoAdvanceBehavior') type provides a way to enable and customize the automatic advance of time.
+
+```csharp
+public sealed class AutoAdvanceBehavior :
+System.IEquatable<TimeProviderExtensions.AutoAdvanceBehavior>
+```
+
+Inheritance [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object') &#129106; AutoAdvanceBehavior
+
+Implements [System.IEquatable&lt;](https://docs.microsoft.com/en-us/dotnet/api/System.IEquatable-1 'System.IEquatable`1')[AutoAdvanceBehavior](TimeProviderExtensions.AutoAdvanceBehavior.md 'TimeProviderExtensions.AutoAdvanceBehavior')[&gt;](https://docs.microsoft.com/en-us/dotnet/api/System.IEquatable-1 'System.IEquatable`1')
+### Properties
+
+<a name='TimeProviderExtensions.AutoAdvanceBehavior.ClockAdvanceAmount'></a>
+
+## AutoAdvanceBehavior.ClockAdvanceAmount Property
+
+Gets or sets the amount of time by which time advances whenever the clock is read via [System.TimeProvider.GetUtcNow](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider.GetUtcNow 'System.TimeProvider.GetUtcNow') or [System.TimeProvider.GetLocalNow](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider.GetLocalNow 'System.TimeProvider.GetLocalNow').
+
+```csharp
+public System.TimeSpan ClockAdvanceAmount { get; set; }
+```
+
+#### Property Value
+[System.TimeSpan](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan 'System.TimeSpan')
+
+#### Exceptions
+
+[System.ArgumentOutOfRangeException](https://docs.microsoft.com/en-us/dotnet/api/System.ArgumentOutOfRangeException 'System.ArgumentOutOfRangeException')  
+Thrown when set to a value than [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero').
+
+### Remarks
+Set to [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero') to disable auto advance. The default value is [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero').

docs/TimeProviderExtensions.ManualTimeProvider.md

@@ -91,26 +91,18 @@ public int ActiveTimers { get; }
 #### Property Value
 [System.Int32](https://docs.microsoft.com/en-us/dotnet/api/System.Int32 'System.Int32')
 
-<a name='TimeProviderExtensions.ManualTimeProvider.AutoAdvanceAmount'></a>
+<a name='TimeProviderExtensions.ManualTimeProvider.AutoAdvanceBehavior'></a>
 
-## ManualTimeProvider.AutoAdvanceAmount Property
+## ManualTimeProvider.AutoAdvanceBehavior Property
 
-Gets or sets the amount of time by which time advances whenever the clock is read via [GetUtcNow()](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.GetUtcNow() 'TimeProviderExtensions.ManualTimeProvider.GetUtcNow()').
+Gets or sets the auto advance behavior of this [ManualTimeProvider](TimeProviderExtensions.ManualTimeProvider.md 'TimeProviderExtensions.ManualTimeProvider').
 
 ```csharp
-public System.TimeSpan AutoAdvanceAmount { get; set; }
+public TimeProviderExtensions.AutoAdvanceBehavior AutoAdvanceBehavior { get; set; }
 ```
 
 #### Property Value
-[System.TimeSpan](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan 'System.TimeSpan')
-
-#### Exceptions
-
-[System.ArgumentOutOfRangeException](https://docs.microsoft.com/en-us/dotnet/api/System.ArgumentOutOfRangeException 'System.ArgumentOutOfRangeException')  
-Thrown when set to a value than [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero').
-
-### Remarks
-Set to [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero') to disable auto advance. The default value is [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero').
+[AutoAdvanceBehavior](TimeProviderExtensions.AutoAdvanceBehavior.md 'TimeProviderExtensions.AutoAdvanceBehavior')
 
 <a name='TimeProviderExtensions.ManualTimeProvider.LocalTimeZone'></a>
 
@@ -350,8 +342,8 @@ public override System.DateTimeOffset GetUtcNow();
 [System.DateTimeOffset](https://docs.microsoft.com/en-us/dotnet/api/System.DateTimeOffset 'System.DateTimeOffset')
 
 ### Remarks
-If [AutoAdvanceAmount](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.AutoAdvanceAmount 'TimeProviderExtensions.ManualTimeProvider.AutoAdvanceAmount') is greater than [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero'), calling this
-method will move time forward by the amount specified by [AutoAdvanceAmount](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.AutoAdvanceAmount 'TimeProviderExtensions.ManualTimeProvider.AutoAdvanceAmount').
+If [AutoAdvanceAmount](https://docs.microsoft.com/en-us/dotnet/api/AutoAdvanceAmount 'AutoAdvanceAmount') is greater than [System.TimeSpan.Zero](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan.Zero 'System.TimeSpan.Zero'), calling this
+method will move time forward by the amount specified by [AutoAdvanceAmount](https://docs.microsoft.com/en-us/dotnet/api/AutoAdvanceAmount 'AutoAdvanceAmount').
 The [System.DateTimeOffset](https://docs.microsoft.com/en-us/dotnet/api/System.DateTimeOffset 'System.DateTimeOffset') returned from this method will reflect the time before
 the auto advance was applied, if any.
 

docs/index.md

@@ -18,5 +18,6 @@
 
 | Classes | |
 | :--- | :--- |
+| [AutoAdvanceBehavior](TimeProviderExtensions.AutoAdvanceBehavior.md 'TimeProviderExtensions.AutoAdvanceBehavior') | The [AutoAdvanceBehavior](TimeProviderExtensions.AutoAdvanceBehavior.md 'TimeProviderExtensions.AutoAdvanceBehavior') type provides a way to enable and customize the automatic advance of time. |
 | [ManualTimeProvider](TimeProviderExtensions.ManualTimeProvider.md 'TimeProviderExtensions.ManualTimeProvider') | Represents a synthetic time provider that can be used to enable deterministic behavior in tests. |
 | [ManualTimer](TimeProviderExtensions.ManualTimer.md 'TimeProviderExtensions.ManualTimer') | A implementaiton of a [System.Threading.ITimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.ITimer 'System.Threading.ITimer') whose callbacks are scheduled via a [ManualTimeProvider](TimeProviderExtensions.ManualTimeProvider.md 'TimeProviderExtensions.ManualTimeProvider'). |

src/TimeProviderExtensions/AutoAdvanceBehavior.cs

@@ -0,0 +1,28 @@
+using System.Runtime.CompilerServices;
+
+namespace TimeProviderExtensions;
+
+/// <summary>
+/// The <see cref="AutoAdvanceBehavior"/> type provides a way to enable and customize the automatic advance of time.
+/// </summary>
+public sealed record class AutoAdvanceBehavior
+{
+    private TimeSpan clockAdvanceAmount = TimeSpan.Zero;
+
+    /// <summary>
+    /// Gets or sets the amount of time by which time advances whenever the clock is read via <see cref="TimeProvider.GetUtcNow"/> or <see cref="TimeProvider.GetLocalNow"/>.
+    /// </summary>
+    /// <remarks>
+    /// Set to <see cref="TimeSpan.Zero"/> to disable auto advance. The default value is <see cref="TimeSpan.Zero"/>.
+    /// </remarks>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when set to a value than <see cref="TimeSpan.Zero"/>.</exception>
+    public TimeSpan ClockAdvanceAmount { get => clockAdvanceAmount; set { ThrowIfLessThanZero(value); clockAdvanceAmount = value; } }
+
+    private static void ThrowIfLessThanZero(TimeSpan value, [CallerMemberName] string? parameterName = null)
+    {
+        if (value < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(parameterName, "Auto advance amounts cannot be less than zero.");
+        }
+    }
+}

src/TimeProviderExtensions/ManualTimeProvider.cs

@@ -9,7 +9,7 @@ namespace TimeProviderExtensions;
 /// <remarks>
 /// Learn more at <see href="https://github.com/egil/TimeProviderExtensions"/>.
 /// </remarks>
-[DebuggerDisplay("UtcNow: {ToString(),nq}. Active timers: {ActiveTimers}. Auto advance amount: {AutoAdvanceAmount,nq}.")]
+[DebuggerDisplay("UtcNow: {ToString(),nq}. Active timers: {ActiveTimers}. {AutoAdvanceBehavior,nq}.")]
 public class ManualTimeProvider : TimeProvider
 {
     internal const uint MaxSupportedTimeout = 0xfffffffe;
@@ -19,7 +19,7 @@ public class ManualTimeProvider : TimeProvider
     private readonly List<ManualTimerScheduler> callbacks = new();
     private DateTimeOffset utcNow;
     private TimeZoneInfo localTimeZone;
-    private TimeSpan autoAdvanceAmount = TimeSpan.Zero;
+    private AutoAdvanceBehavior autoAdvanceBehavior = new AutoAdvanceBehavior();
 
     /// <summary>
     /// Gets the number of active <see cref="ManualTimer"/>, that have callbacks that are scheduled to be triggered at some point in the future.
@@ -32,25 +32,9 @@ public class ManualTimeProvider : TimeProvider
     public DateTimeOffset Start { get; init; }
 
     /// <summary>
-    /// Gets or sets the amount of time by which time advances whenever the clock is read via <see cref="GetUtcNow"/>.
+    /// Gets or sets the auto advance behavior of this <see cref="ManualTimeProvider"/>.
     /// </summary>
-    /// <remarks>
-    /// Set to <see cref="TimeSpan.Zero"/> to disable auto advance. The default value is <see cref="TimeSpan.Zero"/>.
-    /// </remarks>
-    /// <exception cref="ArgumentOutOfRangeException">Thrown when set to a value than <see cref="TimeSpan.Zero"/>.</exception>
-    public TimeSpan AutoAdvanceAmount
-    {
-        get => autoAdvanceAmount;
-        set
-        {
-            if (value < TimeSpan.Zero)
-            {
-                throw new ArgumentOutOfRangeException(nameof(AutoAdvanceAmount), "Auto advance amount cannot be less than zero. ");
-            }
-
-            autoAdvanceAmount = value;
-        }
-    }
+    public AutoAdvanceBehavior AutoAdvanceBehavior { get => autoAdvanceBehavior; set => autoAdvanceBehavior = value ?? new AutoAdvanceBehavior(); }
 
     /// <summary>
     /// Gets the amount by which the value from <see cref="GetTimestamp"/> increments per second.
@@ -120,8 +104,8 @@ public ManualTimeProvider(DateTimeOffset startDateTime, TimeZoneInfo localTimeZo
     /// all according to this <see cref="ManualTimeProvider"/>'s notion of time.
     /// </summary>
     /// <remarks>
-    /// If <see cref="AutoAdvanceAmount"/> is greater than <see cref="TimeSpan.Zero"/>, calling this
-    /// method will move time forward by the amount specified by <see cref="AutoAdvanceAmount"/>.
+    /// If <see cref="AutoAdvanceBehavior.ClockAdvanceAmount"/> is greater than <see cref="TimeSpan.Zero"/>, calling this
+    /// method will move time forward by the amount specified by <see cref="AutoAdvanceBehavior.ClockAdvanceAmount"/>.
     /// The <see cref="DateTimeOffset"/> returned from this method will reflect the time before
     /// the auto advance was applied, if any.
     /// </remarks>
@@ -132,7 +116,7 @@ public override DateTimeOffset GetUtcNow()
         lock (callbacks)
         {
             result = utcNow;
-            Advance(AutoAdvanceAmount);
+            Advance(AutoAdvanceBehavior.ClockAdvanceAmount);
         }
 
         return result;

test/TimeProviderExtensions.Tests/AutoAdvanceBehaviorTests.cs

@@ -0,0 +1,15 @@
+namespace TimeProviderExtensions;
+
+public class AutoAdvanceBehaviorTests
+{
+    [Fact]
+    public void ClockAdvanceAmount_throws_when_lt_zero()
+    {
+        var sut = new AutoAdvanceBehavior();
+
+        var throws = () => sut.ClockAdvanceAmount = TimeSpan.FromTicks(-1);
+
+        throws.Should().Throw<ArgumentOutOfRangeException>()
+            .And.ParamName.Should().Be(nameof(AutoAdvanceBehavior.ClockAdvanceAmount));
+    }
+}

test/TimeProviderExtensions.Tests/ManualTimeProviderTests.cs

@@ -150,7 +150,7 @@ async Task AsyncCallbacks(PeriodicTimer periodicTimer)
     public void Timer_callback_GetUtcNow_AutoAdvance()
     {
         var oneSecond = TimeSpan.FromSeconds(1);
-        var timeProvider = new ManualTimeProvider() { AutoAdvanceAmount = oneSecond };
+        var timeProvider = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = oneSecond } };
 
         using var t1 = timeProvider.CreateTimer(_ =>
         {
@@ -180,16 +180,6 @@ public void Jump_zero()
         sut.GetUtcNow().Should().Be(sut.Start);
     }
 
-    [Fact]
-    public void AutoAdvanceAmount_throws_when_lt_zero()
-    {
-        var sut = new ManualTimeProvider();
-
-        var throws = () => sut.AutoAdvanceAmount = TimeSpan.FromTicks(-1);
-
-        throws.Should().Throw<ArgumentOutOfRangeException>();
-    }
-
     [Fact]
     public void Jump_throws_when_lt_zero()
     {

test/TimeProviderExtensions.Tests/Microsoft.Extensions.Time.Testing.Test/FakeTimeProviderTests.cs

@@ -7,6 +7,7 @@
 
 namespace Microsoft.Extensions.Time.Testing.Test;
 
+using TimeProviderExtensions;
 using FakeTimeProvider = TimeProviderExtensions.ManualTimeProvider;
 
 public class ManualTimeProviderTests
@@ -29,7 +30,7 @@ public void DefaultCtor()
         Assert.Equal(0, now.Millisecond);
         Assert.Equal(TimeSpan.Zero, now.Offset);
         Assert.Equal(10_000_000, frequency);
-        Assert.Equal(TimeSpan.Zero, timeProvider.AutoAdvanceAmount);
+        Assert.Equal(new AutoAdvanceBehavior(), timeProvider.AutoAdvanceBehavior);
 
         var timestamp2 = timeProvider.GetTimestamp();
         var frequency2 = timeProvider.TimestampFrequency;
@@ -59,7 +60,7 @@ public void RichCtor()
         Assert.Equal(TimeSpan.Zero, now.Offset);
         Assert.Equal(8, now.Millisecond);
         Assert.Equal(10_000_000, frequency);
-        Assert.Equal(TimeSpan.Zero, timeProvider.AutoAdvanceAmount);
+        Assert.Equal(new AutoAdvanceBehavior(), timeProvider.AutoAdvanceBehavior);
 
         timeProvider.Advance(TimeSpan.FromMilliseconds(8));
         var pnow2 = timeProvider.GetTimestamp();
@@ -305,10 +306,7 @@ public async Task WaitAsync_Cancel()
     [Fact]
     public void AutoAdvance()
     {
-        var timeProvider = new FakeTimeProvider(DateTimeOffset.UtcNow)
-        {
-            AutoAdvanceAmount = TimeSpan.FromSeconds(1)
-        };
+        var timeProvider = new FakeTimeProvider { AutoAdvanceBehavior = { ClockAdvanceAmount = TimeSpan.FromSeconds(1) } };
 
         var first = timeProvider.GetUtcNow();
         var second = timeProvider.GetUtcNow();
@@ -332,14 +330,11 @@ public void ToString_AutoAdvance_off()
     [Fact]
     public void ToString_AutoAdvance_on()
     {
-        var timeProvider = new FakeTimeProvider
-        {
-            AutoAdvanceAmount = TimeSpan.FromSeconds(1)
-        };
+        var timeProvider = new FakeTimeProvider { AutoAdvanceBehavior = { ClockAdvanceAmount = TimeSpan.FromSeconds(1) } };
 
         _ = timeProvider.ToString();
 
-        timeProvider.AutoAdvanceAmount = TimeSpan.Zero;
+        timeProvider.AutoAdvanceBehavior.ClockAdvanceAmount = TimeSpan.Zero;
         Assert.Equal(timeProvider.Start, timeProvider.GetUtcNow());
     }
 }