CancellationTokenSource CancellationTokenSource CancellationTokenSource CancellationTokenSource Class

定義

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
繼承
CancellationTokenSourceCancellationTokenSourceCancellationTokenSourceCancellationTokenSource
屬性
實作

範例

下列範例會使用亂數產生器,來模擬從 11 個不同的 instruments 讀取 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 4.NET Framework 4,.NET Framework 使用統一的模型牽涉到兩個物件的非同步或長時間執行的同步作業的合作式取消作業:Starting 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() CancellationTokenSource() CancellationTokenSource()

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

CancellationTokenSource(Int32) CancellationTokenSource(Int32) CancellationTokenSource(Int32) CancellationTokenSource(Int32)

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

CancellationTokenSource(TimeSpan) CancellationTokenSource(TimeSpan) CancellationTokenSource(TimeSpan) CancellationTokenSource(TimeSpan)

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

屬性

IsCancellationRequested IsCancellationRequested IsCancellationRequested IsCancellationRequested

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

Token Token Token Token

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

方法

Cancel() Cancel() Cancel() Cancel()

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

Cancel(Boolean) Cancel(Boolean) Cancel(Boolean) Cancel(Boolean)

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

CancelAfter(Int32) CancelAfter(Int32) CancelAfter(Int32) CancelAfter(Int32)

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

CancelAfter(TimeSpan) CancelAfter(TimeSpan) CancelAfter(TimeSpan) CancelAfter(TimeSpan)

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

CreateLinkedTokenSource(CancellationToken, CancellationToken) CreateLinkedTokenSource(CancellationToken, CancellationToken) CreateLinkedTokenSource(CancellationToken, CancellationToken) 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[]) CreateLinkedTokenSource(CancellationToken[]) CreateLinkedTokenSource(CancellationToken[]) 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() Dispose() Dispose() Dispose()

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

Dispose(Boolean) Dispose(Boolean) Dispose(Boolean) Dispose(Boolean)

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

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

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

(Inherited from Object)
GetHashCode() GetHashCode() GetHashCode() GetHashCode()

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

(Inherited from Object)
GetType() GetType() GetType() GetType()

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

(Inherited from Object)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

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

(Inherited from Object)
ToString() ToString() ToString() ToString()

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

(Inherited from Object)

適用於

執行緒安全性

所有 public 和 protected 成員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.

另請參閱