Click or drag to resize

SysTime Class

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.
Inheritance Hierarchy
SystemObject
  Neon.TimeSysTime

Namespace:  Neon.Time
Assembly:  Neon.Common (in Neon.Common.dll) Version: 2.1.0
Syntax
public static class SysTime

The SysTime type exposes the following members.

Properties
  NameDescription
Public propertyStatic memberExternalNow
Tracks an external time source.
Public propertyStatic memberInfinite
Returns what is essentially an infinite timespan.
Public propertyStatic memberNow
Returns the current time relative to time the system started.
Public propertyStatic memberResolution
Returns the resolution of the underlying system timer.
Top
Methods
  NameDescription
Public methodStatic memberReset
Used by Unit tests to reset the timer class to its initial value.
Top
Remarks

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 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 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 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.

See Also