TaskCompletion.txt
20210307

TaskCompletionSource<TResult> Class
Represents the producer side of a Task<TResult> unbound to a delegate, providing access to the consumer side through the Task property.

public class TaskCompletionSource<TResult>


----------
20210307

        /// <summary>
        /// 同時執行 ProcessStartInfo 並捕捉 StandardOutput 執行結果.
        /// 不會封鎖主執行緒.
        /// usage: var psi = new ProcessStartInfo() { FileName = @"..\..\test.exe" }; 
        /// using (var stream = await ZRunWithCaptureAsync(psi))
        /// {
        ///   var sr = new StreamReader(stream);
        ///   Console.Write(sr.ReadToEnd());
        /// }
        /// </summary>
        /// <param name="startInfo"></param>
        /// <returns></returns>
        public static Task<Stream> ZRunWithCaptureAsync(ProcessStartInfo startInfo)
        {
            /*
             
            ref: https://www.codeproject.com/Tips/5295013/Adapting-Event-and-Callback-Based-Asynchronicity-t
            usage:
            var psi = new ProcessStartInfo() { FileName = @"..\..\test.exe" };
            using (var stream = await ZRunWithCaptureAsync(psi))
            {
                // use a streamreader because we want text
                var sr = new StreamReader(stream);
                // no need to dispose it because 
                // we are disposing the stream
                Console.Write(sr.ReadToEnd());
            }

             */
            // we use this as a signal for our custom task
            // we can use SetResult, SetException, and even SetCancelled
            // to signal the completion of a task, with or without errors
            // do not throw exceptions in your async handlers.
            // Use SetException.
            var tcs = new TaskCompletionSource<Stream>(); // CodeHelper TaskCompleteSource 1
            try
            {
                // create a process, and set it up for capturing
                // and raising events
                var proc = new Process();
                proc.StartInfo = startInfo;
                proc.EnableRaisingEvents = true;
                startInfo.RedirectStandardOutput = true;
                startInfo.UseShellExecute = false;
                // attach an event handler that signals completion
                // of our task - here Exited serves us well.
                // note we're using hoisting to pass the 
                // TaskCompletionSource through to the anonymous
                // method:
                proc.Exited += (object sender, EventArgs e) =>
                {
                    // if we were doing anything non-trivial here
                    // we'd wrap everything in a try/catch block
                    // and use tcs.SetException in the catch block
                    // instead of throwing. We don't need that here
                    // because nothing should throw.
                    tcs.SetResult(proc.StandardOutput.BaseStream); // CodeHelper TaskCompleteSource 2 SetResult()
                    (sender as IDisposable)?.Dispose();
                };
                // finally, start the process
                proc.Start();
            }
            catch (Exception ex)
            {
                // signal an exception
                tcs.SetException(ex); // CodeHelper TaskCompleteSource 3 SetException()
            }
            // here we return the task to the caller
            return tcs.Task; // CodeHelper TaskCompleteSource 4 return the Task to the caller.
        }

        /// <summary>
        /// 執行 ProcessStartInfo 並捕捉 StandardOutput 執行結果.
        /// 會封鎖主執行緒.
        /// usage: var psi = new ProcessStartInfo() { FileName = @"..\..\test.exe" }; 
        /// using (var stream = ZRunWithCaptureAsync(psi))
        /// {
        ///   var sr = new StreamReader(stream);
        ///   Console.Write(sr.ReadToEnd());
        /// }
        /// </summary>
        /// <param name="startInfo"></param>
        /// <returns></returns>
        public static Stream ZRunWithCapture(ProcessStartInfo startInfo)
        {
            /*
            ref: https://www.codeproject.com/Tips/5295013/Adapting-Event-and-Callback-Based-Asynchronicity-t
            usage: 
            var psi = new ProcessStartInfo() {
                FileName = "targetapp.exe" 
            };
            using (var stream = RunWithCapture(psi))
            {
                // use a streamreader because we want text
                var sr = new StreamReader(stream);
                // no need to dispose it because 
                // we are disposing the stream
                Console.Write(sr.ReadToEnd());
            }
             */
            // create a process
            var proc = new Process();
            // fill it with what we need to capture
            proc.StartInfo = startInfo;
            proc.EnableRaisingEvents = false;
            startInfo.RedirectStandardOutput = true;
            startInfo.UseShellExecute = false;
            // start doesn't block
            proc.Start();
            // so we use WaitForExit() to block
            proc.WaitForExit();
            // grab our output stream
            var result = proc.StandardOutput.BaseStream;
            // close the process
            proc.Dispose();
            return result;
        }


----------
20210305

public class TaskCompletionSource<TResult>

using System;
using System.Diagnostics;
using System.Threading;
using System.Threading.Tasks;

class TCSDemo
{
    // Demonstrated features:
    // 		TaskCompletionSource ctor()
    // 		TaskCompletionSource.SetResult()
    // 		TaskCompletionSource.SetException()
    //		Task.Result
    // Expected results:
    // 		The attempt to get t1.Result blocks for ~1000ms until tcs1 gets signaled. 15 is printed out.
    // 		The attempt to get t2.Result blocks for ~1000ms until tcs2 gets signaled. An exception is printed out.
    static void Main()
    {
        TaskCompletionSource<int> tcs1 = new TaskCompletionSource<int>();
        Task<int> t1 = tcs1.Task;

        // Start a background task that will complete tcs1.Task
        Task.Factory.StartNew(() =>
        {
            Thread.Sleep(1000);
            tcs1.SetResult(15);
        });

        // The attempt to get the result of t1 blocks the current thread until the completion source gets signaled.
        // It should be a wait of ~1000 ms.
        Stopwatch sw = Stopwatch.StartNew();
        int result = t1.Result;
        sw.Stop();

        Console.WriteLine("(ElapsedTime={0}): t1.Result={1} (expected 15) ", sw.ElapsedMilliseconds, result);

        // ------------------------------------------------------------------

        // Alternatively, an exception can be manually set on a TaskCompletionSource.Task
        TaskCompletionSource<int> tcs2 = new TaskCompletionSource<int>();
        Task<int> t2 = tcs2.Task;

        // Start a background Task that will complete tcs2.Task with an exception
        Task.Factory.StartNew(() =>
        {
            Thread.Sleep(1000);
            tcs2.SetException(new InvalidOperationException("SIMULATED EXCEPTION"));
        });

        // The attempt to get the result of t2 blocks the current thread until the completion source gets signaled with either a result or an exception.
        // In either case it should be a wait of ~1000 ms.
        sw = Stopwatch.StartNew();
        try
        {
            result = t2.Result;

            Console.WriteLine("t2.Result succeeded. THIS WAS NOT EXPECTED.");
        }
        catch (AggregateException e)
        {
            Console.Write("(ElapsedTime={0}): ", sw.ElapsedMilliseconds);
            Console.WriteLine("The following exceptions have been thrown by t2.Result: (THIS WAS EXPECTED)");
            for (int j = 0; j < e.InnerExceptions.Count; j++)
            {
                Console.WriteLine("\n-------------------------------------------------\n{0}", e.InnerExceptions[j].ToString());
            }
        }
    }
}

Remarks
In many scenarios, it is useful to enable a Task<TResult> to represent an external asynchronous operation. TaskCompletionSource<TResult> is provided for this purpose. It enables the creation of a task that can be handed out to consumers. The consumers can use the members of the task the same way as they would in any other scenario handling task member variables. However, unlike most tasks, the state of a task created by a TaskCompletionSource is controlled explicitly by the methods on TaskCompletionSource. This enables the completion of the external asynchronous operation to be propagated to the underlying Task. The separation also ensures that consumers are not able to transition the state without access to the corresponding TaskCompletionSource. For more information, see the entry The Nature of TaskCompletionSource<TResult> in the Parallel Programming with .NET blog.

The Parallel Extensions samples also contain examples of how to use TaskCompletionSource<TResult>.


----------
20210305

When should TaskCompletionSource<T> be used?

ref:
https://stackoverflow.com/questions/15316613/when-should-taskcompletionsourcet-be-used

If I need a way to execute a Func asynchronously and have a Task to represent that operation.

public static Task<T> RunAsync<T>(Func<T> function) 
{ 
    if (function == null) throw new ArgumentNullException(“function”); 
    var tcs = new TaskCompletionSource<T>(); 
    ThreadPool.QueueUserWorkItem(_ => 
    { 
        try 
        {  
            T result = function(); 
            tcs.SetResult(result);  
        } 
        catch(Exception exc) { tcs.SetException(exc); } 
    }); 
    return tcs.Task; 
}
Which could be used *if I didn’t have Task.Factory.StartNew - But I do have Task.Factory.StartNew.

Question:

Can someone please explain by example a scenario related directly to TaskCompletionSource and not to a hypothetical situation in which I don't have Task.Factory.StartNew?



I mostly use it when only an event based API is available (for example Windows Phone 8 sockets):

public Task<Args> SomeApiWrapper()
{
    TaskCompletionSource<Args> tcs = new TaskCompletionSource<Args>(); 

    var obj = new SomeApi();

    // will get raised, when the work is done
    obj.Done += (args) => 
    {
        // this will notify the caller 
        // of the SomeApiWrapper that 
        // the task just completed
        tcs.SetResult(args);
    }

    // start the work
    obj.Do();

    return tcs.Task;
}
So it's especially useful when used together with the C#5 async keyword.







----------
20210223

摘要"Adapting Event and Callback Based Asynchronicity to the Task Framework.pdf"
ref: https://www.codeproject.com/Tips/5295013/Adapting-Event-and-Callback-Based-Asynchronicity-t

Task 本質上是提供一個標準機制, 用來等待工作完成，或報告該工作的錯誤，或提出取消該工作信號.

以下以 System.Diagnostics.Process 示範達成以上行為的 同步版本和非同步版本 程式碼範例。
It is sometimes useful to be able to execute a command line based process and capture the output in your program. You can do
that currently with the Process class by either hooking the Exited event, or using the WaitForExit() method, each
providing its own way to signal completion. Of the two, the former is more flexible, because the latter uncoditionally suspends the
current thread until the process completes, effectively making it blocking - synchronous.
System.Diagnostics.Process 可用來執行指令, 並取得指令的輸出結果.
使用方式可銜接(Exited 事件通知), 或使用(WaitForExit() 方法), 兩者均可發出工作結束訊號來達成同步的目的: 
  前者(Exited 事件通知)為非同步方式, 較具彈性、有效的停止目前的執行緒.
  後者(WaitForExit()方法)為同步方式, 無法預期的停止目前的執行緒, 直到呼叫的執行緒結束後再繼續執行.


後者(WaitForExit()方法)同步方式範例:
  後者(WaitForExit()方法)為同步方式, 無法預期的停止目前的執行緒, 直到呼叫的執行緒結束後再繼續執行.
	static Stream RunWithCapture(ProcessStartInfo startInfo)
	{
	    // create a process
	    var proc = new Process();

	    // fill it with what we need to capture
	    proc.StartInfo = startInfo;
	    proc.EnableRaisingEvents = false;
	    startInfo.RedirectStandardOutput = true;
	    startInfo.UseShellExecute = false;

	    // start doesn't block
	    proc.Start();

	    // so we use WaitForExit() to block
		// 這裡會(阻止主行程執行, 直到子行程結束才會繼續執行)
	    proc.WaitForExit();

	    // grab our output stream
	    var result =proc.StandardOutput.BaseStream;

	    // close the process
	    proc.Dispose();
	    return result;
	}

	// 呼叫方式:
	var psi = new ProcessStartInfo() {
	    FileName = "targetapp.exe" 
	};
	using (var stream = RunWithCapture(psi))
	{
	    // use a streamreader because we want text
	    var sr = new StreamReader(stream);
	    // no need to dispose it because we are disposing the stream
	    Console.Write(sr.ReadToEnd());
	}

前者(Exited 事件通知)非同步方式範例.
  前者(Exited 事件通知)為非同步方式, 較具彈性、有效的停止目前的執行緒.
  Now let's get to the task based asynchronous one. 
  We need to hook the Exited event here instead of calling WaitForExit(), since we can't block.
  以Task<Stream> 銜接到 (Exited) 事件通知, 取代掉同步版本的 WaitForExit()方法, 等待工作結束, 而不是封鎖主執行緒. 
  
	static Task<Stream> RunWithCaptureAsync(ProcessStartInfo startInfo)
	{
	    // we use this as a signal for our custom task
	    // we can use SetResult, SetException, and even SetCancelled
	    // to signal the completion of a task, with or without errors
	    // do not throw exceptions in your async handlers.
	    // Use SetException.
	    var tcs = new TaskCompletionSource<Stream>();
	    try
	    {
	        // create a process, and set it up for capturing
	        // and raising events
	        var proc = new Process();
	        proc.StartInfo = startInfo;
	        proc.EnableRaisingEvents = true;
	        startInfo.RedirectStandardOutput = true;
	        startInfo.UseShellExecute = false;
	        // attach an event handler that signals completion
	        // of our task - here Exited serves us well.
	        // note we're using hoisting to pass the 
	        // TaskCompletionSource through to the anonymous
	        // method:
			// 將 (Exited 事件通知) 銜接到 TaskCompletionSource
	        proc.Exited += (object sender, EventArgs e) => {
	            // if we were doing anything non-trivial here
	            // we'd wrap everything in a try/catch block
	            // and use tcs.SetException() in the catch block
	            // instead of throwing. We don't need that here
	            // because nothing should throw.
				// 若不需要取得完成結果, 則不需要 SetResult() 轉送結果.
	            tcs.SetResult(proc.StandardOutput.BaseStream);
	            (sender as IDisposable)?.Dispose();
	        };
	        // finally, start the process
	        proc.Start();
	    }
	    catch (Exception ex)
	    {
	        // signal an exception
			// Task執行期間, 傳送 exception 給 TaskCompletionSource 表示意外結束, 而不是直接發出 exception.
	        tcs.SetException(ex);
	    }
	    // here we return the task to the caller
	    return tcs.Task;
	}
	
	呼叫方式:

	var psi = new ProcessStartInfo() {
	  FileName = "targetapp.exe"
	};
	using (var stream = await RunWithCaptureAsync(psi))
	{
	    var sr = new StreamReader(stream);
	    Console.Write(sr.ReadToEnd());
	}