Improved comments in various places; disabled all classes in the 'Services' namespace, including the type listers; added scheduler class which will act sort of like the cron daemon on unix machines; defined a time source interface so I can manually advance time instead of waiting in the unit tests; created two time sources, a generic one for all platforms and a windows specific one that will notice when the system time is adjusted

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

Source/Scheduling/AbortedException.Test.cs

@@ -25,7 +25,6 @@ using System.Collections.Generic;
 using System.IO;
 using System.Runtime.Serialization.Formatters.Binary;
 
-
 using NUnit.Framework;
 using NMock2;
 

Source/Scheduling/DefaultTimeSource.Test.cs

@@ -0,0 +1,97 @@
+#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
+
+#if UNITTEST
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+
+using NUnit.Framework;
+
+namespace Nuclex.Support.Scheduling {
+
+  /// <summary>Unit Test for the default scheduler time source</summary>
+  [TestFixture]
+  public class DefaultTimeSourceTest {
+
+    /// <summary>
+    ///   Verifies that the time source's default constructor is working
+    /// </summary>
+    [Test]
+    public void TestDefaultConstructor() {
+      DefaultTimeSource timeSource = new DefaultTimeSource();
+    }
+
+    /// <summary>
+    ///   Verifies that the time source can provide the current UTC time
+    /// </summary>
+    [Test]
+    public void TestCurrentUtcTime() {
+      DefaultTimeSource timeSource = new DefaultTimeSource();
+
+      Assert.That(
+        timeSource.CurrentUtcTime, Is.EqualTo(DateTime.UtcNow).Within(10).Seconds
+      );
+    }
+
+    /// <summary>
+    ///   Verifies that the default time source's tick property is working if
+    ///   the Stopwatch class is used to measure time
+    /// </summary>
+    [Test]
+    public void TestTicksWithStopwatch() {
+      DefaultTimeSource timeSource = new DefaultTimeSource(true);
+      long ticks1 = timeSource.Ticks;
+      long ticks2 = timeSource.Ticks;
+
+      Assert.That(ticks2, Is.GreaterThanOrEqualTo(ticks1));
+    }
+
+    /// <summary>
+    ///   Verifies that the default time source's tick property is working if
+    ///   Environment.TickCount is used to measure time
+    /// </summary>
+    [Test]
+    public void TestTicksWithTickCount() {
+      DefaultTimeSource timeSource = new DefaultTimeSource(false);
+      long ticks1 = timeSource.Ticks;
+      long ticks2 = timeSource.Ticks;
+
+      Assert.That(ticks2, Is.GreaterThanOrEqualTo(ticks1));
+    }
+
+    /// <summary>
+    ///   Verifies that the default time source's WaitOne() method works correctly
+    /// </summary>
+    [Test]
+    public void TestWaitOne() {
+      DefaultTimeSource timeSource = new DefaultTimeSource();
+      AutoResetEvent waitEvent = new AutoResetEvent(true);
+
+      Assert.IsTrue(timeSource.WaitOne(waitEvent, TimeSpan.FromMilliseconds(1).Ticks));
+      Assert.IsFalse(timeSource.WaitOne(waitEvent, TimeSpan.FromMilliseconds(1).Ticks));
+    }
+
+  }
+
+} // namespace Nuclex.Support.Scheduling
+
+#endif // UNITTEST

Source/Scheduling/DefaultTimeSource.cs

@@ -0,0 +1,137 @@
+#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>
+  ///   Default time source implementation using the Stopwatch or Environment.TickCount
+  /// </summary>
+  public class DefaultTimeSource : ITimeSource {
+
+    /// <summary>Number of ticks (100 ns intervals) in a millisecond</summary>
+    private const long TicksPerMillisecond = 10000;
+
+    /// <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 DefaultTimeSource() {
+      tickFrequency = 10000000.0;
+      tickFrequency /= (double)Stopwatch.Frequency;
+    }
+
+    /// <summary>Initializes the default time source</summary>
+    public DefaultTimeSource() : 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 DefaultTimeSource(bool useStopwatch) {
+      this.useStopwatch = useStopwatch;
+    }
+
+    /// <summary>Waits for an AutoResetEvent 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) {
+
+      // 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>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

Source/Scheduling/ITimeSource.cs

@@ -0,0 +1,67 @@
+#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.Threading;
+
+namespace Nuclex.Support.Scheduling {
+
+  /// <summary>Provides time measurement and change notification services</summary>
+  interface ITimeSource {
+
+    /// <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>
+    event EventHandler DateTimeAdjusted;
+
+    /// <summary>Waits for an AutoResetEvent 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
+    ///   or the time source thinks its time to recheck the system date/time.
+    /// </returns>
+    /// <remarks>
+    ///   Depending on whether the system will provide notifications when date/time
+    ///   is adjusted, the time source will be forced to let thid method block for
+    ///   less than the indicated time before returning a timeout in order to give
+    ///   the caller a chance to recheck the system time.
+    /// </remarks>
+    bool WaitOne(AutoResetEvent waitHandle, long ticks);
+
+    /// <summary>Current system time in UTC format</summary>
+    DateTime CurrentUtcTime { get; }
+
+    /// <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>
+    long Ticks { get; }
+
+  }
+
+} // namespace Nuclex.Support.Scheduling

Source/Scheduling/Scheduler.cs

@@ -0,0 +1,42 @@
+#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.Threading;
+using System.Diagnostics;
+
+namespace Nuclex.Support.Scheduling {
+
+#if false
+
+  /// <summary>Schedules actions for execution at a future point in time</summary>
+  public class Scheduler : IDisposable {
+
+    /// <summary>Immediately releases all resources owned by the instance</summary>
+    public void Dispose() {
+    }
+
+
+  }
+
+#endif
+
+} // namespace Nuclex.Support.Scheduling

Source/Scheduling/WindowsTimeSource.Test.cs

@@ -0,0 +1,164 @@
+#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
+
+#if UNITTEST
+
+#if !XBOX360
+
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Threading;
+
+using Microsoft.Win32;
+
+using NUnit.Framework;
+
+namespace Nuclex.Support.Scheduling {
+
+  /// <summary>Unit Test for the windows time source</summary>
+  [TestFixture]
+  public class WindowsTimeSourceTest {
+
+    #region class TestWindowsTimeSource
+
+    /// <summary>Windows time source used for testing</summary>
+    private class TestWindowsTimeSource : WindowsTimeSource {
+
+      /// <summary>
+      ///   Forces a time change notification even if the system time was not adjusted
+      /// </summary>
+      public void ForceTimeChange() {
+        OnDateTimeAdjusted(this, EventArgs.Empty);
+      }
+    }
+
+    #endregion // class TestWindowsTimeSource
+
+    #region class TestTimeChangedSubscriber
+
+    /// <summary>Dummy subscriber used to test the time changed event</summary>
+    private class TestTimeChangedSubscriber {
+
+      /// <summary>Callback subscribed to the TimeChanged event</summary>
+      /// <param name="sender">Not used</param>
+      /// <param name="arguments">Not used</param>
+      public void TimeChanged(object sender, EventArgs arguments) {
+        ++this.CallCount;
+      }
+
+      /// <summary>Number of times the callback was invoked</summary>
+      public int CallCount;
+
+    }
+
+    #endregion // class TestTimeChangedSubscriber
+
+    /// <summary>
+    ///   Verifies that the time source's default constructor is working
+    /// </summary>
+    [Test]
+    public void TestDefaultConstructor() {
+      using(WindowsTimeSource timeSource = new WindowsTimeSource()) { }
+    }
+
+    /// <summary>
+    ///   Verifies that the time source can provide the current UTC time
+    /// </summary>
+    [Test]
+    public void TestCurrentUtcTime() {
+      using(WindowsTimeSource timeSource = new WindowsTimeSource()) {
+
+        Assert.That(
+          timeSource.CurrentUtcTime, Is.EqualTo(DateTime.UtcNow).Within(10).Seconds
+        );
+      }
+    }
+
+    /// <summary>
+    ///   Verifies that the time source's tick property is working if
+    ///   the Stopwatch class is used to measure time
+    /// </summary>
+    [Test]
+    public void TestTicks() {
+      using(WindowsTimeSource timeSource = new WindowsTimeSource()) {
+        long ticks1 = timeSource.Ticks;
+        long ticks2 = timeSource.Ticks;
+
+        Assert.That(ticks2, Is.GreaterThanOrEqualTo(ticks1));
+      }
+    }
+
+    /// <summary>
+    ///   Verifies that the time source's WaitOne() method works correctly
+    /// </summary>
+    [Test]
+    public void TestWaitOne() {
+      using(WindowsTimeSource timeSource = new WindowsTimeSource()) {
+        AutoResetEvent waitEvent = new AutoResetEvent(true);
+
+        Assert.IsTrue(timeSource.WaitOne(waitEvent, TimeSpan.FromMilliseconds(1).Ticks));
+        Assert.IsFalse(timeSource.WaitOne(waitEvent, TimeSpan.FromMilliseconds(1).Ticks));
+      }
+    }
+
+    /// <summary>
+    ///   Verifies that the default time source's WaitOne() method works correctly
+    /// </summary>
+    [Test]
+    public void TestTimeChange() {
+      using(TestWindowsTimeSource timeSource = new TestWindowsTimeSource()) {
+        TestTimeChangedSubscriber subscriber = new TestTimeChangedSubscriber();
+
+        EventHandler callbackDelegate = new EventHandler(subscriber.TimeChanged);
+        timeSource.DateTimeAdjusted += callbackDelegate;
+        try {
+          timeSource.ForceTimeChange();
+        }
+        finally {
+          timeSource.DateTimeAdjusted -= callbackDelegate;
+        }
+        
+        // Using greater than because during the test run a real time change notification
+        // might have happened, increasing the counter to 2 or more.
+        Assert.That(subscriber.CallCount, Is.GreaterThanOrEqualTo(1));
+      }
+    }
+
+    /// <summary>
+    ///   Tests whether the Windows-specific time source can reports its availability on
+    ///   the current platform
+    /// </summary>
+    [Test]
+    public void TestAvailability() {
+      bool isAvailable = WindowsTimeSource.Available;
+      Assert.IsTrue(
+        (isAvailable == true) ||
+        (isAvailable == false)
+      );
+    }
+
+  }
+
+} // namespace Nuclex.Support.Scheduling
+
+#endif // !XBOX360
+
+#endif // UNITTEST

Source/Scheduling/WindowsTimeSource.cs

@@ -0,0 +1,77 @@
+#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
+
+#if !XBOX360
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+
+using Microsoft.Win32;
+
+namespace Nuclex.Support.Scheduling {
+
+  /// <summary>
+  ///   Time source that makes use of additional features only available on Windows
+  /// </summary>
+  public class WindowsTimeSource : DefaultTimeSource, IDisposable {
+
+    /// <summary>Number of ticks (100 ns intervals) in a millisecond</summary>
+    private const long TicksPerMillisecond = 10000;
+
+    /// <summary>Initializes a new Windows time source</summary>
+    public WindowsTimeSource() {
+      this.onDateTimeAdjustedDelegate = new EventHandler(OnDateTimeAdjusted);
+      SystemEvents.TimeChanged += this.onDateTimeAdjustedDelegate;
+    }
+
+    /// <summary>Immediately releases all resources owned by the instance</summary>
+    public void Dispose() {
+      if(this.onDateTimeAdjustedDelegate != null) {
+        SystemEvents.TimeChanged -= this.onDateTimeAdjustedDelegate;
+        this.onDateTimeAdjustedDelegate = null;
+      }
+    }
+
+    /// <summary>Waits for an AutoResetEvent 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 override bool WaitOne(AutoResetEvent waitHandle, long ticks) {
+      return waitHandle.WaitOne((int)(ticks / TicksPerMillisecond));
+    }
+
+    /// <summary>
+    ///   Whether the Windows time source can be used on the current platform
+    /// </summary>
+    public static bool Available {
+      get { return Environment.OSVersion.Platform == PlatformID.Win32NT; }
+    }
+
+    /// <summary>Delegate for the timeChanged() callback method</summary>
+    private EventHandler onDateTimeAdjustedDelegate;
+
+  }
+
+} // namespace Nuclex.Support.Scheduling
+
+#endif // !XBOX360