[API Proposal]: FakeTimeProvider.Advance

[ArwynFr]

Background and motivation

Currently, FakeTimeProvider.Advance(); returns a void.

When called, it runs all callbacks, for instance continuations of a PeriodicTimer.WaitForNextTickAsync();
However, as soon as these callback hits an await keyword, the thread jumps to the next waiter.
The rest of the calblacks eventually execute, but there is no reliable way to wait for their completion.
I think these waiters should be returned as a Task.WhenAll() awaitable from Advance();

API Proposal

namespace Microsoft.Extensions.Time.Testing;

public class FakeTimeProvider : TimeProvider
{
    public Task Advance(TimeSpan delta);
}

API Usage

[Fact]
public async Task GivenCreatedTransaction_StatusIsAbortedAfterTimeout()
{
    using var client = application.factory.CreateClient().WithAuthenticationAsParkingService();
    var transaction = await client.CreateTransaction().AsTransactionDto();

    await application.TimeProvider.Advance(application.PaymentOptions.TransactionLifetime!.Value);

    var actual = await client!.GetTransaction(transaction!.Guid).AsTransactionDto();
    Assert.Equal(TransactionState.Aborted.ToString(), actual!.State);
}    

Alternative Designs

No response

Risks

No response

[KalleOlaviNiemitalo]

The TimeProvider.CreateTimer method takes a TimerCallback parameter, and that delegate returns void, rather than a Task from which the TimeProvider implementation could detect when the async operations have finished.

I can imagine ways to solve it:

• Add to TimeProvider an overload: public virtual ITimer CreateTimer(Func<object?, Task> callback, object? state, TimeSpan dueTime, TimeSpan period). Override that in FakeTimeProvider. Use that when creating timers for callbacks that start async operations. This would have to go through dotnet/runtime API review.
• Alternatively, make the test call FakeTimeProvider.Advance from within a SynchronizationContext that overrides OperationStarted() and OperationCompleted() to count whether there's still something in progress. These are then called from System.Runtime.CompilerServices.AsyncVoidMethodBuilder, so if the TimerCallback refers to an async void function, then the custom SynchronizationContext can detect the completion.