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

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 {