Moved the failure handling of asynchronous processes from the Operation class into a new intermediate class, FailableProgression; renamed Begin() to Start() in Operation to keep it more in line with System.Threading.Thread; renamed End() method to Join() in the new FailableProgression class for the same reason; improved documentation

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

Nuclex.Support (x86).csproj

@@ -60,6 +60,8 @@
     <Reference Include="System">
       <Private>False</Private>
     </Reference>
+    <Reference Include="System.Data" />
+    <Reference Include="System.Xml" />
   </ItemGroup>
   <ItemGroup>
     <Compile Include="Properties\AssemblyInfo.cs" />
@@ -146,6 +148,7 @@
     <Compile Include="Source\Tracking\Internal\ObservedWeightedProgression.cs" />
     <Compile Include="Source\Tracking\Internal\WeightedProgressionWrapperCollection.cs" />
     <Compile Include="Source\Tracking\IStatusReporter.cs" />
+    <Compile Include="Source\Tracking\FailableProgression.cs" />
     <Compile Include="Source\Tracking\Progression.cs" />
     <Compile Include="Source\Tracking\ProgressionTracker.cs" />
     <Compile Include="Source\Tracking\ProgressionTracker.Test.cs">

Source/Scheduling/Operation.cs

@@ -26,64 +26,10 @@ using Nuclex.Support.Tracking;
 namespace Nuclex.Support.Scheduling {
 
   /// <summary>Base class for observable operations running in the background</summary>
-  public abstract class Operation : Progression {
+  public abstract class Operation : FailableProgression {
 
     /// <summary>Launches the background operation</summary>
-    public abstract void Begin();
-
-    /// <summary>Waits for the background operation to end</summary>
-    /// <remarks>
-    ///   Any exceptions raised in the background operation will be thrown
-    ///   in this method. If you decide to override this method, you should
-    ///   call End() first (and let any possible exception through to your
-    ///   caller).
-    /// </remarks>
-    public virtual void End() {
-
-      // By design, end can only be called once!
-      lock(this) {
-        if(this.endCalled)
-          throw new InvalidOperationException("End() has already been called");
-
-        this.endCalled = true;
-      }
-
-      // If the progression itself hasn't ended yet, block the caller until it has.
-      if(!Ended)
-        WaitHandle.WaitOne();
-
-      // If an exception occured during the background execution
-      if(this.occuredException != null)
-        throw this.occuredException;
-
-    }
-
-    /// <summary>Exception that occured while the operation was executing</summary>
-    /// <remarks>
-    ///   If this field is null, it is assumed that no exception has occured
-    ///   in the background process. If it is set, however, the End() method will
-    ///   re-raise the exception to the calling thread when it is called.
-    /// </remarks>
-    public Exception OccuredException {
-      get { return this.occuredException; }
-    }
-
-    /// <summary>Sets the exception to raise to the caller of the End() method</summary>
-    /// <param name="exception">Exception to raise to the caller of the End() method</param>
-    protected void SetException(Exception exception) {
-
-      // We allow the caller to set the exception multiple times. While I certainly
-      // can't think of a scenario where this would happen, throwing an exception
-      // in that case seems worse. The caller might just be executing an exception
-      // handling block and locking + throwing here could cause all kinds of problems.
-      this.occuredException = exception;
-
-    }
-
-    /// <summary>Exception that occured while the operation was executing</summary>
-    private volatile Exception occuredException;
-    /// <summary>Whether the End() method has been called already</summary>
-    private volatile bool endCalled;
+    public abstract void Start();
 
   }
 

Source/Scheduling/QueueOperation.Test.cs

@@ -99,7 +99,7 @@ namespace Nuclex.Support.Scheduling {
     private class TestOperation : Operation {
 
       /// <summary>Begins executing the operation. Yeah, sure :)</summary>
-      public override void Begin() { }
+      public override void Start() { }
 
       /// <summary>Moves the operation into the ended state</summary>
       public void SetEnded() {
@@ -144,7 +144,7 @@ namespace Nuclex.Support.Scheduling {
 
       IQueueOperationSubscriber mockedSubscriber = mockSubscriber(testQueueOperation);
 
-      testQueueOperation.Begin();
+      testQueueOperation.Start();
 
       Expect.Once.On(mockedSubscriber).
         Method("ProgressUpdated").

Source/Scheduling/QueueOperation.cs

@@ -80,8 +80,8 @@ namespace Nuclex.Support.Scheduling {
     }
 
     /// <summary>Launches the background operation</summary>
-    public override void Begin() {
-      beginCurrentOperation();
+    public override void Start() {
+      startCurrentOperation();
     }
 
     /// <summary>Prepares the current operation and calls its Begin() method</summary>
@@ -89,13 +89,13 @@ namespace Nuclex.Support.Scheduling {
     ///   This subscribes the queue to the events of to the current operation
     ///   and launches the operation by calling its Begin() method.
     /// </remarks>
-    private void beginCurrentOperation() {
+    private void startCurrentOperation() {
       OperationType operation = this.children[this.currentOperationIndex].Progression;
 
       operation.AsyncEnded += this.asyncOperationEndedDelegate;
       operation.AsyncProgressUpdated += this.asyncOperationProgressUpdatedDelegate;
 
-      operation.Begin();
+      operation.Start();
     }
 
     /// <summary>Disconnects from the current operation and calls its End() method</summary>
@@ -112,7 +112,7 @@ namespace Nuclex.Support.Scheduling {
       operation.AsyncProgressUpdated -= this.asyncOperationProgressUpdatedDelegate;
 
       try {
-        operation.End();
+        operation.Join();
 
         // Add the operations weight to the total amount of completed weight in the queue
         this.completedWeight += this.children[this.currentOperationIndex].Weight;
@@ -141,7 +141,7 @@ namespace Nuclex.Support.Scheduling {
 
         // Execute the next operation unless we reached the end of the queue
         if(this.currentOperationIndex < this.children.Count) {
-          beginCurrentOperation();
+          startCurrentOperation();
           return;
         }
 

Source/Scheduling/ThreadOperation.cs

@@ -49,7 +49,7 @@ namespace Nuclex.Support.Scheduling {
     }
 
     /// <summary>Launches the background operation</summary>
-    public override void Begin() {
+    public override void Start() {
       if(useThreadPool) {
         ThreadPool.QueueUserWorkItem(callMethod);
       } else {

Source/Tracking/FailableProgression.cs

@@ -0,0 +1,109 @@
+using System;
+using System.Collections.Generic;
+
+namespace Nuclex.Support.Tracking {
+
+  /// <summary>Extended type of progression that is able to fail</summary>
+  /// <remarks>
+  ///   <para>
+  ///     If the background process fails, the exception that caused it to fail is
+  ///     communicated to all parties waiting on the progression through the
+  ///     Exception property. Implementers should place their code in try..catch
+  ///     blocks and call SetException() to temporarily store the exception for
+  ///     retrieval by the caller(s).
+  ///   </para>
+  ///   <para>
+  ///     As with all progressions, the interface contract still requires you to call
+  ///     OnAsyncEnded(), no matter what the outcome of your background operation is.
+  ///   </para>
+  /// </remarks>
+  public class FailableProgression : Progression {
+
+    #region class EndedDummyProgression
+
+    /// <summary>Dummy progression that is always in the ended state</summary>
+    private class EndedDummyProgression : FailableProgression {
+      /// <summary>Creates a new successfully completed dummy progression</summary>
+      public EndedDummyProgression() : this(null) { }
+      /// <summary>Creates a new failed dummy progression</summary>
+      /// <param name="exception">Exception that caused the dummy to fail</param>
+      public EndedDummyProgression(Exception exception) {
+        OnAsyncEnded();
+
+        // Only call SetException() if an actual exception was provided. Who knows what
+        // evil code might be inside SetException() after all ;)
+        if(exception != null)
+          SetException(exception);
+      }
+    }
+
+    #endregion // EndedDummyProgression
+
+    /// <summary>Creates a new failed dummy progression</summary>
+    /// <param name="error">
+    ///   Exception that supposedly caused the progression to fail
+    /// </param>
+    /// <returns>
+    ///   A failed progression that reports the provided exception as cause for its failure
+    /// </returns>
+    public static FailableProgression CreateFailedDummyProgression(Exception exception) {
+      return new EndedDummyProgression(exception);
+    }
+
+    /// <summary>Waits for the background operation to end</summary>
+    /// <remarks>
+    ///   Any exceptions raised in the background operation will be thrown
+    ///   in this method. If you decide to override this method, you should
+    ///   call End() first (and let any possible exception through to your
+    ///   caller).
+    /// </remarks>
+    public virtual void Join() {
+
+      // By design, end can only be called once!
+      lock(this) {
+        if(this.endCalled)
+          throw new InvalidOperationException("End() has already been called");
+
+        this.endCalled = true;
+      }
+
+      // If the progression itself hasn't ended yet, block the caller until it has.
+      if(!Ended)
+        WaitHandle.WaitOne();
+
+      // If an exception occured during the background execution
+      if(this.occuredException != null)
+        throw this.occuredException;
+
+    }
+
+    /// <summary>Exception that occured while the operation was executing</summary>
+    /// <remarks>
+    ///   If this field is null, it is assumed that no exception has occured
+    ///   in the background process. If it is set, however, the End() method will
+    ///   re-raise the exception to the calling thread when it is called.
+    /// </remarks>
+    public Exception OccuredException {
+      get { return this.occuredException; }
+    }
+
+    /// <summary>Sets the exception to raise to the caller of the End() method</summary>
+    /// <param name="exception">Exception to raise to the caller of the End() method</param>
+    protected void SetException(Exception exception) {
+
+      // We allow the caller to set the exception multiple times. While I certainly
+      // can't think of a scenario where this would happen, throwing an exception
+      // in that case seems worse. The caller might just be executing an exception
+      // handling block and locking + throwing here could cause all kinds of problems.
+      this.occuredException = exception;
+
+    }
+
+    /// <summary>Exception that occured while the operation was executing</summary>
+    private volatile Exception occuredException;
+    /// <summary>Whether the End() method has been called already</summary>
+    private volatile bool endCalled;
+
+  }
+
+} // namespace Nuclex.Support.Tracking

Source/Tracking/IStatusReporter.cs

@@ -24,7 +24,7 @@ using System.Collections.Generic;
 namespace Nuclex.Support.Tracking {
 
   /// <summary>Interface for processes that report their status</summary>
-  interface IStatusReporter {
+  public interface IStatusReporter {
 
     /// <summary>Triggered when the status of the process changes</summary>
     event EventHandler<StatusReportEventArgs> StatusChanged;