search

dotnet / runtime

.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.
https://docs.microsoft.com/dotnet/core/
MIT License
15.45k stars 4.76k forks source link

API to provide the current system time #36617

Closed YohDeadfall closed 1 year ago

YohDeadfall commented 4 years ago

This proposal is edited by @tarekgh

Proposal

The aim of this proposal is to introduce time abstraction. This abstraction will include the ability to retrieve the system date and time, either in UTC or local time, as well as timestamps for use in performance or tagging scenarios. Additionally, this abstraction can be used in the Task operations like WaitAsync and CancellationTokenSource CancelAfter. By introducing this new abstraction, it will become possible to replace other existing abstractions that are currently being used in a nonuniform way across various interfaces such as ISystemClock and ITimer. The following are some examples of such interfaces:

In addition, this new abstraction will enable the creation of tests that can mock time functionality, providing greater flexibility in testing through the ability to customize time operations.

Below are some design notes to consider:

APIs proposal

APIs for .NET 8.0 and Down-levels

namespace System
{
    /// <summary>Provides an abstraction for time. </summary>
    public abstract class TimeProvider
    {
        /// <summary>Initializes the instance. </summary>
        protected TimeProvider();

        /// <summary>
        /// Gets a <see cref="TimeProvider"/> that provides a clock based on <see cref="DateTimeOffset.UtcNow"/>,
        /// a time zone based on <see cref="TimeZoneInfo.Local"/>, a high-performance time stamp based on <see cref="Stopwatch"/>,
        /// and a timer based on <see cref="Timer"/>.
        /// </summary>
        public static TimeProvider System { get; }

        /// <summary>
        /// Creates a <see cref="TimeProvider"/> that provides a clock based on <see cref="DateTimeOffset.UtcNow"/>,
        /// a time zone based on <paramref name="timeZone"/>, a high-performance time stamp based on <see cref="Stopwatch"/>,
        /// and a timer based on <see cref="Timer"/>.
        /// </summary>
        public static TimeProvider FromLocalTimeZone(TimeZoneInfo timeZone);

        /// <summary>
        /// Gets a <see cref="DateTimeOffset"/> value whose date and time are set to the current
        /// Coordinated Universal Time (UTC) date and time and whose offset is Zero,
        /// all according to this <see cref="TimeProvider"/>'s notion of time.
        /// </summary>
        public abstract DateTimeOffset UtcNow { get; }

        /// <summary>
        /// Gets a <see cref="DateTimeOffset"/> value that is set to the current date and time according to this <see cref="TimeProvider"/>'s
        /// notion of time based on <see cref="UtcNow"/>, with the offset set to the <see cref="LocalTimeZone"/>'s offset from Coordinated Universal Time (UTC).
        /// </summary>
        public DateTimeOffset LocalNow { get; }

        /// <summary>Gets a <see cref="TimeZoneInfo"/> object that represents the local time zone according to this <see cref="TimeProvider"/>'s notion of time. </summary>
        public abstract TimeZoneInfo LocalTimeZone { get; }

        /// <summary>Gets the current high-frequency value designed to measure small time intervals with high accuracy in the timer mechanism. </summary>
        /// <returns>A long integer representing the high-frequency counter value of the underlying timer mechanism. </returns>
        public abstract long GetTimestamp();

        /// <summary>Gets the frequency of <see cref="GetTimestamp"/> of high-frequency value per second. </summary>
        public abstract long TimestampFrequency { get; }

        /// <summary>Gets the elapsed time between two timestamps retrieved using <see cref="GetTimestamp"/>. </summary>
        /// <param name="startingTimestamp">The timestamp marking the beginning of the time period. </param>
        /// <param name="endingTimestamp">The timestamp marking the end of the time period. </param>
        /// <returns>A <see cref="TimeSpan"/> for the elapsed time between the starting and ending timestamps. </returns>
        public TimeSpan GetElapsedTime(long startingTimestamp, long endingTimestamp);

        /// <summary>Creates a new <see cref="ITimer"/> instance, using <see cref="TimeSpan"/> values to measure time intervals. </summary>
        /// <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="dueTime">The amount of time to delay before <paramref name="callback"/> is invoked. Specify <see cref="Timeout.InfiniteTimeSpan"/> to prevent the timer from starting. Specify <see cref="TimeSpan.Zero"/> to start the timer immediately. </param>
        /// <param name="period">The time interval between invocations of <paramref name="callback"/>. Specify <see cref="Timeout.InfiniteTimeSpan"/> to disable periodic signaling. </param>
        /// <returns>The newly created <see cref="ITimer"/> instance. </returns>
        /// <exception cref="ArgumentNullException"><paramref name="callback"/> is null. </exception>
        /// <exception cref="ArgumentOutOfRangeException">The number of milliseconds in the value of <paramref name="dueTime"/> or <paramref name="period"/> is negative and not equal to <see cref="Timeout.Infinite"/>, or is greater than <see cref="int.MaxValue"/>. </exception>
        /// <remarks>
        /// <para>
        /// The delegate specified by the callback parameter is invoked once after <paramref name="dueTime"/> elapses, and thereafter each time the <paramref name="period"/> time interval elapses.
        /// </para>
        /// <para>
        /// If <paramref name="dueTime"/> is zero, the callback is invoked immediately. If <paramref name="dueTime"/> is -1 milliseconds, <paramref name="callback"/> is not invoked; the timer is disabled,
        /// but can be re-enabled by calling the <see cref="ITimer.Change"/> method.
        /// </para>
        /// <para>
        /// If <paramref name="period"/> is 0 or -1 milliseconds and <paramref name="dueTime"/> is positive, <paramref name="callback"/> is invoked once; the periodic behavior of the timer is disabled,
        /// but can be re-enabled using the <see cref="ITimer.Change"/> method.
        /// </para>
        /// <para>
        /// The return <see cref="ITimer"/> instance will be implicitly rooted while the timer is still scheduled.
        /// </para>
        /// <para>
        /// <see cref="CreateTimer"/> captures the <see cref="ExecutionContext"/> and stores that with the <see cref="ITimer"/> for use in invoking <paramref name="callback"/>
        /// each time it's called.  That capture can be suppressed with <see cref="ExecutionContext.SuppressFlow"/>.
        /// </para>
        /// </remarks>
        public abstract ITimer CreateTimer(TimerCallback callback, object? state, TimeSpan dueTime, TimeSpan period);
    }
}
namespace System.Threading
{
    /// <summary>Represents a timer that can have its due time and period changed. </summary>
    /// <remarks>
    /// Implementations of <see cref="Change"/>, <see cref="IDisposable.Dispose"/>, and <see cref="IAsyncDisposable.DisposeAsync"/>
    /// must all be thread-safe such that the timer instance may be accessed concurrently from multiple threads.
    /// </remarks>
    public interface ITimer : IDisposable, IAsyncDisposable
    {
        /// <summary>Changes the start time and the interval between method invocations for a timer, using <see cref="TimeSpan"/> values to measure time intervals. </summary>
        /// <param name="dueTime">
        /// A <see cref="TimeSpan"/> representing the amount of time to delay before invoking the callback method specified when the <see cref="ITimer"/> was constructed.
        /// Specify <see cref="Timeout.InfiniteTimeSpan"/> to prevent the timer from restarting. Specify <see cref="TimeSpan.Zero"/> to restart the timer immediately.
        /// </param>
        /// <param name="period">
        /// The time interval between invocations of the callback method specified when the Timer was constructed.
        /// Specify <see cref="Timeout.InfiniteTimeSpan"/> to disable periodic signaling.
        /// </param>
        /// <returns><see langword="true"/> if the timer was successfully updated; otherwise, <see langword="false"/>. </returns>
        /// <exception cref="ObjectDisposedException">The timer has already been disposed. </exception>
        /// <exception cref="ArgumentOutOfRangeException">The <paramref name="dueTime"/> or <paramref name="period"/> parameter, in milliseconds, is less than -1 or greater than 4294967294. </exception>
        bool Change(TimeSpan dueTime, TimeSpan period);
    }

APIs for .NET 8.0 Only

namespace System.Threading
{
-   public sealed class Timer : MarshalByRefObject, IDisposable, IAsyncDisposable
+  public sealed class Timer : MarshalByRefObject, IDisposable, IAsyncDisposable, ITimer
    {
    }

    public class CancellationTokenSource : IDisposable
    {
+        /// <summary>Initializes a new instance of the <see cref="CancellationTokenSource"/> class that will be canceled after the specified <see cref="TimeSpan"/>. </summary>
+        /// <param name="delay">The time interval to wait before canceling this <see cref="CancellationTokenSource"/>. </param>
+        /// <param name="timeProvider">The <see cref="TimeProvider"/> with which to interpret the <paramref name="delay"/>. </param>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="delay"/>'s <see cref="TimeSpan.TotalMilliseconds"/> is less than -1 or greater than <see cref="uint.MaxValue"/> - 1. </exception>
+        /// <exception cref="ArgumentNullException"><paramref name="timeProvider"/> is null. </exception>
+        /// <remarks>
+        /// The countdown for the delay starts during the call to the constructor.  When the delay expires,
+        /// the constructed <see cref="CancellationTokenSource"/> is canceled, if it has
+        /// not been canceled already. Subsequent calls to CancelAfter will reset the delay for the constructed
+        /// <see cref="CancellationTokenSource"/>, if it has not been canceled already.
+        /// </remarks>
+        public CancellationTokenSource(TimeSpan delay, TimeProvider timeProvider);
    }

    public sealed class PeriodicTimer : IDisposable
    {
+        /// <summary>Initializes the timer. </summary>
+        /// <param name="period">The time interval between returning the next enumerated value.</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>
+        public PeriodicTimer(TimeSpan period, TimeProvider timeProvider);
    }
}

namespace System.Threading.Tasks
{
    public class Task<TResult> : Task
    {
+        /// <summary>Gets a <see cref="Task{TResult}"/> that will complete when this <see cref="Task{TResult}"/> completes or when the specified timeout expires. </summary>
+        /// <param name="timeout">The timeout after which the <see cref="Task"/> should be faulted with a <see cref="TimeoutException"/> if it hasn't otherwise completed. </param>
+        /// <param name="timeProvider">The <see cref="TimeProvider"/> with which to interpret <paramref name="timeout"/>. </param>
+        /// <returns>The <see cref="Task{TResult}"/> representing the asynchronous wait.  It may or may not be the same instance as the current instance. </returns>
+        public new Task<TResult> WaitAsync(TimeSpan timeout, TimeProvider timeProvider);

+        /// <summary>Gets a <see cref="Task{TResult}"/> that will complete when this <see cref="Task{TResult}"/> completes, when the specified timeout expires, or when the specified <see cref="CancellationToken"/> has cancellation requested. </summary>
+        /// <param name="timeout">The timeout after which the <see cref="Task"/> should be faulted with a <see cref="TimeoutException"/> if it hasn't otherwise completed. </param>
+        /// <param name="timeProvider">The <see cref="TimeProvider"/> with which to interpret <paramref name="timeout"/>. </param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for a cancellation request. </param>
+        /// <returns>The <see cref="Task{TResult}"/> representing the asynchronous wait.  It may or may not be the same instance as the current instance. </returns>
+        public new Task<TResult> WaitAsync(TimeSpan timeout, TimeProvider timeProvider, CancellationToken cancellationToken);
    }

    public class Task : IAsyncResult, IDisposable
    {
+        /// <summary>Gets a <see cref="Task"/> that will complete when this <see cref="Task"/> completes or when the specified timeout expires. </summary>
+        /// <param name="timeout">The timeout after which the <see cref="Task"/> should be faulted with a <see cref="TimeoutException"/> if it hasn't otherwise completed. </param>
+        /// <param name="timeProvider">The <see cref="TimeProvider"/> with which to interpret <paramref name="timeout"/>. </param>
+        /// <returns>The <see cref="Task"/> representing the asynchronous wait.  It may or may not be the same instance as the current instance. </returns>
+        public Task WaitAsync(TimeSpan timeout, TimeProvider timeProvider);

+        /// <summary>Gets a <see cref="Task"/> that will complete when this <see cref="Task"/> completes, when the specified timeout expires, or when the specified <see cref="CancellationToken"/> has cancellation requested. </summary>
+        /// <param name="timeout">The timeout after which the <see cref="Task"/> should be faulted with a <see cref="TimeoutException"/> if it hasn't otherwise completed. </param>
+        /// <param name="timeProvider">The <see cref="TimeProvider"/> with which to interpret <paramref name="timeout"/>. </param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for a cancellation request. </param>
+        /// <returns>The <see cref="Task"/> representing the asynchronous wait.  It may or may not be the same instance as the current instance. </returns>
+        public Task WaitAsync(TimeSpan timeout, TimeProvider timeProvider, CancellationToken cancellationToken);
    }
}

APIs for down-level Only

namespace System.Threading.Tasks
{
    public static class TimeProviderTaskExtensions
    {
        public static async Task<TResult> WaitAsync<TResult>(this Task<TResult> task, TimeSpan timeout, TimeProvider timeProvider);
        public static async Task<TResult> WaitAsync<TResult>(this Task<TResult> task, TimeSpan timeout, TimeProvider timeProvider, CancellationToken cancellationToken);
        public static async Task WaitAsync(this Task task, TimeSpan timeout, TimeProvider timeProvider);
        public static async Task WaitAsync(this Task task, TimeSpan timeout, TimeProvider timeProvider, CancellationToken cancellationToken);

    }

Possible APIs addition for .NET 8.0 and down-level

namespace System.Threading.Tasks
{
    public static class TimeProviderTaskExtensions
    {

        /// <summary>Initializes a new instance of the <see cref="CancellationTokenSource"/> class that will be canceled after the specified <see cref="TimeSpan"/>. </summary>
        /// <param name="timeProvider">The <see cref="TimeProvider"/> with which to interpret the <paramref name="delay"/>. </param>
        /// <param name="delay">The time interval to wait before canceling this <see cref="CancellationTokenSource"/>. </param>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="delay"/>'s <see cref="TimeSpan.TotalMilliseconds"/> is less than -1 or greater than <see cref="uint.MaxValue"/> - 1. </exception>
        /// <remarks>
        /// The countdown for the delay starts during the call to the constructor.  When the delay expires,
        /// the constructed <see cref="CancellationTokenSource"/> is canceled, if it has
        /// not been canceled already. Subsequent calls to CancelAfter will reset the delay for the constructed
        /// <see cref="CancellationTokenSource"/>, if it has not been canceled already.
        /// </remarks>
        public static CancellationTokenSource CreateCancellationTokenSource(this TimeProvider timeProvider, TimeSpan delay) ;
    }
}

End of the @tarekgh edit

The Original Proposal

Motivation

The ISystemClock interface exists in:

There is a small difference exists between implementations, but in most cases it can be moved out. In case of Kestrel's clock which has a specific logic inside, there could be made a new interface IScopedSystemClock which will provide the scope start time as UtcNow does now. Therefore, looks like all of them could be merged into a single class/interface and put into Microsoft.Extensions.Primitives.

The same interface often implemented by developers themselves to be used by microservices and applications utilizing dependency injection.

Having a common implementation of the data provider pattern will free users from repeating the same simple code many times and will allow to test apps in conjunction with ASP.NET internals without changing an environment.

Proposed API

The ISystemClock defines a way to get the current time in UTC timezone, and it has a simple implementation:

public interface ISystemClock
{
    DateTimeOffset UtcNow { get; }
}

public class SystemClock : ISystemClock
{
    public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
}

Originally proposed in dotnet/aspnetcore#16844.

Clockwork-Muse commented 2 years ago

The vast majority of cases should be covered by current time + current timezone;

using System;

public interface IClock
{
    public abstract DateTimeOffset UtcNow {get;}

    // I'm explicitly including this because otherwise it usually results in relying on the implicit zone from the culture.
    // This makes dealing with "current local time" much easier in server scenarios handling multiple cultures/users.
    public abstract TimeZoneInfo Zone {get;}
}

... for some additional cases it may be worth considering system/process time...

public abstract long TickCount64 {get;}

(this one in theory enables at least some timer-related uses to be based on this, but that is non-trivial and quite likely to break something)

dazinator commented 2 years ago

@geeknoid

Replacing just the "get time" function is completely insufficient to ensure robust tests. Code does things like waiting for tasks to complete with a timeout. The timeout that is used follows wall-clock time so it needs to be virtualized.

One issue with code that is waiting on Task's is that there are many Task's created and awaited in applications, and I see these as being more part of the execution environment as opposed directly related with a clock. A Task.Delay seems special in your case because it sounds like you need to take control of it because its linked with time, and you want to control time. One way to control time is (flux capacitor!) to do both of the following:-

  1. If we have the simple IClock that returns current time you can mock that
  2. Somehow, take control of the Task.Delay so you can make it return early as if the time had passed at test time.

Both these are possible today by refactoring code for testability, but I think this issue is about promoting something that will help solve these issues in a common way, so refactoring isn't going to be encountered as often - via some agreed standards / interfaces etc.

With that in mind, I'm imagining a kind of Delay task factory, so a bit like what we are proposing here with IClock but the guidance would be if you want to do Task.Delay we'd warn against that and instead inject the IDelayFactory (or whatever it's called) and use that to delay - this would support mocking so you could return task's that you control at test time.

As a more of a pie in the sky runtime idea - I was also imagining a runtime level feature where you could switch something on with the runtime, that meant that every Task that was running in the environment became accessible via some environmental service that could be used during testing, so that there were ways to access specific tasks's and trigger them to return results prematurely - not sure whether such a thing is really desirable or possible though ;-) - it could be pretty chaotic.

geeknoid commented 2 years ago

There are many ways .NET delivers functionality that derives from wall-clock time: getting the time, waiting for time, various timer abstractions, various timeout semantics, etc. I want to control all of these through a single common clock, where I control the passage of time within my test process.

Aside from I/O completion, the forward movement of time is the other primary source of non-determinism in a process. The key to reliable and systematic testing is to eliminate non-determinism in your tests. We use mocks and fake services to eliminate non-determinism in I/O, but there currently isn't a mechanism to eliminate non-determinism introduced by the passage of time. This makes it considerably more difficult to write tests that are reliable and that provide 100% test coverage (since hitting some time-related edge cases in your code can be nearly impossible).

So what I'm really after here is an effective way to test, given the non-determinism of wall-clock time.

Clockwork-Muse commented 2 years ago

I want to control all of these through a single common clock

You can't, because as was previously mentioned some of the timeouts get pushed below the runtime, into the OS/hardware. And even some of those that refer back to runtime-space clocks for related behaviour can still be relying on external functionality for the timing.
Further, without completely rearchitecting significant portions of the runtime it's likely that this would introduce hidden implementation dependencies on the clock; you'd have to know what methods were being called on the clock to be able to control them, which makes it brittle.

Generally, I think people generally get around this in tests by making the timeouts configurable (and setting a low value), or pushing the timeouts into whatever other part is being mocked/injected, which generally also simplifies testing as well.

tarekgh commented 2 years ago

What about doing the following:

    public interface IClock
    {
        DateTimeOffset UtcNow { get; }

        // We can think adding Time Zone or related thing we think is important enough for retrieving the time from the clock
    }

    public interface IStoppableClock : IClock // We can decide better name than IStoppableClock so I am not discussing naming for now :-)
    {
        // Add here all interfaces for handling timers, periods...etc.
    }

The benefits are:

If the main idea here is reasonable, we can start digging the details as needed.

julealgon commented 2 years ago

What about doing the following:

    public interface IClock
    {
        DateTimeOffset UtcNow { get; }

        // We can think adding Time Zone or related thing we think is important enough for retrieving the time from the clock
    }

    public interface IStoppableClock : IClock // We can decide better name than IStoppableClock so I am not discussing naming for now :-)
    {
        // Add here all interfaces for handling timers, periods...etc.
    }

The benefits are:

  • IClock is still simple and satisfies most of the scenarios needed today. Users can easily implement that.
  • IStoppableClock can satisfy more specialized clocks which can be used for other needed scenarios.
  • IStoppableClock can still be used in simple scenarios as it is implementing IClock.
  • Concrete implantation can be provided for common cases (like SystemClock, SystemStoppableClock, CustomizedStoppableClock ...etc).

If the main idea here is reasonable, we can start digging the details as needed.

@tarekgh

I'd rather see something like this without the interface inheritance:

    public interface IClock
    {
        DateTimeOffset UtcNow { get; }
    }

    public interface IAlarm
    {
        // Add here all interfaces for handling timers, periods...etc.
    }

And then a concrete implementation:

public class AlarmClock : IClock, IAlarm
dazinator commented 2 years ago

@tarekgh - I'd agree in general, but just wanted to add that it may then be better to then split the new interface up into multiple seperate ones depending on the api's it's intended to house - for example, Task related stuff (such as delay's) vs Timer related (there are different timers in different namespaces etc). This could form a set of services and you'd need to use the correct one/s for your scenarios. This may end up quite granular but I think it would be factored better to align with dependencies.

bartonjs commented 2 years ago

For what it's worth, I don't expect this to pass API Review if proposed as interfaces.

public class Clock
{
    public virtual DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
    ...
}

is more likely (though we'd almost certainly want a the class name to have two words as "Clock" is a bit of an over-reach)... so I'll throw out TimeProvider as a strawman).

tarekgh commented 2 years ago

@julealgon

I'd rather see something like this without the interface inheritance:

I want to have the fact that IAlarm depends on IClock in general and not just the concrete implementation. Not having such a relationship in the interface can cause some of IAlram APIs need to have IClock parameters I guess.

@dazinator

then split the new interface up into multiple seperate ones depending on the api's it's intended to house

This is helpful feedback. At the same time, I want to reduce exposure to many interfaces which are mostly related to each other and can cause some complications. So, we can look carefully at which functionality can fit in the proposed interfaces and which can fit in some other places or new interfaces. IMHO using Task stuff inside the timer interface is still ok as I am viewing Task as a concept/type which can be used anywhere and not necessarily be part of Task special types.

@bartonjs

Thanks for the design tips we need to consider when we start working on the actual proposal.

mattjohnsonpint commented 2 years ago

A few thoughts:

Thus, I propose:

public interface IUtcTimeProvider
{
    public DateTimeOffset GetUtcTime();
}

public interface ILocalTimeProvider
{
    public TimeZoneInfo TimeZone { get; }
    public DateTimeOffset GetLocalTime();
}

A possible concrete implementation for the real time would be:

public class SystemTimeProvider : ILocalTimeProvider, IUtcTimeProvider
{
    public static SystemTimeProvider Instance { get; } = new();
    private SystemTimeProvider() { }

    public TimeZoneInfo TimeZone => TimeZoneInfo.Local;
    public DateTimeOffset GetLocalTime() => DateTimeOffset.Now;
    public DateTimeOffset GetUtcTime() => DateTimeOffset.UtcNow;
}

One possible concrete implementation to be used during testing, with behavior of only a single fixed point in time, would be:

public class FixedTimeProvider : ILocalTimeProvider, IUtcTimeProvider
{
    private readonly DateTimeOffset _utcTime;

    public FixedTimeProvider(DateTimeOffset time, TimeZoneInfo? timeZone = default)
    {
        _utcTime = time.ToUniversalTime();
        TimeZone = timeZone ?? TimeZoneInfo.Local;
    }

    public TimeZoneInfo TimeZone { get; }
    public DateTimeOffset GetLocalTime() => TimeZoneInfo.ConvertTime(_utcTime, TimeZone);
    public DateTimeOffset GetUtcTime() => _utcTime;
}

This also helps separate applications that legitimately use local time (such as desktop or mobile apps) from application that should probably only use UTC. For example, an ASP.NET Core web controller might inject IUtcTimeProvider into their controller, where a MAUI app might inject an ILocalTimeProvider.

tarekgh commented 2 years ago

@mattjohnsonpint

I'm not sure what members would be on IAlarm

Most of the functionality requested in this comment https://github.com/dotnet/runtime/issues/36617#issuecomment-1302734728. Naming is a different issue, so we don't have to stick with Alram if you think it is confusing.

I agree that mocking the local time zone could be useful. I would expect that on a separate interface

What is the benefit of splitting that? If someone exposes a new API that wants to have it to work with time, it will not be good to have this API taking 2-time provider parameters instead of just one. I expect the API will take the interfaces and not use the concrete types.

I think @bartonjs was pointing to not use interfaces and instead use class with virtual members. We can clarify that.

bartonjs commented 2 years ago

I think @bartonjs was pointing to not use interfaces and instead use class with virtual members. We can clarify that.

Correct.

Several quotes from Framework Design Guidelines, 3rd edition:

4.3 Choosing Between Class and Interface

In general, classes are the preferred construct for exposing abstractions. ...

DO favor defining classes over interfaces.

DO use abstract classes instead of interfaces to decouple the contract from implementations.

RICO MARIANI: Good interface candidates often have this “mix in” feel to them. All sorts of objects can be IFormattable—it isn’t restricted to a certain subtype. It’s more like a type attribute. Other times we have interfaces that look more like they should be classes—IFormatProvider springs to mind. The fact that the interface’s name ended in "er" speaks volumes.

JEREMY BARTON: One hint that Jeffrey’s "can-do" paradigm is being followed is when the interface ends in the suffix "able." For example, IDisposable can be loosely rewritten "a thing that can do Dispose." If we compare this to ICryptoTransform, that interface isn’t describing a capability; it’s instead defining a set of related actions. When we added System.Span<T> in .NET Core 2.0, we found that we couldn’t add Span support to symmetric cryptography because we used an interface instead of an abstract base class. It may have taken 15 years to realize that it was a mistake to have that type as an interface, but it was nonetheless a mistake.

Since it doesn't make sense as IClockable, it shouldn't be an interface; but rather designed as an unsealed class with virtual members.

mattjohnsonpint commented 2 years ago

Ok, I understand now. How about something like this then?

public class TimeProvider
{
    public static TimeProvider Default = new();

    public TimeProvider(TimeZoneInfo? timeZone = default)
    {
        TimeZone = timeZone ?? TimeZoneInfo.Local;
    }

    public TimeProvider(string timeZoneId)
    {
        TimeZone = TimeZoneInfo.FindSystemTimeZoneById(timeZoneId);
    }

    public TimeZoneInfo TimeZone { get; init; }
    public DateTimeOffset GetLocalTime() => TimeZoneInfo.ConvertTime(GetUtcTime(), TimeZone);
    public virtual DateTimeOffset GetUtcTime() => DateTimeOffset.UtcNow;
}

A possible fixed-time implementation, overriding the virtual GetUtcTime method:

public class FixedTimeProvider : TimeProvider
{
    private readonly DateTimeOffset _utcTime;

    public FixedTimeProvider(DateTimeOffset time, TimeZoneInfo? timeZone = default)
        : base(timeZone)
    {
        _utcTime = time.ToUniversalTime();
    }

    public FixedTimeProvider(DateTimeOffset time, string timeZoneId)
        : base(timeZoneId)
    {
        _utcTime = time.ToUniversalTime();
    }

    public override DateTimeOffset GetUtcTime() => _utcTime;
}
tarekgh commented 2 years ago

@mattjohnsonpint this going same direction I am proposing. We can talk about the details when we create the full proposal as we are missing the TimerProvider or whatever we'll call it.

mattjohnsonpint commented 2 years ago

If there is to be a discussion about TimerProvider (or whatever it will be called), can it please move to another proposal? We've already said a few times that they are separate things. I don't want to wait for a whole other debate for something that has already taken 2.5 years to get this far.

bartonjs commented 2 years ago

If there is to be a discussion about TimerProvider (or whatever it will be called), can it please move to another proposal? We've already said a few times that they are separate things

What is "they"? IClock vs. TimeProvider? They're the same thing. interface IClock isn't consistent with the design guidelines for the base class layer (as quoted), class TimeProvider is the shape that it would need to make progress. (Maybe I'm wrong, and everyone else in the review group would think an interface is natural and correct here; but to me it feels pretty solidly against our design guidelines)

mattjohnsonpint commented 2 years ago

By "they", I meant TimeProvider vs TimerProvider. This proposal being about an API to provide the current system time, abstracting DateTime.UtcNow and the like. A proposal for abstracting Task.Delay and other timers shouldn't creep in to this proposal, IMHO.

bartonjs commented 2 years ago

Ah, I missed the r in Timer, sorry. (I choose to blame it on learning to "ignore" adjectival declension suffixes from German. And now all Deutschsprachen Deutschsprachige can roll their eyes at me.)

mattjohnsonpint commented 2 years ago

All good.

Actually, the framework guidance about the "able" suffix is quite useful here, and I think bifurcates the two nicely. One wouldn't say that a clock is "clockable", but one might say that a task is "delayable". So perhaps TimeProvider for this proposal, and something like IDelayable for a separate proposal?

tarekgh commented 2 years ago

and other timers shouldn't creep in to this proposal, IMHO.

@mattjohnsonpint as @stephentoub mentioned in the comment https://github.com/dotnet/runtime/issues/36617#issuecomment-1307558843 both abstracts we want to have been related and it is good to design them together. No worries, we are doing a good progress here and we'll keep it up :-)

ChadNedzlek commented 2 years ago

I'm trying to wrap my head around all the proposals. It sounds like step one is coming up with "what concepts are we even trying to encode here" (and we'll worry about shape later). It feels like there are... 4? big concepts I think:

Am I missing something or misunderstanding the high level concepts?

tarekgh commented 2 years ago

@ChadNedzlek you have captured the high-level concepts correctly. The third one we didn't discuss it though. We need to decide if it is required here.

What I was trying to get into is to have an agreement to split the abstractions so time provider (previously we were calling it IClock), should be simple and provide Utc and local time only. This one covers the first two concepts you have. Then the fourth concept will be in its own abstractions.

drieseng commented 2 years ago

No methods for return current time as TimeOnly and current date as DateOnly (yeah, it's not "time")?

tarekgh commented 2 years ago

No methods for return current time as TimeOnly and current date as DateOnly (yeah, it's not "time")?

No. We don't expose any API to return current date/time as TimeOnly or DateOnly. This is intentional. These types are not tied to specific time zones to report system time.

ghost commented 2 years ago

Tagging subscribers to this area: @dotnet/area-extensions-primitives See info in area-owners.md if you want to be subscribed.

Issue Details
## Motivation The `ISystemClock` interface exists in: * `Microsoft.AspNetCore.Authentication` * `Microsoft.AspNetCore.ResponseCaching` * `Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Infrastructure` * `Microsoft.Extensions.Internal` There is a small difference exists between implementations, but in most cases it can be moved out. In case of Kestrel's clock which has a specific logic inside, there could be made a new interface `IScopedSystemClock` which will provide the scope start time as `UtcNow` does now. Therefore, looks like all of them could be merged into a single class/interface and put into `Microsoft.Extensions.Primitives`. The same interface often implemented by developers themselves to be used by microservices and applications utilizing dependency injection. Having a common implementation of the data provider pattern will free users from repeating the same simple code many times and will allow to test apps in conjunction with ASP.NET internals without changing an environment. ## Proposed API The `ISystemClock` defines a way to get the current time in UTC timezone, and it has a simple implementation: ```csharp public interface ISystemClock { DateTimeOffset UtcNow { get; } } public class SystemClock : ISystemClock { public DateTimeOffset UtcNow => DateTimeOffset.UtcNow; } ``` --- Originally proposed in dotnet/aspnetcore#16844.
Author: YohDeadfall
Assignees: -
Labels: `api-needs-work`, `area-Extensions-Primitives`, `partner-impact`
Milestone: 8.0.0
tarekgh commented 1 year ago

I have made changes to the proposal at the top and added comments to explain the reasoning behind this design.

CC @stephentoub @geeknoid @davidfowl @joperezr @ericstj

yaakov-h commented 1 year ago

Having tried to build a similar API for a proprietary system, I find WaitAsync(Task task, TimeSpan timeout, CancellationToken cancellationToken) quite intriguing.

I would have thought that CancellationTokenSource + CancelAfter would be the ideal way to introduce a timeout to APIs that already take a CancellationToken, but that loses the ability to mock time in testing, such as by speeding it up or skipping the delay entirely.

So therefore, logically the solution is to double-up and have two ways to cancel the wait, one explicitly via timeout and one as a general-purpose cancellation token.

However I can see that you've also proposed void CancelAfter(CancellationTokenSource source, TimeSpan delay) (genius, why didn't I think of that?!). IMO this solves the first problem entirely and would allow for WaitAsync(Task task, CancellationToken cancellationToken) to be usable on it's own.

Is there another reason for WaitAsync to take TimeSpan timeout, or is it kind of redundant when the rest of the API surface is used? As far as I can tell, it could become an extension method on TimeProvider.

Clockwork-Muse commented 1 year ago

Is there another reason for WaitAsync to take TimeSpan timeout, or is it kind of redundant when the rest of the API surface is used? As far as I can tell, it could become an extension method on TimeProvider.

It would be for situations where the method receives a CancellationToken, which you want to forward, but also want to be able to cancel any async calls you make independently of the token being cancelled. The traditional way to do this is to get a linked source, this just makes it a bit easier. The pattern is relatively common for web apis (especially for things like functions-as-a-service, where you only write such a leaf method, and never see the token source).

Clockwork-Muse commented 1 year ago

@tarekgh - nit: I would prefer to call out the source of the time for the default provider, eg TimeProvider.System, instead of just labeling it "default". Are we also going to be including analyzers to nudge people away from referencing TimeProvider.Default directly, and DateTime(Offset).(Utc)Now?

Joe4evr commented 1 year ago

I agree the name System is much more preferable over Default. Some other thoughts:

  • To allow for potential future extensions, TimeProvider has been designed as a class rather than an interface. This design decision allows for virtual methods and properties to be easily overridden for testing or other purposes.

I can get behind that, but would it perhaps make sense to make it an abstract class? (Currently it's simply non-sealed.) Just thinking out loud, but TimeProvider by itself just sounds more like an abstract type rather than something to be newed up arbitrarily. (I don't believe there's a philosophical requirement that abstract members need to exist for the class to be abstract.)

  • The TimeProvider will be implemented in the Microsoft.Extensions.Primitives library.

I'm assuming that's for the down-level support case, but is there no expectation that this might want to be consumed in the runtime in the future?

public virtual DateTimeOffset UtcNow { get; }

Does this type really need to keep using the same (arguably mistaken) shape as DateTime{Offset}, or should these (finally) be made methods instead of properties?

julealgon commented 1 year ago

@tarekgh

I have made changes to the proposal at the top and added comments to explain the reasoning behind this design.

The name TimeProvider to me now seems slightly inadequate/potentially misleading. It would fit when we were just getting the current time, but as the API surface has been expanded, I think the name should be reconsidered.

Perhaps a broader name such as TimeManager or TimeHandler (or something else)?

It just feels to me that "TimeProvider" == "gives you the time", which is too limiting for the current functionality.

@Joe4evr

Does this type really need to keep using the same (arguably mistaken) shape as DateTime{Offset}, or should these (finally) be made methods instead of properties?

Are you saying that because of the dynamic nature of the value, meaning it would go against best practices for properties which should be (mostly) fixed values and/or zero-computation-cost accessors? Or is there more to it?

Also, what would the name be for it if it was a method? GetUtcNow? Or perhaps something different like GetCurrentTimeUtc (or GetCurrentDateTimeUtc)?

ilmax commented 1 year ago 
        /// <summary>
        /// Get current ticks count and ticks' frequency per second which can be used to measure elapsed time.
        /// </summary>
        /// <returns></returns>
        public virtual (long ticks, long frequency) Timestamp { get; }

I can't get to like this one due to returning a tuple :)

KalleOlaviNiemitalo commented 1 year ago

.NET Framework does not define a Task.WaitAsync method but the proposed API includes an equivalent. That can be useful even if the application does not care about wall-clock time at all. I don't know whether a downlevel implementation is being shipped in any other supported package. .NET Runtime already has such an implementation in test code, though:

https://github.com/dotnet/runtime/blob/2a90daa2cc41ae8f11a2c1519cb8b235f609251a/src/libraries/Common/tests/System/Threading/Tasks/TaskTimeoutExtensions.cs#L12-L52

That implementation does not propagate the canceled CancellationToken to the resulting Task. TaskCompletionSource\<TResult>.TrySetCanceled(CancellationToken) is part of .NET Standard 2.0 so this should be fixable.

Also, I suspect those await expressions keep only one inner exception of Task.Exception.

mattjohnsonpint commented 1 year ago 
/// <summary>
/// Retrieve the current Utc time
/// </summary>
/// <returns>DateTimeOffset object representing the current UTC time</returns>
public virtual DateTimeOffset UtcNow { get; }

/// <summary>
/// Retrieve the current local time
/// </summary>
/// <returns>DateTimeOffset object representing the current local time</returns>
public virtual DateTimeOffset LocalNow  { get; }

/// <summary>
/// time zone info object to report the local time with
/// </summary>
public virtual TimeZoneInfo TimeZone { get; }

This design allows one to implement UtcNow and LocalNow such that they return entirely different points in time. It also requires implementers of LocalNow to correctly apply the TimeZone.

I suggest LocalNow not be marked virtual. Its implementation should only exist in TimeProvider, not in derived class. Its implementation should simply be:

public DateTimeOffset LocalNow  => TimeZoneInfo.ConvertTime(UtcNow, TimeZone);
tarekgh commented 1 year ago

@yaakov-h

Is there another reason for WaitAsync to take TimeSpan timeout, or is it kind of redundant when the rest of the API surface is used? As far as I can tell, it could become an extension method on TimeProvider.

@Clockwork-Muse answer is correct regarding that.

@Clockwork-Muse

nit: I would prefer to call out the source of the time for the default provider, eg TimeProvider.System, instead of just labeling it "default".

It is a good suggestion to me.

Are we also going to be including analyzers to nudge people away from referencing TimeProvider.Default directly, and DateTime(Offset).(Utc)Now?

In general, this is a good idea, and it is related to @Joe4evr point if TimeProvider will be outside the core. If recommend using the TimeProvider.UtcNow that may require users to reference the Microsoft.Extensions library. I'll look more at this part first and we can track having the analyzer later.

@Joe4evr

I'm assuming that's for the down-level support case, but is there no expectation that this might want to be consumed in the runtime in the future?

Yes, I am still looking at this part evaluating the complication and the need inside the core.

I can get behind that, but would it perhaps make sense to make it an abstract class? (Currently it's simply non-sealed.) Just thinking out loud, but TimeProvider by itself just sounds more like an abstract type rather than something to be newed up arbitrarily. (I don't believe there's a philosophical requirement that abstract members need to exist for the class to be abstract.)

It can be an abstract class and instead of constructors we'll have factory methods. internal implementation will need to add extra internal class to create the System instance. Initially I thought to have it abstract and then I found it would be more convenient if it is not abstract. I'll think more about it.

Does this type really need to keep using the same (arguably mistaken) shape as DateTime{Offset}, or should these (finally) be made methods instead of properties?

I thought about this for a long time and debating between having it as a method and having some consistency with the existing type that is used a lot today. I am inclining to consistency with one slight change to have LocalNow instead of Now for more clarity. Anyway, this can be discussed in design review.

@julealgon

The name TimeProvider to me now seems slightly inadequate/potentially misleading.

I'll add a comment on the proposal for suggested other names like TimeManager or TimeHandler or other names. Personally, I am still like TimeProvider but we can discuss the naming during the design review.

@ilmax

I can't get to like this one due to returning a tuple :)

Can you explain why?

@KalleOlaviNiemitalo

I don't know whether a downlevel implementation is being shipped in any other supported package.

No, it is not shipped in other packages you may look at https://apisof.net/catalog/7d2ef1a2-1113-dda8-37cd-1061a7e4b3f5.

tarekgh commented 1 year ago

@mattjohnsonpint

I suggest LocalNow not be marked virtual. Its implementation should only exist in TimeProvider, not in derived class. Its implementation should simply be:

Do you think there is no test scenario needed to mock LocalNew even with having time zone and Utc time are available? I marked it as virtual for more flexibility. Whoever subclasses this can choose not to override if need the normal behavior but can choose to override it if they need to support more special behavior. I can make up one scenario is to create a time provider object which tests with multiple time zones in same time. return local time according to some condition inside the time provider. what do you think?

mattjohnsonpint commented 1 year ago

Do you think there is no test scenario needed to mock LocalNow even with having time zone and Utc time are available?

To mock the local time, one implements the mock for the UTC time and the time zone. The local time is thus provided through conversion.

I can make up one scenario is to create a time provider object which tests with multiple time zones in same time.

I think that scenario should require multiple time providers. There should be a consistent view of time within a single instance of a time provider.

mattjohnsonpint commented 1 year ago

Similarly, it feels strange to me that WaitAsync and WaitAsync<T> would have to be mocked separately. Shouldn't there be one thing to implement that would would affect them both?

tarekgh commented 1 year ago

For LocalNew I'll change it to be non-virtual for now and watch in the future if needed to be virtual.

Similarly, it feels strange to me that WaitAsync and WaitAsync would have to be mocked separately. Shouldn't there be one thing to implement that would would affect them both?

We can have only one that takes Task but this will require users of Task do extra step to get the T value which I don't like. having the overload makes it easier for the API user.

Task<T> task = ...;
await provider.WaitAsync(task, ...);
T result = task.Result; // or await task.Result
KalleOlaviNiemitalo commented 1 year ago

What's the behaviour of new TimeProvider(null)? Will the TimeZoneInfo TimeZone getter of the resulting instance read TimeZoneInfo.Local on each call so that the result is usable even if TimeZoneInfo. ClearCachedData() has been called in the meantime?

tarekgh commented 1 year ago

What's the behaviour of new TimeProvider(null)? Will the TimeZoneInfo TimeZone getter of the resulting instance read TimeZoneInfo.Local on each call so that the result is usable even if TimeZoneInfo. ClearCachedData() has been called in the meantime?

Yes, it will always use TimeZoneInfo.Local when getting the local time. This will be the same behavior of TimeProvider.Default.

Clockwork-Muse commented 1 year ago

Yes, it will always use TimeZoneInfo.Local when getting the local time. This will be the same behavior of TimeProvider.Default.

Wait, is that getting the "live" view of the local timezone, or a frozen one?

I think that scenario should require multiple time providers. There should be a consistent view of time within a single instance of a time provider.

Or a single utc-only time provider, because in most real-world instances I'm thinking of the called method will be doing conversion of the destination timezones itself, based on passed parameters.

tarekgh commented 1 year ago

Wait, is that getting the "live" view of the local timezone, or a frozen one?

will get the live one. If you want to get fixed time zone behavior can just call the constructor which take the TimeZoneInfo and pass TimeZoneInfo.Local if needed.

tarekgh commented 1 year ago

@mattjohnsonpint I got scenarios for LocalNow that may need allow overriding it. Trying to report local time that is greater than 14 hours from UTC (for testing purpose). Currently the max TZ offsets cannot exceed 14 hours. Also, we cannot have tZ offset with a fraction of minutes. I know users may try to work around it in other ways, but it will be more involving. What do you think about that?

Clockwork-Muse commented 1 year ago

will get the live one. If you want to get fixed time zone behavior can just call the constructor which take the TimeZoneInfo and pass TimeZoneInfo.Local if needed.

This difference will need to be explicitly called out in documentation (although practically the difference will be rare).

What do you think about that?

Users would have to create their own timezone-related classes to handle such cases in the first place; at that point the rest of the effort is small potatoes.

mattjohnsonpint commented 1 year ago

Trying to report local time that is greater than 14 hours from UTC (for testing purpose).

Testing what exactly? I don't see how overriding LocalNow would let you get around any of the invariants on TimeZoneInfo or DateTimeOffset.

If you're talking testing the internals of DateTimeOffset or TimeZoneInfo itself - I think that should be out of scope for this API.

mattjohnsonpint commented 1 year ago

Just also want to add, I don't like the revised API. I suggested previously:

So perhaps TimeProvider for this proposal, and something like IDelayable for a separate proposal?

And @tarekgh, you had said

@mattjohnsonpint as @stephentoub mentioned in the comment https://github.com/dotnet/runtime/issues/36617#issuecomment-1307558843 both abstracts we want to have been related and it is good to design them together.

That link to @stephentoub's comments say:

I'm suggesting this issue needs to account for both. I don't want to design one abstraction in isolation from the other. If it ends up with two abstractions, fine. If it ends up with one abstraction, fine. But they're highly related and should be designed together.

I had taken away from this that we would be looking at a TimeProvider and IDelayable together in this API design proposal, but not that we would smoosh them into a single class. The main issue I have is that it violates Single-Responsibility Principle. Mocking the current DateTime has nothing to do with mocking how the passage of time is measured or interpreted by delayable functions.

They need to be split into two abstractions.

stephentoub commented 1 year ago

They need to be split into two abstractions.

They obviously don't need to be. You want them to be. Why is that critical? What can't you do with it as proposed? What code you have to write ends up being objectively worse?

mattjohnsonpint commented 1 year ago

You're right, it probably doesn't need to be split. It just feels to me like it should. Sorry for my poor word choice.

Still, I'm struggling to come with a scenario that would benefit from them being together. It feels a bit like a generic utility class, getting the kitchen sink of all things time related.

yaakov-h commented 1 year ago

Mocking the current DateTime has nothing to do with mocking how the passage of time is measured or interpreted by delayable functions.

I would strongly disagree here. If I want to accelerate or slow down the passage of time, or skip time completely, I would need to mock out both the current time as well as anything that relies on time elapsing.

The currently proposed design has both in one class which means there's only one object responsible for time. Splitting them means I need up to two objects which have to be kept in sync - one for "what is the time" and one for "wait for a period of time".

(Granted, at the moment you would need to keep all the methods in sync, but I don't see that as much of a problem.)