Renamed DefaultTimeSource to GenericTimeSource; the generic time source will now detect when the system date/time is adjusted; made some progress on the Scheduler implementation; wrote some unit tests for the Scheduler class

git-svn-id: file:///srv/devel/repo-conversion/nusu@144 d2e56fa2-650e-0410-a79f-9358c0239efd

Source/Scheduling/GenericTimeSource.cs

@@ -0,0 +1,181 @@
+#region CPL License
+/*
+Nuclex Framework
+Copyright (C) 2002-2009 Nuclex Development Labs
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the IBM Common Public License as
+published by the IBM Corporation; either version 1.0 of the
+License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+IBM Common Public License for more details.
+
+You should have received a copy of the IBM Common Public
+License along with this library
+*/
+#endregion
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Threading;
+
+namespace Nuclex.Support.Scheduling {
+
+  /// <summary>
+  ///   Generic time source implementation using the Stopwatch or Environment.TickCount
+  /// </summary>
+  public class GenericTimeSource : ITimeSource {
+
+    /// <summary>Number of ticks (100 ns intervals) in a millisecond</summary>
+    private const long TicksPerMillisecond = 10000;
+
+    /// <summary>Tolerance for the detection of a date/time adjustment</summary>
+    /// <remarks>
+    ///   If the current system date/time jumps by more than this tolerance into any
+    ///   direction, the default time source will trigger the DateTimeAdjusted event.
+    /// </remarks>
+    private const long TimeAdjustmentToleranceTicks = 75 * TicksPerMillisecond;
+
+    /// <summary>Called when the system date/time are adjusted</summary>
+    /// <remarks>
+    ///   An adjustment is a change out of the ordinary, eg. when a time synchronization
+    ///   alters the current system time, when daylight saving time takes effect or
+    ///   when the user manually adjusts the system date/time.
+    /// </remarks>
+    public event EventHandler DateTimeAdjusted;
+
+    /// <summary>Initializes the static fields of the default time source</summary>
+    static GenericTimeSource() {
+      tickFrequency = 10000000.0;
+      tickFrequency /= (double)Stopwatch.Frequency;
+    }
+
+    /// <summary>Initializes the default time source</summary>
+    public GenericTimeSource() : this(Stopwatch.IsHighResolution) { }
+
+    /// <summary>Initializes the default time source</summary>
+    /// <param name="useStopwatch">
+    ///   Whether to use the Stopwatch class for measuring time
+    /// </param>
+    /// <remarks>
+    ///   <para>
+    ///     Normally it's a good idea to use the default constructor. If the Stopwatch
+    ///     is unable to use the high-resolution timer, it will fall back to
+    ///     DateTime.Now (as stated on MSDN). This is bad because then the tick count
+    ///     will jump whenever the system time changes (eg. when the system synchronizes
+    ///     its time with a time server).
+    ///   </para>
+    ///   <para>
+    ///     Your can safely use this constructor if you always set its arugment to 'false',
+    ///     but then your won't profit from the high-resolution timer if one is available.
+    ///   </para>
+    /// </remarks>
+    public GenericTimeSource(bool useStopwatch) {
+      this.useStopwatch = useStopwatch;
+
+      checkForTimeAdjustment();
+    }
+
+    /// <summary>Waits for an AutoResetEvent to become signalled</summary>
+    /// <param name="waitHandle">WaitHandle the method will wait for</param>
+    /// <param name="ticks">Number of ticks to wait</param>
+    /// <returns>
+    ///   True if the WaitHandle was signalled, false if the timeout was reached
+    /// </returns>
+    public virtual bool WaitOne(AutoResetEvent waitHandle, long ticks) {
+      checkForTimeAdjustment();
+
+      // Force a timeout at least each second so the caller can check the system time
+      // since we're not able to provide the DateTimeAdjusted notification
+      int milliseconds = (int)(ticks / TicksPerMillisecond);
+      return waitHandle.WaitOne(Math.Min(1000, milliseconds), false);
+    }
+
+    /// <summary>Current system time in UTC format</summary>
+    public DateTime CurrentUtcTime {
+      get { return DateTime.UtcNow; }
+    }
+
+    /// <summary>How long the time source has been running</summary>
+    /// <remarks>
+    ///   There is no guarantee this value starts at zero (or anywhere near it) when
+    ///   the time source is created. The only requirement for this value is that it
+    ///   keeps increasing with the passing of time and that it stays unaffected
+    ///   (eg. doesn't skip or jump back) when the system date/time are changed.
+    /// </remarks>
+    public long Ticks {
+      get {
+
+        // The docs say if Stopwatch.IsHighResolution is false, it will return
+        // DateTime.Now (actually DateTime.UtcNow). This means that the Stopwatch is
+        // prone to skips and jumps during DST crossings and NTP synchronizations,
+        // so we cannot use it in that case.
+        if(this.useStopwatch) {
+          double timestamp = (double)Stopwatch.GetTimestamp();
+          return (long)(timestamp * tickFrequency);
+        }
+
+        // Fallback: Use Environment.TickCount instead. Not as accurate, but at least
+        // it will not jump around when the date or time are adjusted.
+        return Environment.TickCount * TicksPerMillisecond;
+
+      }
+    }
+
+    /// <summary>Called when the system time is changed</summary>
+    /// <param name="sender">Not used</param>
+    /// <param name="arguments">Not used</param>
+    protected virtual void OnDateTimeAdjusted(object sender, EventArgs arguments) {
+      EventHandler copy = DateTimeAdjusted;
+      if(copy != null) {
+        copy(sender, arguments);
+      }
+    }
+
+    /// <summary>
+    ///   Checks whether the system/date time have been adjusted since the last call
+    /// </summary>
+    private void checkForTimeAdjustment() {
+
+      // Grab the current date/time and timer ticks in one go
+      DateTime currentLocalTime = DateTime.Now;
+      long currentTicks = Ticks;
+
+      // Calculate the number of timer ticks that have passed since the last check and
+      // extrapolate the local date/time we should be expecting to see
+      long ticksSinceLastCheck = currentTicks - lastCheckedTicks;
+      DateTime expectedLocalTime = new DateTime(
+        lastCheckedLocalTime.Ticks + ticksSinceLastCheck, DateTimeKind.Local
+      );
+
+      // Find out by what amount the actual local date/time deviates from
+      // the extrapolated date/time and trigger the date/time adjustment event if
+      // we can reasonably assume that the system date/time have been adjusted.
+      long deviationTicks = Math.Abs(expectedLocalTime.Ticks - currentLocalTime.Ticks);
+      if(deviationTicks > TimeAdjustmentToleranceTicks) {
+        OnDateTimeAdjusted(this, EventArgs.Empty);
+      }
+
+      // Remember the current local date/time and timer ticks for the next run
+      this.lastCheckedLocalTime = currentLocalTime;
+      this.lastCheckedTicks = currentTicks;
+
+    }
+
+    /// <summary>Last local time we checked for a date/time adjustment</summary>
+    private DateTime lastCheckedLocalTime;
+    /// <summary>Timer ticks at which we last checked the local time</summary>
+    private long lastCheckedTicks;
+
+    /// <summary>Number of ticks per Stopwatch time unit</summary>
+    private static double tickFrequency;
+    /// <summary>Whether ot use the Stopwatch class for measuring time</summary>
+    private bool useStopwatch;
+
+  }
+
+} // namespace Nuclex.Support.Scheduling