CancellationTokenSource 類別

定義

CancellationToken 發出訊號,表示應該將它取消。Signals to a CancellationToken that it should be canceled.

public ref class CancellationTokenSource : IDisposable
[System.Runtime.InteropServices.ComVisible(false)]
public class CancellationTokenSource : IDisposable
type CancellationTokenSource = class
    interface IDisposable
Public Class CancellationTokenSource
Implements IDisposable
繼承
CancellationTokenSource
屬性
實作

範例

下列範例會使用亂數產生器來模擬資料收集應用程式, 以從11個不同的儀器讀取10個整數值。The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. 值為零表示某個檢測的度量失敗, 在此情況下, 應該取消作業, 而且不會計算整體平均值。A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed.

為了處理作業的可能取消作業, 此範例會具現CancellationTokenSource化一個物件, 該物件會產生傳遞TaskFactory給物件的解除標記。To handle the possible cancellation of the operation, the example instantiates a CancellationTokenSource object that generates a cancellation token which is passed to a TaskFactory object. TaskFactory物件接著會將解除標記傳遞給負責收集特定檢測之讀取的每個工作。The TaskFactory object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. 呼叫TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken)方法, 以確保只有在成功收集所有讀數之後, 才會計算平均值。The TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) method is called to ensure that the mean is computed only after all readings have been gathered successfully. 如果工作尚未被取消, 則呼叫TaskFactory.ContinueWhenAll方法會擲回例外狀況。If a task has not because it has been cancelled, the call to the TaskFactory.ContinueWhenAll method throws an exception.

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      // Define the cancellation token.
      CancellationTokenSource source = new CancellationTokenSource();
      CancellationToken token = source.Token;

      Random rnd = new Random();
      Object lockObj = new Object();
      
      List<Task<int[]>> tasks = new List<Task<int[]>>();
      TaskFactory factory = new TaskFactory(token);
      for (int taskCtr = 0; taskCtr <= 10; taskCtr++) {
         int iteration = taskCtr + 1;
         tasks.Add(factory.StartNew( () => {
                                       int value;
                                       int[] values = new int[10];
                                       for (int ctr = 1; ctr <= 10; ctr++) {
                                          lock (lockObj) {
                                             value = rnd.Next(0,101);
                                          }
                                          if (value == 0) { 
                                             source.Cancel();
                                             Console.WriteLine("Cancelling at task {0}", iteration);
                                             break;
                                          }   
                                          values[ctr-1] = value; 
                                       }
                                       return values;
                                    }, token));   
         
      }
      try {
         Task<double> fTask = factory.ContinueWhenAll(tasks.ToArray(), 
                                                      (results) => {
                                                         Console.WriteLine("Calculating overall mean...");
                                                         long sum = 0;
                                                         int n = 0; 
                                                         foreach (var t in results) {
                                                            foreach (var r in t.Result) {
                                                                  sum += r;
                                                                  n++;
                                                               }
                                                         }
                                                         return sum/(double) n;
                                                      } , token);
         Console.WriteLine("The mean is {0}.", fTask.Result);
      }   
      catch (AggregateException ae) {
         foreach (Exception e in ae.InnerExceptions) {
            if (e is TaskCanceledException)
               Console.WriteLine("Unable to compute mean: {0}", 
                                 ((TaskCanceledException) e).Message);
            else
               Console.WriteLine("Exception: " + e.GetType().Name);
         }
      }
      finally {
         source.Dispose();
      }
   }
}
// Repeated execution of the example produces output like the following:
//       Cancelling at task 5
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 10
//       Unable to compute mean: A task was canceled.
//       
//       Calculating overall mean...
//       The mean is 5.29545454545455.
//       
//       Cancelling at task 4
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 5
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 6
//       Unable to compute mean: A task was canceled.
//       
//       Calculating overall mean...
//       The mean is 4.97363636363636.
//       
//       Cancelling at task 4
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 5
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 4
//       Unable to compute mean: A task was canceled.
//       
//       Calculating overall mean...
//       The mean is 4.86545454545455.
Imports System.Collections.Generic
Imports System.Threading
Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      ' Define the cancellation token.
      Dim source As New CancellationTokenSource()
      Dim token As CancellationToken = source.Token

      Dim lockObj As New Object()
      Dim rnd As New Random

      Dim tasks As New List(Of Task(Of Integer()))
      Dim factory As New TaskFactory(token)
      For taskCtr As Integer = 0 To 10
         Dim iteration As Integer = taskCtr + 1
         tasks.Add(factory.StartNew(Function()
                                       Dim value, values(9) As Integer
                                       For ctr As Integer = 1 To 10
                                          SyncLock lockObj
                                             value = rnd.Next(0,101)
                                          End SyncLock
                                          If value = 0 Then 
                                             source.Cancel
                                             Console.WriteLine("Cancelling at task {0}", iteration)
                                             Exit For
                                          End If   
                                          values(ctr-1) = value 
                                       Next
                                       Return values
                                    End Function, token))   
         
      Next
      Try
         Dim fTask As Task(Of Double) = factory.ContinueWhenAll(tasks.ToArray(), 
                                                         Function(results)
                                                            Console.WriteLine("Calculating overall mean...")
                                                            Dim sum As Long
                                                            Dim n As Integer 
                                                            For Each t In results
                                                               For Each r In t.Result
                                                                  sum += r
                                                                  n+= 1
                                                               Next
                                                            Next
                                                            Return sum/n
                                                         End Function, token)
         Console.WriteLine("The mean is {0}.", fTask.Result)
      Catch ae As AggregateException
         For Each e In ae.InnerExceptions
            If TypeOf e Is TaskCanceledException
               Console.WriteLine("Unable to compute mean: {0}", 
                                 CType(e, TaskCanceledException).Message)
            Else
               Console.WriteLine("Exception: " + e.GetType().Name)
            End If   
         Next
      Finally
         source.Dispose()
      End Try                                                          
   End Sub
End Module
' Repeated execution of the example produces output like the following:
'       Cancelling at task 5
'       Unable to compute mean: A task was canceled.
'       
'       Cancelling at task 10
'       Unable to compute mean: A task was canceled.
'       
'       Calculating overall mean...
'       The mean is 5.29545454545455.
'       
'       Cancelling at task 4
'       Unable to compute mean: A task was canceled.
'       
'       Cancelling at task 5
'       Unable to compute mean: A task was canceled.
'       
'       Cancelling at task 6
'       Unable to compute mean: A task was canceled.
'       
'       Calculating overall mean...
'       The mean is 4.97363636363636.
'       
'       Cancelling at task 4
'       Unable to compute mean: A task was canceled.
'       
'       Cancelling at task 5
'       Unable to compute mean: A task was canceled.
'       
'       Cancelling at task 4
'       Unable to compute mean: A task was canceled.
'       
'       Calculating overall mean...
'       The mean is 4.86545454545455.

備註

從開始, .NET Framework 會針對非同步或長時間執行且涉及兩個物件的同步作業, 使用統一的模型來進行合作式取消: .NET Framework 4.NET Framework 4Starting with the .NET Framework 4.NET Framework 4, the .NET Framework uses a unified model for cooperative cancellation of asynchronous or long-running synchronous operations that involves two objects:

合作式取消模型的一般實作模式是:The general pattern for implementing the cooperative cancellation model is:

如需詳細資訊,請參閱受控執行緒中的取消作業For more information, see Cancellation in Managed Threads.

重要

這個型IDisposable別會執行介面。This type implements the IDisposable interface. 當您完成使用類型的實例時, 您應該直接或間接處置它。When you have finished using an instance of the type, you should dispose of it either directly or indirectly. 若要直接Dispose處置類型, 請try / catch在區塊中呼叫其方法。To dispose of the type directly, call its Dispose method in a try/catch block. 若要間接處置它, 請使用語言結構, 例如using (在C#中) Using或 (在 Visual Basic 中)。To dispose of it indirectly, use a language construct such as using (in C#) or Using (in Visual Basic). 如需詳細資訊, 請參閱IDisposable介面主題中的「使用可執行 IDisposable 的物件」一節。For more information, see the "Using an Object that Implements IDisposable" section in the IDisposable interface topic.

建構函式

CancellationTokenSource()

初始化 CancellationTokenSource 類別的新執行個體。Initializes a new instance of the CancellationTokenSource class.

CancellationTokenSource(Int32)

初始化 CancellationTokenSource 類別的新執行個體,這個執行個體將會在指定的延遲 (以毫秒為單位) 之後被取消。Initializes a new instance of the CancellationTokenSource class that will be canceled after the specified delay in milliseconds.

CancellationTokenSource(TimeSpan)

初始化 CancellationTokenSource 類別的新執行個體,這個執行個體將會在指定的時間範圍之後被取消。Initializes a new instance of the CancellationTokenSource class that will be canceled after the specified time span.

屬性

IsCancellationRequested

取得是否已要求取消這個 CancellationTokenSourceGets whether cancellation has been requested for this CancellationTokenSource.

Token

取得與這個 CancellationToken 關聯的 CancellationTokenSourceGets the CancellationToken associated with this CancellationTokenSource.

方法

Cancel()

傳遞取消要求。Communicates a request for cancellation.

Cancel(Boolean)

傳遞取消要求,並指定如果發生例外狀況時,是否應處理其餘回呼和可取消的作業。Communicates a request for cancellation, and specifies whether remaining callbacks and cancelable operations should be processed if an exception occurs.

CancelAfter(Int32)

在這個 CancellationTokenSource 上,將取消作業排程於指定的毫秒數後。Schedules a cancel operation on this CancellationTokenSource after the specified number of milliseconds.

CancelAfter(TimeSpan)

在這個 CancellationTokenSource 上,將取消作業排程於指定的時間範圍後。Schedules a cancel operation on this CancellationTokenSource after the specified time span.

CreateLinkedTokenSource(CancellationToken, CancellationToken)

建立 CancellationTokenSource,且設定只要有任何來源語彙基元處於已取消狀態,它就會處於已取消狀態。Creates a CancellationTokenSource that will be in the canceled state when any of the source tokens are in the canceled state.

CreateLinkedTokenSource(CancellationToken[])

建立 CancellationTokenSource,且設定只要指定的陣列中有任何來源語彙基元處於已取消狀態,它就會處於已取消狀態。Creates a CancellationTokenSource that will be in the canceled state when any of the source tokens in the specified array are in the canceled state.

Dispose()

釋放 CancellationTokenSource 類別目前的執行個體所使用的全部資源。Releases all resources used by the current instance of the CancellationTokenSource class.

Dispose(Boolean)

釋放 CancellationTokenSource 類別所使用的 Unmanaged 資源,並選擇性地釋放 Managed 資源。Releases the unmanaged resources used by the CancellationTokenSource class and optionally releases the managed resources.

Equals(Object)

判斷指定的物件是否等於目前的物件。Determines whether the specified object is equal to the current object.

(繼承來源 Object)
GetHashCode()

做為預設雜湊函式。Serves as the default hash function.

(繼承來源 Object)
GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(繼承來源 Object)
MemberwiseClone()

建立目前 Object 的淺層複本 (Shallow Copy)。Creates a shallow copy of the current Object.

(繼承來源 Object)
ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(繼承來源 Object)

適用於

執行緒安全性

所有的CancellationTokenSource公用和受保護成員都是安全線程, 而且可以從多個執行緒同時使用, 但Dispose()除外, 只有在CancellationTokenSource物件上的所有其他作業都已完成時, 才必須使用。All public and protected members of CancellationTokenSource are thread-safe and may be used concurrently from multiple threads, with the exception of Dispose(), which must only be used when all other operations on the CancellationTokenSource object have completed.

另請參閱