Task.txt
20210307

----------
20210307

TaskStatus

#region Assembly mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
// C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.6\mscorlib.dll
#endregion

namespace System.Threading.Tasks
{
    //
    // Summary:
    //     Represents the current stage in the lifecycle of a System.Threading.Tasks.Task.
    public enum TaskStatus
    {
        //
        // Summary:
        //     The task has been initialized but has not yet been scheduled.
        Created = 0,
        //
        // Summary:
        //     The task is waiting to be activated and scheduled internally by the .NET Framework
        //     infrastructure.
        WaitingForActivation = 1,
        //
        // Summary:
        //     The task has been scheduled for execution but has not yet begun executing.
        WaitingToRun = 2,
        //
        // Summary:
        //     The task is running but has not yet completed.
        Running = 3,
        //
        // Summary:
        //     The task has finished executing and is implicitly waiting for attached child
        //     tasks to complete.
        WaitingForChildrenToComplete = 4,
        //
        // Summary:
        //     The task completed execution successfully.
        RanToCompletion = 5,
        //
        // Summary:
        //     The task acknowledged cancellation by throwing an OperationCanceledException
        //     with its own CancellationToken while the token was in signaled state, or the
        //     task's CancellationToken was already signaled before the task started executing.
        //     For more information, see Task Cancellation.
        Canceled = 6,
        //
        // Summary:
        //     The task completed due to an unhandled exception.
        Faulted = 7
    }


----------
20190716

Task asynchronous programming model
ref:

Asynchronous Programming with async and await:
Task asynchronous programming model:
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/task-asynchronous-programming-model
async-await-Task-Programming.pdf

----------
20190717

https://docs.microsoft.com/zh-tw/dotnet/csharp/programming-guide/concepts/async/

非同步工作程式設計模型 (TAP) 在非同步程式碼上提供一個抽象層。 您可以和往常一樣，將程式碼撰寫成一連串的陳述式。 您可以將該程式碼讀成每個陳述式會先完成，再開始下一個陳述式。 編譯器會執行一些轉換，因為部分陳述式可能會開始工作，並傳回表示進行工作的 Task。
這是此語法的目標：讓程式碼讀起來就像是一連串的陳述式，但會根據外部資源配置和工作完成時間，以比較複雜的順序來執行。 這類似於人員為包含非同步工作之程序提供指示的方式。 在本文中，您將以準備早餐的指示為例，來了解 async 和 await 關鍵字如何讓您更輕鬆地理解包含一連串非同步指示的程式碼。 您撰寫了類似下列清單的指示，來說明如何準備早餐：
倒杯咖啡。
熱鍋，然後煎兩顆蛋。
煎三片培根。
烤兩片吐司。
在吐司塗上奶油和果醬。
倒杯柳橙汁。
如果您有烹飪經驗，您會非同步地執行這些指示。 您會從為雞蛋熱鍋開始，然後開始煎培根。 等到將麵包放入烤麵包機，再開始煎蛋。 在程序的每個步驟，您會開始一個工作，然後將注意轉移到其他需要您注意的工作。
準備早餐很適合用來示範非平行的非同步工作。 一個人 (或執行緒) 可處理所有這些工作。 繼續以早餐為例，一個人可能會以非同步方式準備早餐，不等到第一個工作完成，就開始下一個工作。 不論是否有旁觀者，烹飪都會進行。 開始為雞蛋熱鍋之後，您可以開始煎培根。 等到開始煎培根，您可以將麵包放入烤麵包機。
若要進行平行演算法，您需要多個廚師 (或執行緒)。 一個人會負責煎蛋、一個人會負責煎培根，依此類推。 每個人只會專注於一個工作。 每個廚師 (或執行緒) 禁止以同步方式等候培根準備好翻面，或吐司彈出。
現在，考慮將這些相同指示撰寫成 C# 陳述式：
C#

複製
static void Main(string[] args)
{
    Coffee cup = PourCoffee();
    Console.WriteLine("coffee is ready");
    Egg eggs = FryEggs(2);
    Console.WriteLine("eggs are ready");
    Bacon bacon = FryBacon(3);
    Console.WriteLine("bacon is ready");
    Toast toast = ToastBread(2);
    ApplyButter(toast);
    ApplyJam(toast);
    Console.WriteLine("toast is ready");
    Juice oj = PourOJ();
    Console.WriteLine("oj is ready");

    Console.WriteLine("Breakfast is ready!");
}
電腦解譯這些指示的方式與人類不同。 電腦會封鎖每個陳述式，直到工作完成為止，再繼續下一個陳述式。 這會導致早餐無法令人滿意。 後續工作必須等到先前工作完成才會開始。 這會花更長的時間來準備早餐，且在上菜前，有些菜可能會變涼。
如果您想要電腦以非同步方式執行上述指示，您必須撰寫非同步程式碼。
這些考量對您現今撰寫的程式很重要。 當您撰寫用戶端程式時，您想要 UI 可以回應使用者輸入。 您的應用程式不應該讓手機在從網路下載資料時呈現凍結。 當您撰寫伺服器程式時，您不想要執行緒被封鎖。 這些執行緒可能會服務其他要求。 在存在替代的非同步程式碼時使用同步程式碼，會導致您無法以較不耗費成本的方式擴充。 這些封鎖的執行緒會耗費成本。
現代化應用程式需要非同步程式碼才能成功。 由於沒有語言支援，撰寫非同步程式碼需要回呼、完成事件，或隱藏程式碼原本意圖的其他方式。 同步程式碼的優點是容易了解。 逐步動作讓您可以輕鬆地瀏覽與了解。 傳統非同步模型迫使您將重點放在程式碼的非同步本質，而不是程式碼的基本動作。
不要封鎖，而是等候

上述程式碼示範不正確的做法：建構同步程式碼來執行非同步作業。 如內容所指，此程式碼會防止執行緒執行任何其他工作。 在任何工作進行時，它不會遭到中斷。 就像是將麵包放入烤麵包機之後，直盯著烤麵包機。 在吐司彈出之前，您不會理會任何人對您說的話。
我們將從更新此程式碼開始，讓執行緒在工作執行時不會遭到封鎖。 await 關鍵字提供一個非封鎖方式來開始工作，然後在工作完成時繼續執行。 準備早餐程式碼的一個簡單非同步版本看起來像下列程式碼片段：
C#

複製
static async Task Main(string[] args)
{
    Coffee cup = PourCoffee();
    Console.WriteLine("coffee is ready");
    Egg eggs = await FryEggs(2);
    Console.WriteLine("eggs are ready");
    Bacon bacon = await FryBacon(3);
    Console.WriteLine("bacon is ready");
    Toast toast = await ToastBread(2);
    ApplyButter(toast);
    ApplyJam(toast);
    Console.WriteLine("toast is ready");
    Juice oj = PourOJ();
    Console.WriteLine("oj is ready");

    Console.WriteLine("Breakfast is ready!");
}
此程式碼不會在煎蛋或煎培根時封鎖其他工作。 但此程式碼也不會開始任何其他工作。 您仍會將吐司放入烤麵包機，並在彈出前直盯著它瞧。 但至少，您會回應任何需要您注意的人。 在點了多份早餐的餐廳中，廚師可能會在第一份早餐還在準備時，就開始準備另一份早餐。
現在，準備早餐的執行緒在等候任何已開始但尚未完成的工作時，不會遭到封鎖。 對於某些應用程式而言，只需要這項變更。 GUI 應用程式仍會只以這項變更來回應使用者。 不過在此案例中，您需要不只一項變更。 您不想要循序執行每個元件工作。 較好的做法是開始每個元件工作，然後等候先前的工作完成。
同時開始工作

在許多情況下，您想要立即開始數個獨立工作。 然後，在每個工作完成時，您可以繼續其他準備好的工作。 以早餐為例，這會讓您更快速地完成早餐。 您也會幾乎同時完成所有工作。 因此，您會有熱騰騰的早餐。
System.Threading.Tasks.Task 和相關類型是您可以用來理解進行中工作的類別。 這可讓您撰寫出更類似您實際準備早餐方式的程式碼。 您會同時開始煎蛋、煎培根和烤吐司。 由於每個工作都需要執行動作，因此您會將注意轉移到該工作、處理下一個動作，然後等候其他需要您注意的工作。
您會開始一個工作，並保存表示該工作的 Task 物件。 您會 await 每個工作，再處理其結果。
我們將對早餐程式碼進行這些變更。 第一個步驟是為作業儲存開始時的工作，而不是等候工作：
C#

複製
Coffee cup = PourCoffee();
Console.WriteLine("coffee is ready");
Task<Egg> eggTask = FryEggs(2);
Egg eggs = await eggTask;
Console.WriteLine("eggs are ready");
Task<Bacon> baconTask = FryBacon(3);
Bacon bacon = await baconTask;
Console.WriteLine("bacon is ready");
Task<Toast> toastTask = ToastBread(2);
Toast toast = await toastTask;
ApplyButter(toast);
ApplyJam(toast);
Console.WriteLine("toast is ready");
Juice oj = PourOJ();
Console.WriteLine("oj is ready");

Console.WriteLine("Breakfast is ready!");
接下來，您可以將培根與雞蛋的 await 陳述式移至方法結尾，並在供應早餐之前：
C#

複製
Coffee cup = PourCoffee();
Console.WriteLine("coffee is ready");
Task<Egg> eggTask = FryEggs(2);
Task<Bacon> baconTask = FryBacon(3);
Task<Toast> toastTask = ToastBread(2);
Toast toast = await toastTask;
ApplyButter(toast);
ApplyJam(toast);
Console.WriteLine("toast is ready");
Juice oj = PourOJ();
Console.WriteLine("oj is ready");

Egg eggs = await eggTask;
Console.WriteLine("eggs are ready");
Bacon bacon = await baconTask;
Console.WriteLine("bacon is ready");

Console.WriteLine("Breakfast is ready!");
上述程式碼的效果更好。 您會同時開始所有非同步工作。 只有需要結果時，才會等候每個工作。 上述程式碼可能會類似於提出不同微服務要求，然後將結果合併成單一頁面的 Web 應用程式程式碼。 您會立即提出所有要求，然後 await 所有這些工作並撰寫網頁。
工作組合

您同時準備好早餐的每道菜，除吐司以外。 準備吐司是非同步作業 (烤土司) 以及同步作業 (塗上奶油和果醬) 的組合。 更新此程式碼說明一個重要概念：
 重要
非同步作業後面接著同步工作的組合會是非同步作業。 換句話說，如果作業有任何部分為非同步，則整個作業是非同步。
上述程式碼顯示您可以使用 Task 或 Task<TResult> 物件來保存執行中的工作。 您會 await 每個工作，再使用其結果。 下一個步驟是建立表示其他工作組合的方法。 在供應早餐之前，您想要等候表示烤土司後再塗上奶油和果醬的工作。 您可以使用下列程式碼來表示該工作：
C#

複製
async Task<Toast> makeToastWithButterAndJamAsync(int number)
{
    var plainToast = await ToastBreadAsync(number);
    ApplyButter(plainToast);
    ApplyJam(plainToast);
    return plainToast;
}
上述方法的簽章中有 async 修飾詞。 這會通知編譯器，此方法包含 await 陳述式，其中包含非同步作業。 此方法表示烤土司後再塗上奶油和果醬的工作。 此方法會傳回 Task<TResult>，表示這三項作業的組合。 程式碼的 Main 區塊現在會變成：
C#

複製
static async Task Main(string[] args)
{
    Coffee cup = PourCoffee();
    Console.WriteLine("coffee is ready");
    var eggsTask = FryEggsAsync(2);
    var baconTask = FryBaconAsync(3);
    var toastTask = makeToastWithButterAndJamAsync(2);

    var eggs = await eggsTask;
    Console.WriteLine("eggs are ready");
    var bacon = await baconTask;
    Console.WriteLine("bacon is ready");
    var toast = await toastTask;
    Console.WriteLine("toast is ready");
    Juice oj = PourOJ();
    Console.WriteLine("oj is ready");

    Console.WriteLine("Breakfast is ready!");

    async Task<Toast> makeToastWithButterAndJamAsync(int number)
    {
        var plainToast = await ToastBreadAsync(number);
        ApplyButter(plainToast);
        ApplyJam(plainToast);
        return plainToast;
    }
}
上述變更說明使用非同步程式碼的重要技術。 您可以透過分隔作業，將多個工作組合成傳回一個工作的新方法。 您可以選擇何時等候該工作。 您可以同時開始其他工作。
有效率地等候工作

上述程式碼結尾的一連串 await 陳述式，可以透過 Task 類別的方法來改善。 其中一個 API 是 WhenAll，它會傳回其引數清單中所有工作都已完成時所完成的 Task，如下列程式碼所示：
C#

複製
await Task.WhenAll(eggTask, baconTask, toastTask);
Console.WriteLine("eggs are ready");
Console.WriteLine("bacon is ready");
Console.WriteLine("toast is ready");
Console.WriteLine("Breakfast is ready!");
另一個選項是使用 WhenAny，它會傳回其任何引數完成時所完成的 Task<Task>。 您可以等候傳回的工作，並知道它已完成。 下列程式碼範例示範如何使用 WhenAny 等候第一個工作完成，再處理其結果。 處理完成工作的結果之後，您會從傳遞至 WhenAny 的工作清單中移除該完成工作。
C#

複製
var allTasks = new List<Task>{eggsTask, baconTask, toastTask};
while (allTasks.Any())
{
    Task finished = await Task.WhenAny(allTasks);
    if (finished == eggsTask)
    {
        Console.WriteLine("eggs are ready");
    }
    else if (finished == baconTask)
    {
        Console.WriteLine("bacon is ready");
    }
    else if (finished == toastTask)
    {
        Console.WriteLine("toast is ready");
    }
    allTasks.Remove(finished);
}
Console.WriteLine("Breakfast is ready!");
完成上述所有變更之後，Main 的最終版本看起來像下列程式碼：
C#

複製
static async Task Main(string[] args)
{
    Coffee cup = PourCoffee();
    Console.WriteLine("coffee is ready");
    var eggsTask = FryEggsAsync(2);
    var baconTask = FryBaconAsync(3);
    var toastTask = makeToastWithButterAndJamAsync(2);

    var allTasks = new List<Task>{eggsTask, baconTask, toastTask};
    while (allTasks.Any())
    {
        Task finished = await Task.WhenAny(allTasks);
        if (finished == eggsTask)
        {
            Console.WriteLine("eggs are ready");
        }
        else if (finished == baconTask)
        {
            Console.WriteLine("bacon is ready");
        }
        else if (finished == toastTask)
        {
            Console.WriteLine("toast is ready");
        }
        allTasks.Remove(finished);
    }
    Console.WriteLine("Breakfast is ready!");

    async Task<Toast> makeToastWithButterAndJamAsync(int number)
    {
        var plainToast = await ToastBreadAsync(number);
        ApplyButter(plainToast);
        ApplyJam(plainToast);
        return plainToast;
    }
}
此最終程式碼為非同步。 它會更精確地反映人員準備早餐的方式。 將上述程式碼與本文中的第一個程式碼範例做比較。 閱讀程式碼仍會清楚了解核心動作。 閱讀此程式碼的方式，如同閱讀本文開頭準備早餐的指示。 async 和 await 之語言功能為所有遵循下列書面指示的人員提供轉譯：盡可能開始多個工作且不要防止等候工作完成。



----------
20181118

#if ZSAMPLE
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
// add 
using System.Threading;

namespace ZLib.DCodeHelper
{
    public class TaskSample
    {
        public void TestTask1()
        {
            // 寫法 1 - .NET 2 開始提供 ThreadPool.QueueUserWorkItem
            ThreadPool.QueueUserWorkItem(state => myTaskWithNoArg());  // Sample: ThreadPool.QueueUserWorkItem() 無參數
            ThreadPool.QueueUserWorkItem(state => myTaskWithArg(1));

            // 寫法 2 - .NET 4 開始提供 Task 類別。
            // 等同於 new Task(new Action(MyTask));
            var t = new Task(myTaskWithNoArg);
            t.Start();
            var tWithArg = new Task(() => myTaskWithArg(2));
            tWithArg.Start();

            // 這個寫法同寫法2(沒有傳入參數)
            var tSame = new Task(new Action(myTaskWithNoArg));
            tSame.Start();
            // 但是傳入參數, 以下寫法都不行:
            // Task.Factory.StartNew(myTaskWithArg, 2); // error: cannot convert from 'method group' to 'action'.
            // Task.Factory.StartNew(new Action<int>(myTaskWithArg), 2); // error: cannot convert from 'method group' to 'action'.
            // Task.Factory.StartNew(new Action<object>(myTaskWithArg), 2); // no overload for 'myTaskWithArg' matches delegate 'Action<object>'
            // 必須先把委派函數的參數改為object型態, 再參考如下呼叫
            Task.Factory.StartNew(myTaskWithArgObject, 1); // OK!
            Task.Factory.StartNew(new Action<Object>(myTaskWithArgObject), 2); // OK! 效果同上。

            // 寫法 3 - 也可以用靜態方法直接建立並開始執行工作。
            Task.Factory.StartNew(myTaskWithNoArg);
            Task.Factory.StartNew(() => myTaskWithArg(3));


            // 寫法 4 - .NET 4.5 的 Task 類別新增了靜態方法 Run。
            // Task.Run()僅支援Action委派, 無回傳值也無輸入參數.
            Task.Run(() => myTaskWithNoArg());
            Task.Run(() => myTaskWithArg(4));

            // 取得結果
            string url = "http://www.microsoft.com.tw";
            var task = new Task<int>(GetContentLength, url);    // 建立工作。
            task.Start();   // 起始工作。
            task.Wait();    // 等待工作。
            int length = task.Result;   // 取得結果。
            Console.WriteLine("Content length: {0}", length);

            // 執行結果:
            //工作執行緒 #12
            //num = 1
            //工作執行緒 #13
            //num = 2
            //工作執行緒 #12
            //工作執行緒 #12
            //num = 1
            //num = 2
            //num = 4
            //工作執行緒 #14
            //num = 3
            //Content length: 152770
        }
        public void TestTask2WithArg()
        {
            // 這裡示範 (帶入參數)執行非同步工作

            ThreadPool.QueueUserWorkItem(state => myTaskWithArg(1));

            var tWithArg = new Task(() => myTaskWithArg(2));
            tWithArg.Start();

            Task.Factory.StartNew(() => myTaskWithArg(3));

            Task.Run(() => myTaskWithArg(4));
        }


        void myTaskWithNoArg()
        {
            Console.WriteLine("工作執行緒 #{0}", Thread.CurrentThread.ManagedThreadId);
        }

        void myTaskWithArg(int num)
        {
            Console.WriteLine("num = {0}", num);
        }

        void myTaskWithArgObject(object state)
        {
            int num = (int)state;
            Console.WriteLine("num = {0}", num);
        }

        int GetContentLength(object stateURL)
        {
            var client = new System.Net.Http.HttpClient();
            var url = stateURL as string;
            try
            {
                return client.GetStringAsync(url).Result.Length;
            }
            catch (Exception e1)
            {
                Console.WriteLine(e1.Message);
                return 0;
            }
        }



        public void testTaskMSDN1()
        {
            // Task 語法需銜接(action delegate) 或 (lambda inline)

            // 以 lambda 語法 定義 action delegate 的 inline 程式邏輯.
            // Thread.CurrentThread.ManagedThreadId 可取得目前的 threadid
            Action<object> action = (object obj) =>
            {
                Console.WriteLine("Task={0}, obj={1}, Thread={2}",
                Task.CurrentId, obj,
                Thread.CurrentThread.ManagedThreadId);
            };

            // Create a task but do not start it.
            // Task 語法1: 只建立Task, 但是還不啟動執行.
            Task t1 = new Task(action, "alpha");

            // Construct a started task.  
            // Task 語法2: 建立並啟動 Task.
            Task t2 = Task.Factory.StartNew(action, "beta");

            // Block the main thread to demonstrate that t2 is executing. 
            // Task 可以等待完成後, 再繼續執行主執行緒.
            t2.Wait();

            // Launch t1 啟動執行已建立的 Task.
            t1.Start();
            Console.WriteLine("t1 has been launched. (Main Thread={0})",
                              Thread.CurrentThread.ManagedThreadId);
            // Wait for the task to finish.
            t1.Wait();

            // Construct a started task using Task.Run. 
            // Task t3 以 lambda 語法, 呼叫Task.Run()建立inline程式邏輯, 可取代麻煩的(定義 action delegate 的 inline 程式邏輯), 並立刻啟動執行.
            String taskData = "delta";
            Task t3 = Task.Run(() =>
            {
                Console.WriteLine("Task={0}, obj={1}, Thread={2}",
                                  Task.CurrentId, taskData,
                                   Thread.CurrentThread.ManagedThreadId);
            });
            // Wait for the task to finish.
            t3.Wait();

            // Construct an unstarted task
            Task t4 = new Task(action, "gamma");
            // Run it synchronously 以同步方式執行.
            t4.RunSynchronously();
            // Although the task was run synchronously, it is a good practice
            // to wait for it in the event exceptions were thrown by the task.
            // 即使是同步方式執行, 最好還是等待 Task 發出來的 event exceptions.
            t4.Wait();

            // The example displays output like the following:
            //       Task=1, obj=beta, Thread=3
            //       t1 has been launched. (Main Thread=1)
            //       Task=2, obj=alpha, Thread=4
            //       Task=3, obj=delta, Thread=3
            //       Task=4, obj=gamma, Thread=1

        }
        public async Task testTaskMSDN2()
        {
            ////////// 最常見的啟動Task方式, 是使用.net 4.5提供的靜態方法 Task.Run().
            await Task.Run(() =>
            {
                // Just loop.
                int ctr = 0;
                for (ctr = 0; ctr <= 1000000; ctr++)
                { }
                Console.WriteLine("Finished {0} loop iterations",
                                  ctr);
            });
            // The example displays the following output:
            //        Finished 1000001 loop iterations

        }
        public void TestTaskMsdn3StartNew()
        {
            ////////// 或是使用.net 4.0提供的靜態方法 TaskFactory.StartNew()
            Task t = Task.Factory.StartNew(() =>
            {
                // Just loop.
                int ctr = 0;
                for (ctr = 0; ctr <= 1000000; ctr++)
                { }
                Console.WriteLine("Finished {0} loop iterations",
                                  ctr);
            });
            t.Wait();
            // The example displays the following output:
            //        Finished 1000001 loop iterations
        }
        public void testTaskMSDN4Wait()
        {
            // Wait的用法

            // Wait on a single task with no timeout specified.
            Task taskA = Task.Run(() => Thread.Sleep(2000));
            Console.WriteLine("taskA Status: {0}", taskA.Status);
            try
            {
                ////////// 使用 Wait() 可等待非同步執行的Task完成後再繼續執行.
                taskA.Wait();

                // 這裡寫出的WriteLine()會出現在AggregateException 後面.
                Console.WriteLine("taskA Status: {0}", taskA.Status);
            }
            catch (AggregateException)
            {
                Console.WriteLine("Exception in taskA.");
            }
            // The example displays output like the following:
            //     taskA Status: WaitingToRun
            //     taskA Status: RanToCompletion


            // Wait on a single task with a timeout specified.
            Task taskB = Task.Run(() => Thread.Sleep(2000));
            try
            {
                /////////// 使用 Wait(int32) 可等待非同步執行的完成後, 或指定的時間後, 再繼續執行.
                taskB.Wait(1000);       // Wait for 1 second.

                bool completed = taskB.IsCompleted;
                Console.WriteLine("Task B completed: {0}, Status: {1}",
                                 completed, taskB.Status);
                if (!completed)
                    Console.WriteLine("Timed out before task B completed.");
            }
            catch (AggregateException)
            {
                Console.WriteLine("Exception in taskB.");
            }
            // The example displays output like the following:
            //     Task B completed: False, Status: Running
            //     Timed out before task B completed.
        }
        void testTask4WaitAny()
        {
            // 使用 WaitAny: 任一個task完成時.
            var tasks = new Task[3];
            var rnd = new Random();
            for (int ctr = 0; ctr <= 2; ctr++)
                tasks[ctr] = Task.Run(() => Thread.Sleep(rnd.Next(500, 3000)));

            try
            {
                int index = Task.WaitAny(tasks);
                Console.WriteLine("Task #{0} completed first.\n", tasks[index].Id);
                Console.WriteLine("Status of all tasks:");
                foreach (var t in tasks)
                    Console.WriteLine("   Task #{0}: {1}", t.Id, t.Status);
            }
            catch (AggregateException)
            {
                Console.WriteLine("An exception occurred.");
            }
            // The example displays output like the following:
            //     Task #1 completed first.
            //     
            //     Status of all tasks:
            //        Task #3: Running
            //        Task #1: RanToCompletion
            //        Task #4: Running

        }
        void testTaskMsdnWaitAll()
        {
            // 使用WaitAll: 等待所有的task都完成

            // Wait for all tasks to complete.
            Task[] tasks = new Task[10];
            for (int i = 0; i < 10; i++)
            {
                tasks[i] = Task.Run(() => Thread.Sleep(2000));
            }
            try
            {
                Task.WaitAll(tasks);
            }
            catch (AggregateException ae)
            {
                Console.WriteLine("One or more exceptions occurred: ");
                foreach (var ex in ae.Flatten().InnerExceptions)
                    Console.WriteLine("   {0}", ex.Message);
            }

            Console.WriteLine("Status of completed tasks:");
            foreach (var t in tasks)
                Console.WriteLine("   Task #{0}: {1}", t.Id, t.Status);

            // The example displays the following output:
            //     Status of completed tasks:
            //        Task #2: RanToCompletion
            //        Task #1: RanToCompletion
            //        Task #3: RanToCompletion
            //        Task #4: RanToCompletion
            //        Task #6: RanToCompletion
            //        Task #5: RanToCompletion
            //        Task #7: RanToCompletion
            //        Task #8: RanToCompletion
            //        Task #9: RanToCompletion
            //        Task #10: RanToCompletion

        }

        void testTaskMsdnCancel()
        {
            // 使用 cancel.
            // 以下範例啟動12個Task: 3個正常結束, 3個例外結束, 3個還沒開始就先取消, 3個在執行中取消.

            // Create a cancellation token and cancel it.
            var source1 = new CancellationTokenSource();
            var token1 = source1.Token;
            source1.Cancel();
            // Create a cancellation token for later cancellation.
            var source2 = new CancellationTokenSource();
            var token2 = source2.Token;

            // Create a series of tasks that will complete, be cancelled, 
            // timeout, or throw an exception.
            Task[] tasks = new Task[12];
            for (int i = 0; i < 12; i++)
            {
                switch (i % 4)
                {
                    // Task should run to completion.
                    case 0:
                        tasks[i] = Task.Run(() => Thread.Sleep(2000));
                        break;
                    // Task should be set to canceled state.
                    case 1:
                        tasks[i] = Task.Run(() => Thread.Sleep(2000),
                                 token1);
                        break;
                    case 2:
                        // Task should throw an exception.
                        tasks[i] = Task.Run(() => { throw new NotSupportedException(); });
                        break;
                    case 3:
                        // Task should examine cancellation token.
                        tasks[i] = Task.Run(() =>
                        {
                            Thread.Sleep(2000);
                            if (token2.IsCancellationRequested)
                                token2.ThrowIfCancellationRequested();
                            Thread.Sleep(500);
                        }, token2);
                        break;
                }
            }
            Thread.Sleep(250);
            source2.Cancel();

            try
            {
                Task.WaitAll(tasks);
            }
            catch (AggregateException ae)
            {
                Console.WriteLine("One or more exceptions occurred:");
                foreach (var ex in ae.InnerExceptions)
                    Console.WriteLine("   {0}: {1}", ex.GetType().Name, ex.Message);
            }

            Console.WriteLine("\nStatus of tasks:");
            foreach (var t in tasks)
            {
                Console.WriteLine("   Task #{0}: {1}", t.Id, t.Status);
                if (t.Exception != null)
                {
                    foreach (var ex in t.Exception.InnerExceptions)
                        Console.WriteLine("      {0}: {1}", ex.GetType().Name,
                                          ex.Message);
                }
            }
            // The example displays output like the following:
            //   One or more exceptions occurred:
            //      TaskCanceledException: A task was canceled.
            //      NotSupportedException: Specified method is not supported.
            //      TaskCanceledException: A task was canceled.
            //      TaskCanceledException: A task was canceled.
            //      NotSupportedException: Specified method is not supported.
            //      TaskCanceledException: A task was canceled.
            //      TaskCanceledException: A task was canceled.
            //      NotSupportedException: Specified method is not supported.
            //      TaskCanceledException: A task was canceled.
            //   
            //   Status of tasks:
            //      Task #13: RanToCompletion
            //      Task #1: Canceled
            //      Task #3: Faulted
            //         NotSupportedException: Specified method is not supported.
            //      Task #8: Canceled
            //      Task #14: RanToCompletion
            //      Task #4: Canceled
            //      Task #6: Faulted
            //         NotSupportedException: Specified method is not supported.
            //      Task #7: Canceled
            //      Task #15: RanToCompletion
            //      Task #9: Canceled
            //      Task #11: Faulted
            //         NotSupportedException: Specified method is not supported.
            //      Task #12: Canceled

        }

    }
}
#endif

----------
20181118

Thread vs Task

Thread is a lower-level concept: if you're directly starting a thread, you know it will be a separate thread, rather than executing on the thread pool etc.

Task is more than just an abstraction of "where to run some code" though - it's really just "the promise of a result in the future". So as some different examples:
  1. Task.Delay doesn't need any actual CPU time; it's just like setting a timer to go off in the future
  2. A task returned by WebClient.DownloadStringTaskAsync won't take much CPU time locally; it's representing a result which is likely to spend most of its time in network latency or remote work (at the web server)
  3. A task returned by Task.Run() really is saying "I want you to execute this code separately"; the exact thread on which that code executes depends on a number of factors.

Note that the Task<T> abstraction is pivotal to the async support in C# 5.

In general, I'd recommend that you use the higher level abstraction wherever you can: in modern C# code you should rarely need to explicitly start your own thread.

Thread 是低階控制的概念. 啟動thread會執行於不同的執行緒, 而不是在執行緒池中.
Task 並非僅提供"在何處執行程式"的抽象概念-而是僅確保未來的執行結果. 以下為差異處
  1. Task.Delay 不需要任何實際的CPU時間. 使用上如timer設定以後, 就會被啟動執行.
  2. Task 回傳 WebClient.DownloadStringTaskAsync的結果, 不會耗用太多CPU時間. 這表示出大部份的時間花在網路的延遲以及遠端主機的工作上.
  3. 經由Task.Run() 回傳的task 的實際意義為: 分別執行程式. 實際上執行程式的thread, 取決於幾個因子. 
注意: Task<T>抽象物件是 C# 5.0 的 async 非同步方法關鍵字的主要支援.
建議盡量使用高階的抽象物件. 在現在的C#程式碼中, 應該很少需要自行啟動thread.

----------
20181118

Task
TPL: Task Parallel Library

ref:
https://www.huanlintalk.com/2013/06/csharp-notes-multithreading-6-tpl.html

是啊，經過前面幾篇筆記的緩慢爬梳，從執行緒的基本概念到如何使用執行緒集區（ThreadPool）來建立及起始非同步工作，再談到非同步工作的取消與逾時。除了異常處理（exception handling）之外，非同步操作的基本功大致都點到了吧（沒點到請舉手）。
有了這些基本功，希望接下來的 TPL 可以像倒吃甘蔗，漸入佳境，也漸漸加速（希望啦）。

Task Parallel Library
使用 Thread 類別的 QueueUserWorkItem 方法來進行非同步操作雖然很簡單，可是它缺了兩項基本功能：得知非同步工作何時完成，以及當工作完成時取得其執行結果。倒不是說，使用 QueueUserWorkItem 就完全無法得知非同步工作的完成時機與結果，而是開發人員得額外花一番工夫才能做到。因此，微軟從 .NET Framework 4 開始提供了以工作為基礎的（task-based）概念，並將相關類別放在 System.Threading.Tasks 命名空間裡。這些類別形成了一組 API，統稱為 Task Parallel Library，簡稱 TPL。到了 .NET Framework 4.5，TPL 又有一些擴充和改進，程式寫起來又稍微容易些。

起始非同步工作
TPL 的核心類別是 Task，所以接著就來看看如何使用 Task 類別來處理非同步工作。首先要了解的，當然就是建立和起始非同步工作了。
範例程式：

static void Main(string[] args)
{
    // 寫法 1 - .NET 2 開始提供
    ThreadPool.QueueUserWorkItem(state => MyTask());

    // 寫法 2 - .NET 4 開始提供 Task 類別。
    var t = new Task(MyTask);   // 等同於 new Task(new Action(MyTask));
    t.Start();

    // 寫法 3 - 也可以用靜態方法直接建立並開始執行工作。
    Task.Factory.StartNew(MyTask);

    // 寫法 4 - .NET 4.5 的 Task 類別新增了靜態方法 Run。
    Task.Run(() => MyTask());

    Console.ReadLine();
}

static void MyTask()
{
    Console.WriteLine("工作執行緒 #{0}", Thread.CurrentThread.ManagedThreadId);
}

執行結果:
工作執行緒 #3
工作執行緒 #5
工作執行緒 #4
工作執行緒 #6


此範例的重點不在執行結果，而是在示範各種寫法。第一種寫法，也就是先前介紹過的，使用 .NET 2.0 開始就提供的 ThreadPool.QueueUserWorkItem 方法來建立非同步工作。第二種寫法使用 .NET 4 提供的 TPL，以 new Task 的方式來建立 Task 物件──代表一項工作；建立好的工作可以在稍後需要的時候才呼叫 Task 物件的 Start 方法來開始執行工作。這表示我們甚至可以先建立好 Task 物件，然後把它當作參數傳遞給其他函式，並由其他函式在適當時機起始工作。不過，比較常見的情形還是在建立工作之後緊接著執行工作，所以 .NET Framework 另外提供了簡便的方法，讓我們可透過 Task.Factory 屬性來取得 TaskFactory 類別的執行個體，再呼叫它的 StartNew 方法來開始執行工作（寫法 3）。

Task.Factory.StartNew 雖然能夠一次完成建立工作和起始工作的程序，可是它的多載版本多達 16 種，雖然提供了更細緻的控制，但是對於初次使用的人來說，恐怕容易眼花撩亂，不知該用哪個版本。於是 .NET 4.5 為 Task 類別提供了比較陽春、簡便的靜態方法：Run 。此方法僅 8 種版本，功能沒有 Task.Factory.StartNew 那麼多，但相對容易上手。

剛才的範例中，欲執行的非同步工作是不帶任何輸入參數的 MyTask 方法。如需傳入參數，程式寫法其實也差不多，。這裡再提供一個帶參數的版本，方便參考對照。
static void Main(string[] args)
{
    ThreadPool.QueueUserWorkItem(state => MyTask(1));

    var t = new Task(() => MyTask(2));
    t.Start();

    Task.Factory.StartNew(() => MyTask(3));

    Task.Run(() => MyTask(4));
}

static void MyTask(int num)
{
    Console.WriteLine("num = {0}", num);
}

接著要稍微岔開，順便提個小細節，與泛型委派的型別相容有關。（以下細節討論似乎有點囉嗦，考慮刪去）

即便上述範例中的 MyTask 方法需要傳入一個 int 型別的參數，在呼叫 Task.Factory.StartNew 和 Tas.Run 方法時，傳入的委派其實都是不帶任何輸入參數的 Action 委派（.NET 提供了多種 Action 委派的泛型版本，主要用於無回傳值以及零至多個輸入參數的場合；詳情請參閱 MSDN線上文件）。除了傳遞 Action 委派，Task.Factory.StartNew 還提供了一個多載版本可以傳入 Action<Object> 委派，但 Task.Run 方法僅支援 Action 委派，亦即無回傳值、亦無任何輸入參數。以下是 Task.Factory.StartNew 方法的其中兩個多載版本的原型宣告：

public Task StartNew(Action action)
public Task StartNew(Action<Object> action, Object state)

如果要使用 Action<Object> 來傳遞自訂參數，直覺上可能會以為只要把先前範例中的 Task.Factory.StartNew 敘述稍微修改一下就行，例如底下這三種寫法： 
Task.Factory.StartNew(MyTask, 2); // 編譯失敗: 找不到符合的多載方法。
Task.Factory.StartNew(new Action<int>(MyTask), 2); // 同上。
Task.Factory.StartNew(new Action<Object>(MyTask), 2); // 編譯失敗:
            // MyTask 沒有提供傳入 'System.Action<Object>' 委派的多載方法。

如註解所說，上述寫法皆無法通過編譯。可是，MyTask 函式確實是接受一個 int 參數啊，為什麼連第二種寫法都編譯失敗呢？

看一下前面列出的兩個 StartNew 多載方法的原型宣告，第二個版本是接受兩個參數，其中第一個參數的型別是  Action<Object> 委派。然而前述範例卻是傳入 Action<int> 委派。這裡產生了型別不相容的問題。

再往源頭追，從 MSDN 線上資源找到 Action<T> 委派的原型宣告：
public delegate void Action<in t>(T obj)

注意泛型參數 T 前面的修飾詞「in」，代表這是個逆變型（contravariant）參數。用白話文來解釋，就是此型別參數 T 只接受 T 本身及其父代型別，而不接受子代型別。因此，先前範例中傳入的 Action<int> 不符規定──int 既不是 Object 也不是 Object 的父代型別──編譯失敗。

有關泛型的共變（covariance）與逆變（contravariance），可參閱另一篇筆記＜C# 4.0：Covariance 與 Contravariance 觀念入門＞或 MSDN 文件：Covariance and Contravariance in Generics。

結論是，如欲傳遞 Action<Object> 委派給 TaskFactory 的 StartNew 方法，目標函式（即範例中的 MyTask 方法）必須傳入一個 Object 型別的參數。正解如下：

static void Main(string[] args)
{
    Task.Factory.StartNew(MyTask, 1); // OK!
    Task.Factory.StartNew(new Action<Object>(MyTask), 2); // OK! 效果同上。
}

static void MyTask(Object state)
{
    int num = (int) state;
    Console.WriteLine("num = {0}", num);
}

取得工作執行結果

稍早提過，TPL 比 ThreadPool 類別好用的一個地方，是它本身就提供了取得非同步工作的執行結果的機制。執行結果當然是得等到工作執行完畢方能獲得，所以本節所要介紹的非同步操作技巧其實包含兩個步驟：先等待工作執行完畢，然後取得執行結果。底下是個簡單範例：

static void Main(string[] args)
{
    string url = "https://www.huanlintalk.com/";
    var task = new Task<int>(GetContentLength, url);    // 建立工作。

    task.Start();   // 起始工作。

    task.Wait();    // 等待工作。

    int length = task.Result;   // 取得結果。
    Console.WriteLine("Content length: {0}", length);
}

static int GetContentLength(object state)
{
    var client = new System.Net.Http.HttpClient();
    var url = state as string;
    return client.GetStringAsync(url).Result.Length;
}


程式說明：
GetContentLength 方法的任務是傳回指定網頁的內容長度，網頁的 URL 是由參數 state 指定。
由於 Task.Run 靜態方法所提供的多載版本並未支援傳入參數，故此範例採用建立 Task 物件的方式來執行非同步工作。欲執行之非同步工作 GetContentLength 有回傳值，所以建立 Task 物件時所使用之類別為其泛型版本 Task<TResult>；而回傳的型別是 int，於是將 TResult 換成 int，便得到Task<int>。
建立 Task 物件之後，呼叫 Start 方法來起始非同步工作，然後呼叫 Wait 以等待工作執行完畢，再透過 Task 物件的 Result 屬性取得結果。這裡的 Wait 呼叫亦可省略，因為存取 Task 的 Result 屬性時也會等待工作執行完畢。

執行結果：
Content length: 88888

需特別說明的是，Task 物件開始執行之後，呼叫 Wait 方法會令目前的執行緒暫停，等到非同步工作執行完畢之後才會繼續往下執行。但如果 Task 物件並未開始執行（未曾呼叫其 Start 方法）就呼叫了 Wait 方法，視情況而定，有可能會執行非同步工作並立即返回，也有可能產生奇怪的狀況。

以這個例子來說，若將 task.Start() 這行程式碼註解掉，程式執行到 task.Wait() 時會陷入無窮等待的鎖死狀態（dead lock）。那麼，究竟什麼條件下能夠令它順利執行，什麼條件下會導致鎖死呢？這得看當時使用的 TaskScheduler 物件（此範例係使用預設的 TaskScheuler 執行個體）。

至於 TaskScheduler 類別，它也是隸屬 System.Threading.Tasks 命名空間，主要是負責將非同步工作排入佇列並配給執行緒等等比較低階的處理。目前先大概知道這東西做啥用的就夠了，將來有空再細究吧（或者直接參考 MSDN 文件有關 TaskScheduler 的說明）。

小結

這篇筆記簡單介紹了 TPL 的一部分基本用法，包括建立與起始非同步工作，以及等待工作執行完成並取得執行結果。另外還有工作取消、異常處理的基本課題，再加上末尾出現的 TaskSchedular，以及父子巢狀工作的處理.....

		
			

----------
20180928

Task
Represents an asynchronous operation
非同步作業

摘要:
1. Task 物件是.NET Framework 4 以上新增的 task-based asynchronous pattern 之一.
2. Task 語法代表(沒有回傳值的單一作業). 若需要回傳值, 可使用Task<TResult>.
3. Task 通常是以非同步執行方式, 執行於 Thread pool中, 而不是主執行緒中, 可以Status, IsCanceled, IsCompleted...等屬性查詢task執行狀態. 

ref:
https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task?redirectedfrom=MSDN&view=netframework-4.7.

The Task class represents a single operation that does not return a value and that usually executes asynchronously. Task objects are one of the central components of the task-based asynchronous pattern first introduced in the .NET Framework 4. Because the work performed by a Task object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the Status property, as well as the IsCanceled, IsCompleted, and IsFaulted properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. 
For operations that return values, you use the Task<TResult> class. 

----------
Task instantiation

The following example creates and executes four tasks. Three tasks execute an Action<T> delegate named action, which accepts an argument of type Object. A fourth task executes a lambda expression (an Action delegate) that is defined inline in the call to the task creation method. Each task is instantiated and run in a different way: 

•Task t1 is instantiated by calling a Task class constructor, but is started by calling its Start() method only after task t2 has started. 
•Task t2 is instantiated and started in a single method call by calling the TaskFactory.StartNew(Action<Object>, Object) method. 
•Task t3 is instantiated and started in a single method call by calling the Run(Action) method. 
•Task t4 is executed synchronously on the main thread by calling the RunSynchronously() method. 

Because task t4 executes synchronously, it executes on the main application thread. The remaining tasks execute asynchronously typically on one or more thread pool threads. 

以下範例重點:
1. Task 語法需銜接(action delegate) 或 (lambda inline). 
2. Task 可選擇在 (thread pool) 或 (主執行緒) 中執行.
3. 利用 lambda expression inline 可簡化語法.

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

class Example
{
    static void Main()
    {
		// Task 語法需銜接(action delegate) 或 (lambda inline)
		
		// 以 lambda 語法 定義 action delegate 的 inline 程式邏輯.
		// Thread.CurrentThread.ManagedThreadId 可取得目前的 threadid
        Action<object> action = (object obj) =>
                                {
                                   Console.WriteLine("Task={0}, obj={1}, Thread={2}",
                                   Task.CurrentId, obj,
                                   Thread.CurrentThread.ManagedThreadId);
                                };

        // Create a task but do not start it.
		// Task 語法1: 只建立Task, 但是還不啟動執行.
        Task t1 = new Task(action, "alpha");

        // Construct a started task.  
		// Task 語法2: 建立並啟動 Task.
        Task t2 = Task.Factory.StartNew(action, "beta");
		
        // Block the main thread to demonstrate that t2 is executing. 
		// Task 可以等待完成後, 再繼續執行主執行緒.
        t2.Wait();

        // Launch t1 啟動執行已建立的 Task.
        t1.Start();
        Console.WriteLine("t1 has been launched. (Main Thread={0})",
                          Thread.CurrentThread.ManagedThreadId);
        // Wait for the task to finish.
        t1.Wait();

        // Construct a started task using Task.Run. 
		// Task t3 以 lambda 語法建立inline程式邏輯, 可取代麻煩的(定義 action delegate 的 inline 程式邏輯), 並立刻啟動執行.
        String taskData = "delta";
        Task t3 = Task.Run( () => {Console.WriteLine("Task={0}, obj={1}, Thread={2}",
                                                     Task.CurrentId, taskData,
                                                      Thread.CurrentThread.ManagedThreadId);
                                   });
        // Wait for the task to finish.
        t3.Wait();

        // Construct an unstarted task
        Task t4 = new Task(action, "gamma");
        // Run it synchronously 以同步方式執行.
        t4.RunSynchronously();
        // Although the task was run synchronously, it is a good practice
        // to wait for it in the event exceptions were thrown by the task.
		// 即使是同步方式執行, 最好還是等待 Task 發出來的 event exceptions.
        t4.Wait();
    }
}
// The example displays output like the following:
//       Task=1, obj=beta, Thread=3
//       t1 has been launched. (Main Thread=1)
//       Task=2, obj=alpha, Thread=4
//       Task=3, obj=delta, Thread=3
//       Task=4, obj=gamma, Thread=1


----------
Creating and executing a task

Task instances may be created in a variety of ways. The most common approach, which is available starting with the .NET Framework 4.5, is to call the static Run method. The Run method provides a simple way to start a task using default values and without requiring additional parameters. The following example uses the Run(Action) method to start a task that loops and then displays the number of loop iterations: 

執行 Task 有很多種方式. 最常見的方式是呼叫 Task.Run() (.NET Framework 4.5以上才支援).

using System;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      Task t = Task.Run( () => {
                                  // Just loop.
                                  int ctr = 0;
                                  for (ctr = 0; ctr <= 1000000; ctr++)
                                  {}
                                  Console.WriteLine("Finished {0} loop iterations",
                                                    ctr);
                               } );
      t.Wait();
   }
}
// The example displays the following output:
//        Finished 1000001 loop iterations


An alternative, and the most common method to start a task in .NET Framework 4, is the static TaskFactory.StartNew method. The Task.Factory property returns a TaskFactory object. Overloads of the TaskFactory.StartNew method let you specify parameters to pass to the task creation options and a task scheduler. The following example uses the TaskFactory.StartNew method to start a task. It is functionally equivalent to the code in the previous example

執行 Task, 也可以用 Task.Factory.StartNew() (.NET Framework 4.0 以上才支援).
以下範例執行結果與前一個相同, 但是改為 Task.Factory.StartNew() 執行 Task.

using System;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      Task t = Task.Factory.StartNew( () => {
                                  // Just loop.
                                  int ctr = 0;
                                  for (ctr = 0; ctr <= 1000000; ctr++)
                                  {}
                                  Console.WriteLine("Finished {0} loop iterations",
                                                    ctr);
                               } );
      t.Wait();
   }
}
// The example displays the following output:
//        Finished 1000001 loop iterations


----------
Separating task creation and execution

The Task class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the Task.Run or TaskFactory.StartNew method is the preferred mechanism for creating and scheduling computational tasks, but for scenarios where creation and scheduling must be separated, you can use the constructors and then call the Task.Start method to schedule the task for execution at a later time. 

 

Waiting for one or more tasks to complete

Because tasks typically run asynchronously on a thread pool thread, the thread that creates and starts the task continues execution as soon as the task has been instantiated. In some cases, when the calling thread is the main application thread, the app may terminate before any the task actually begins execution. In others, your application's logic may require that the calling thread continue execution only when one or more tasks has completed execution. You can synchronize the execution of the calling thread and the asynchronous tasks it launches by calling a Wait method to wait for one or more tasks to complete. 

To wait for a single task to complete, you can call its Task.Wait method. A call to the Wait method blocks the calling thread until the single class instance has completed execution. 

The following example calls the parameterless Wait() method to wait unconditionally until a task completes. The task simulates work by calling the Thread.Sleep method to sleep for two seconds. 


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

class Program
{
    static Random rand = new Random();

    static void Main()
    {
        // Wait on a single task with no timeout specified.
        Task taskA = Task.Run( () => Thread.Sleep(2000));
        Console.WriteLine("taskA Status: {0}", taskA.Status);
        try {
          taskA.Wait();
          Console.WriteLine("taskA Status: {0}", taskA.Status);
       } 
       catch (AggregateException) {
          Console.WriteLine("Exception in taskA.");
       }   
    }    
}
// The example displays output like the following:
//     taskA Status: WaitingToRun
//     taskA Status: RanToCompletion


You can also conditionally wait for a task to complete. The Wait(Int32) and Wait(TimeSpan) methods block the calling thread until the task finishes or a timeout interval elapses, whichever comes first. Since the following example launches a task that sleeps for two seconds but defines a one-second timeout value, the calling thread blocks until the timeout expires and before the task has completed execution. 

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

public class Example
{
   public static void Main()
   {
      // Wait on a single task with a timeout specified.
      Task taskA = Task.Run( () => Thread.Sleep(2000));
      try {
        taskA.Wait(1000);       // Wait for 1 second.
        bool completed = taskA.IsCompleted;
        Console.WriteLine("Task A completed: {0}, Status: {1}",
                         completed, taskA.Status);
        if (! completed)
           Console.WriteLine("Timed out before task A completed.");                 
       }
       catch (AggregateException) {
          Console.WriteLine("Exception in taskA.");
       }   
   }
}
// The example displays output like the following:
//     Task A completed: False, Status: Running
//     Timed out before task A completed.

You can also supply a cancellation token by calling the Wait(CancellationToken) and Wait(Int32, CancellationToken) methods. If the token's IsCancellationRequested property is true, the wait is cancelled; if it becomes true while the Wait method terminates. 

In some cases, you may want to wait for the first of a series of executing tasks to complete, but don't care which task it is. For this purpose, you can call one of the overloads of the Task.WaitAll method. The following example creates three tasks, each of which sleeps for an interval determine by a random number generator. The WaitAny(Task[]) method waits for the first task to complete. The example then displays information about the status of all three tasks. 

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

public class Example
{
   public static void Main()
   {
      var tasks = new Task[3];
      var rnd = new Random();
      for (int ctr = 0; ctr <= 2; ctr++)
         tasks[ctr] = Task.Run( () => Thread.Sleep(rnd.Next(500, 3000)));

      try {
         int index = Task.WaitAny(tasks);
         Console.WriteLine("Task #{0} completed first.\n", tasks[index].Id);
         Console.WriteLine("Status of all tasks:");
         foreach (var t in tasks)
            Console.WriteLine("   Task #{0}: {1}", t.Id, t.Status);
      }
      catch (AggregateException) {
         Console.WriteLine("An exception occurred.");
      }
   }
}
// The example displays output like the following:
//     Task #1 completed first.
//     
//     Status of all tasks:
//        Task #3: Running
//        Task #1: RanToCompletion
//        Task #4: Running

You can also wait for all of a series of tasks to complete by calling the WaitAll method. The following example creates ten tasks, waits for all ten to complete, and then displays their status. 

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

public class Example
{
   public static void Main()
   {
      // Wait for all tasks to complete.
      Task[] tasks = new Task[10];
      for (int i = 0; i < 10; i++)
      {
          tasks[i] = Task.Run(() => Thread.Sleep(2000));
      }
      try {
         Task.WaitAll(tasks);
      }
      catch (AggregateException ae) {
         Console.WriteLine("One or more exceptions occurred: ");
         foreach (var ex in ae.Flatten().InnerExceptions)
            Console.WriteLine("   {0}", ex.Message);
      }   

      Console.WriteLine("Status of completed tasks:");
      foreach (var t in tasks)
         Console.WriteLine("   Task #{0}: {1}", t.Id, t.Status);
   }
}
// The example displays the following output:
//     Status of completed tasks:
//        Task #2: RanToCompletion
//        Task #1: RanToCompletion
//        Task #3: RanToCompletion
//        Task #4: RanToCompletion
//        Task #6: RanToCompletion
//        Task #5: RanToCompletion
//        Task #7: RanToCompletion
//        Task #8: RanToCompletion
//        Task #9: RanToCompletion
//        Task #10: RanToCompletion


Note that when you wait for one or more tasks to complete, any exceptions thrown in the running tasks are propagated on the thread that calls the Wait method, as the following example shows. It launches 12 tasks, three of which complete normally and three of which throw an exception. Of the remaining six tasks, three are cancelled before the start, and three are cancelled while they executing. Exceptions are thrown in the WaitAll method call and are handled by a try/catch block. 

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

public class Example
{
   public static void Main()
   {
      // Create a cancellation token and cancel it.
      var source1 = new CancellationTokenSource();
      var token1 = source1.Token;
      source1.Cancel();
      // Create a cancellation token for later cancellation.
      var source2 = new CancellationTokenSource();
      var token2 = source2.Token;
       
      // Create a series of tasks that will complete, be cancelled, 
      // timeout, or throw an exception.
      Task[] tasks = new Task[12];
      for (int i = 0; i < 12; i++)
      {
          switch (i % 4) 
          {
             // Task should run to completion.
             case 0:
                tasks[i] = Task.Run(() => Thread.Sleep(2000));
                break;
             // Task should be set to canceled state.
             case 1:   
                tasks[i] = Task.Run( () => Thread.Sleep(2000),
                         token1);
                break;         
             case 2:
                // Task should throw an exception.
                tasks[i] = Task.Run( () => { throw new NotSupportedException(); } );
                break;
             case 3:
                // Task should examine cancellation token.
                tasks[i] = Task.Run( () => { Thread.Sleep(2000); 
                                             if (token2.IsCancellationRequested)
                                                token2.ThrowIfCancellationRequested();
                                             Thread.Sleep(500); }, token2);   
                break;
          }
      }
      Thread.Sleep(250);
      source2.Cancel();
       
      try {
         Task.WaitAll(tasks);
      }
      catch (AggregateException ae) {
          Console.WriteLine("One or more exceptions occurred:");
          foreach (var ex in ae.InnerExceptions)
             Console.WriteLine("   {0}: {1}", ex.GetType().Name, ex.Message);
       }   

      Console.WriteLine("\nStatus of tasks:");
      foreach (var t in tasks) {
         Console.WriteLine("   Task #{0}: {1}", t.Id, t.Status);
         if (t.Exception != null) {
            foreach (var ex in t.Exception.InnerExceptions)
               Console.WriteLine("      {0}: {1}", ex.GetType().Name,
                                 ex.Message);
         }
      }
   }
}
// The example displays output like the following:
//   One or more exceptions occurred:
//      TaskCanceledException: A task was canceled.
//      NotSupportedException: Specified method is not supported.
//      TaskCanceledException: A task was canceled.
//      TaskCanceledException: A task was canceled.
//      NotSupportedException: Specified method is not supported.
//      TaskCanceledException: A task was canceled.
//      TaskCanceledException: A task was canceled.
//      NotSupportedException: Specified method is not supported.
//      TaskCanceledException: A task was canceled.
//   
//   Status of tasks:
//      Task #13: RanToCompletion
//      Task #1: Canceled
//      Task #3: Faulted
//         NotSupportedException: Specified method is not supported.
//      Task #8: Canceled
//      Task #14: RanToCompletion
//      Task #4: Canceled
//      Task #6: Faulted
//         NotSupportedException: Specified method is not supported.
//      Task #7: Canceled
//      Task #15: RanToCompletion
//      Task #9: Canceled
//      Task #11: Faulted
//         NotSupportedException: Specified method is not supported.
//      Task #12: Canceled


Tasks and culture

Starting with desktop apps that target the .NET Framework 4.6, the culture of the thread that creates and invokes a task becomes part of the thread's context. That is, regardless of the current culture of the thread on which the task executes, the current culture of the task is the culture of the calling thread. For apps that target versions of the .NET Framework prior to the .NET Framework 4.6, the culture of the task is the culture of the thread on which the task executes. For more information, see the "Culture and task-based asynchronous operations" section in the CultureInfo topic. 

For debugger developers

For developers implementing custom debuggers, several internal and private members of task may be useful (these may change from release to release). The m_taskId field serves as the backing store for the Id property, however accessing this field directly from a debugger may be more efficient than accessing the same value through the property's getter method (the s_taskIdCounter counter is used to retrieve the next available ID for a task). Similarly, the m_stateFlags field stores information about the current lifecycle stage of the task, information also accessible through the Status property. The m_action field stores a reference to the task's delegate, and the m_stateObject field stores the async state passed to the task by the developer. Finally, for debuggers that parse stack frames, the InternalWait method serves a potential marker for when a task is entering a wait operation.