feat: Enable auto advance feature for GetTimestamp() and GetElapsedTime(long)

Author: egil

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Replace `AutoAdvanceAmount` property with the `AutoAdvanceBehavior` property on `ManualTimeProvider`, and introduced the `AutoAdvanceBehavior` type.
 
+- Enable auto advance feature for `GetTimestamp()` and `GetElapsedTime(long)`.
+
 ## [1.0.0-rc.1]
 
 - Updated Microsoft.Bcl.TimeProvider package dependency to rc.1 version.

docs/TimeProviderExtensions.AutoAdvanceBehavior.md

@@ -19,7 +19,8 @@ Implements [System.IEquatable<](https://docs.microsoft.com/en-us/dotnet/api/S
 
 ## 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').
+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; }
@@ -33,5 +34,27 @@ public System.TimeSpan ClockAdvanceAmount { get; set; }
 [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').
+
+<a name='TimeProviderExtensions.AutoAdvanceBehavior.TimestampAdvanceAmount'></a>
+
+## AutoAdvanceBehavior.TimestampAdvanceAmount Property
+
+Gets or sets the amount of time by which time advances whenever the a timestamp is read via [System.TimeProvider.GetTimestamp](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider.GetTimestamp 'System.TimeProvider.GetTimestamp')
+or an elapsed time is calculated with [System.TimeProvider.GetElapsedTime(System.Int64)](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider.GetElapsedTime#System_TimeProvider_GetElapsedTime_System_Int64_ 'System.TimeProvider.GetElapsedTime(System.Int64)').
+
+```csharp
+public System.TimeSpan TimestampAdvanceAmount { 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

@@ -323,9 +323,15 @@ public override long GetTimestamp();
 A long integer representing the high-frequency counter value of the underlying timer mechanism.
 
 ### Remarks
+
 This implementation bases timestamp on [System.DateTimeOffset.UtcTicks](https://docs.microsoft.com/en-us/dotnet/api/System.DateTimeOffset.UtcTicks 'System.DateTimeOffset.UtcTicks'),
 since the progression of time is represented by the date and time returned from [GetUtcNow()](TimeProviderExtensions.ManualTimeProvider.md#TimeProviderExtensions.ManualTimeProvider.GetUtcNow() 'TimeProviderExtensions.ManualTimeProvider.GetUtcNow()').
 
+If [TimestampAdvanceAmount](TimeProviderExtensions.AutoAdvanceBehavior.md#TimeProviderExtensions.AutoAdvanceBehavior.TimestampAdvanceAmount 'TimeProviderExtensions.AutoAdvanceBehavior.TimestampAdvanceAmount') 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 [TimestampAdvanceAmount](TimeProviderExtensions.AutoAdvanceBehavior.md#TimeProviderExtensions.AutoAdvanceBehavior.TimestampAdvanceAmount 'TimeProviderExtensions.AutoAdvanceBehavior.TimestampAdvanceAmount').
+The [long](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/long 'https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/long') returned from this method will reflect the timestamp before
+the auto advance was applied, if any.
+
 <a name='TimeProviderExtensions.ManualTimeProvider.GetUtcNow()'></a>
 
 ## ManualTimeProvider.GetUtcNow() Method
@@ -342,8 +348,8 @@ public override System.DateTimeOffset GetUtcNow();
 [System.DateTimeOffset](https://docs.microsoft.com/en-us/dotnet/api/System.DateTimeOffset 'System.DateTimeOffset')
 
 ### Remarks
-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').
+If [ClockAdvanceAmount](TimeProviderExtensions.AutoAdvanceBehavior.md#TimeProviderExtensions.AutoAdvanceBehavior.ClockAdvanceAmount 'TimeProviderExtensions.AutoAdvanceBehavior.ClockAdvanceAmount') 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 [ClockAdvanceAmount](TimeProviderExtensions.AutoAdvanceBehavior.md#TimeProviderExtensions.AutoAdvanceBehavior.ClockAdvanceAmount 'TimeProviderExtensions.AutoAdvanceBehavior.ClockAdvanceAmount').
 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.
 

src/TimeProviderExtensions/AutoAdvanceBehavior.cs

@@ -8,16 +8,28 @@ namespace TimeProviderExtensions;
 public sealed record class AutoAdvanceBehavior
 {
     private TimeSpan clockAdvanceAmount = TimeSpan.Zero;
+    private TimeSpan timestampAdvanceAmount = 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"/>.
+    /// 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; } }
 
+    /// <summary>
+    /// Gets or sets the amount of time by which time advances whenever the a timestamp is read via <see cref="TimeProvider.GetTimestamp"/>
+    /// or an elapsed time is calculated with <see cref="TimeProvider.GetElapsedTime(long)"/>.
+    /// </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 TimestampAdvanceAmount { get => timestampAdvanceAmount; set { ThrowIfLessThanZero(value); timestampAdvanceAmount = value; } }
+
     private static void ThrowIfLessThanZero(TimeSpan value, [CallerMemberName] string? parameterName = null)
     {
         if (value < TimeSpan.Zero)

src/TimeProviderExtensions/ManualTimeProvider.cs

@@ -93,10 +93,29 @@ public ManualTimeProvider(DateTimeOffset startDateTime, TimeZoneInfo localTimeZo
     /// </summary>
     /// <returns>A long integer representing the high-frequency counter value of the underlying timer mechanism.</returns>
     /// <remarks>
+    /// <para>
     /// This implementation bases timestamp on <see cref="DateTimeOffset.UtcTicks"/>,
     /// since the progression of time is represented by the date and time returned from <see cref="GetUtcNow()" />.
+    /// </para>
+    /// <para>
+    /// If <see cref="AutoAdvanceBehavior.TimestampAdvanceAmount"/> is greater than <see cref="TimeSpan.Zero"/>, calling this
+    /// method will move time forward by the amount specified by <see cref="AutoAdvanceBehavior.TimestampAdvanceAmount"/>.
+    /// The <see langword="long"/> returned from this method will reflect the timestamp before
+    /// the auto advance was applied, if any.
+    /// </para>
     /// </remarks>
-    public override long GetTimestamp() => utcNow.UtcTicks;
+    public override long GetTimestamp()
+    {
+        long result;
+
+        lock (callbacks)
+        {
+            result = utcNow.UtcTicks;
+            Advance(AutoAdvanceBehavior.TimestampAdvanceAmount);
+        }
+
+        return result;
+    }
 
     /// <summary>
     /// Gets a <see cref="DateTimeOffset"/> value whose date and time are set to the current

test/TimeProviderExtensions.Tests/AutoAdvanceBehaviorTests.cs

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

test/TimeProviderExtensions.Tests/ManualTimeProviderTests.cs

@@ -150,14 +150,59 @@ async Task AsyncCallbacks(PeriodicTimer periodicTimer)
     public void Timer_callback_GetUtcNow_AutoAdvance()
     {
         var oneSecond = TimeSpan.FromSeconds(1);
-        var timeProvider = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = oneSecond } };
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = oneSecond } };
 
-        using var t1 = timeProvider.CreateTimer(_ =>
+        using var t1 = sut.CreateTimer(_ =>
         {
-            timeProvider.GetUtcNow();
+            sut.GetUtcNow();
         }, null, TimeSpan.Zero, oneSecond);
 
-        timeProvider.GetUtcNow().Should().Be(timeProvider.Start + oneSecond);
+        sut.GetUtcNow().Should().Be(sut.Start + oneSecond);
+    }
+
+    [Fact]
+    public void GetUtcNow_with_ClockAdvanceAmount_gt_zero()
+    {
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = 1.Seconds() } };
+
+        var result = sut.GetUtcNow();
+
+        result.Should().Be(sut.Start);
+        sut.GetUtcNow().Should().Be(sut.Start + 1.Seconds());
+    }
+
+    [Fact]
+    public void GetLocalNow_with_ClockAdvanceAmount_gt_zero()
+    {
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = 1.Seconds() } };
+
+        var result = sut.GetLocalNow();
+
+        result.Should().Be(sut.Start);
+        sut.GetLocalNow().Should().Be(sut.Start + 1.Seconds());
+    }
+
+    [Fact]
+    public void GetTimestamp_with_TimestampAdvanceAmount_gt_zero()
+    {
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { TimestampAdvanceAmount = 1.Seconds() } };
+
+        var result = sut.GetTimestamp();
+
+        result.Should().Be(sut.Start.Ticks);
+        sut.GetTimestamp().Should().Be(result + 1.Seconds().Ticks);
+    }
+
+    [Fact]
+    public void GetElapsedTime_with_TimestampAdvanceAmount_gt_zero()
+    {
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { TimestampAdvanceAmount = 1.Seconds() } };
+        var start = sut.Start.Ticks;
+
+        var result = sut.GetElapsedTime(start);
+
+        result.Should().Be(0.Seconds());
+        sut.GetElapsedTime(start).Should().Be(1.Seconds());
     }
 
     [Fact]