Class SysTime
A date/time implementation that is guaranteed to be monotonically increasing even as the underlying system time is updated manually or automatically to adjust for daylight savings time or clock skewing.
Namespace: Neon.Time
Assembly: Neon.Common.dll
Syntax
public static class SysTimeRemarks
Use of system time rather than real-time is useful in situations where events need to be timed in relative rather than absolute time. Using absolute time to measure intervals call can be problematic because system clock may be have to be periodically corrected to keep it in sync with a global time base. These corrections will cause event timers to become inaccurate.
The Now property returns the current system time and Infinite calculates and returns an essentially infinite timespan value that will be safe when added to the current system time.
note
The DateTime instances returned by this class are useful only for measuring timespans. The Day, Month, Year properties will have no useful meaning.
note
The class is implemented such that the first time returned by the Now property will be a time value that is a minumim of one year after MinValue. This is useful in situations where programs want to schedule a periodic event for immediate triggering when the application starts by setting the last trigger time to MinValue.
The SysTime class is also capable of maintaining rough synchronization with an external time source. To use this feature, you'll periodically get the time from the external source and assign it to the static ExternalNow property then you can use the ExternalNow property to get and estimate of the current external time.
The local side clock will likely drift over time, resulting in a skew between the time returned by ExternalNow and the actual time at the external source. This skew can be limited by getting the external time and assigning it to ExternalNow more frequently.
note
The time returned by ExternalNow is not guaranteed to be monotimically increasing since reported times may jump around as the bias between the local and external clocks are adjusted.
Implementation Note
This class is currently implemented using the Windows GetTickCount() API. This function returns the number of milliseconds since the operating system was booted with a resolution equal to the process/threading timeslice (typically 10-15 milliseconds). The actual resolution for the current machine can be obtained from Resolution.
The TickCount counter is an unsigned 32-bit value and will wrap-around every 49.7 days. The SysTime class handles this by using a GatedTimer to wake up every five minutes to check for and handle this wrap-around.
As noted above, the time value returned by Now has no relation to the actual calendar date. The first date returned after booting the computer will be approximately 1/1/0002 00:00:00, one year greater the minimum DateTime value. Infinite returns a calculated value that when added to Now will result in a date one year less then the maximum DateTime value.
These one year offsets were choosen so that applications can perform reasonable offset calculations (e.g. within background tasks) without fear of wrap-around. Since DateTime and TimeSpan span up to 10,000 years, this means that SysTime calculations will remain valid for up to 9,998 years after the computer has been started, which should be good enough for most applications.
Properties
ExternalNow
Tracks an external time source.
note
This currently throws a NotImplementedException.
Declaration
public static DateTime ExternalNow { get; set; }Property Value
| Type | Description |
|---|---|
| DateTime |
Remarks
The SysTime class is also capable of maintaining rough synchronization with an external time source. To use this feature, you'll periodically get the time from the external source and assign it to the static ExternalNow property then you can use the ExternalNow property to get and estimate of the current external time.
The local side clock will likely drift over time, resulting in a skew between the time returned by ExternalNow and the actual time at the external source. This skew can be limited by getting the external time and assigning it to ExternalNow more frequently.
note
The time returned by ExternalNow is not guaranteed to be monotimically increasing since reported times may jump around as the bias between the local and external clocks are adjusted.
Infinite
Returns what is essentially an infinite timespan.
Declaration
public static TimeSpan Infinite { get; }Property Value
| Type | Description |
|---|---|
| TimeSpan |
Remarks
The value returned will calculated such that when added to the current SysTime.Now value that the result will be MaxValue minus one year.
This is useful for situations where you need specify an infinite timeout but you want to avoid wrap-around when adding this to the current SysTime.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown if there's a problem with the system timer. |
Now
Returns the current time relative to time the system started.
Declaration
public static DateTime Now { get; }Property Value
| Type | Description |
|---|---|
| DateTime |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown if there's a problem with the system timer. |
Resolution
Returns the resolution of the underlying system timer.
Declaration
public static TimeSpan Resolution { get; }Property Value
| Type | Description |
|---|---|
| TimeSpan |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown if there's a problem with the system timer. |
Methods
Reset()
Used by Unit tests to reset the timer class to its initial value.
Declaration
public static void Reset()