CancellationToken CancellationToken CancellationToken CancellationToken Struct

定義

傳播通知,表示應該取消作業。Propagates notification that operations should be canceled.

public value class CancellationToken
[System.Runtime.InteropServices.ComVisible(false)]
public struct CancellationToken
type CancellationToken = struct
Public Structure CancellationToken
繼承
CancellationTokenCancellationTokenCancellationTokenCancellationToken
屬性

範例

下列範例會使用亂數產生器,來模擬從 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.

備註

ACancellationToken可讓執行緒,執行緒集區工作項目之間的合作式取消或Task物件。A CancellationToken enables cooperative cancellation between threads, thread pool work items, or Task objects. 您建立以具現化的取消語彙基元CancellationTokenSource物件,用來管理取消語彙基元擷取自其CancellationTokenSource.Token屬性。You create a cancellation token by instantiating a CancellationTokenSource object, which manages cancellation tokens retrieved from its CancellationTokenSource.Token property. 然後,將取消語彙基元傳遞至任意數目的執行緒、 工作或作業來接收取消通知。You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. 語彙基元無法用以起始取消。The token cannot be used to initiate cancellation. 當主控的物件呼叫CancellationTokenSource.Cancel,則IsCancellationRequested的取消語彙基元的每個複本上的屬性設定為trueWhen the owning object calls CancellationTokenSource.Cancel, the IsCancellationRequested property on every copy of the cancellation token is set to true. 接收通知的物件可以回應適合的方式。The objects that receive the notification can respond in whatever manner is appropriate.

如需詳細資訊和程式碼範例,請參閱受控執行緒中的取消For more information and code examples see Cancellation in Managed Threads.

建構函式

CancellationToken(Boolean) CancellationToken(Boolean) CancellationToken(Boolean) CancellationToken(Boolean)

初始化 CancellationTokenInitializes the CancellationToken.

屬性

CanBeCanceled CanBeCanceled CanBeCanceled CanBeCanceled

取得這個語彙基元是否能夠處於已取消狀態。Gets whether this token is capable of being in the canceled state.

IsCancellationRequested IsCancellationRequested IsCancellationRequested IsCancellationRequested

取得是否已要求取消這個語彙基元。Gets whether cancellation has been requested for this token.

None None None None

傳回空的 CancellationToken 值。Returns an empty CancellationToken value.

WaitHandle WaitHandle WaitHandle WaitHandle

取得取消語彙基元時所發出的 WaitHandle 信號。Gets a WaitHandle that is signaled when the token is canceled.

方法

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

判斷目前的 CancellationToken 執行個體與指定的 Object 是否相等。Determines whether the current CancellationToken instance is equal to the specified Object.

Equals(CancellationToken) Equals(CancellationToken) Equals(CancellationToken) Equals(CancellationToken)

判斷目前的 CancellationToken 執行個體與指定的語彙基元是否相等。Determines whether the current CancellationToken instance is equal to the specified token.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

做為 CancellationToken 的雜湊函式。Serves as a hash function for a CancellationToken.

Register(Action) Register(Action) Register(Action) Register(Action)

註冊委派,當取消這個 CancellationToken 時將會呼叫該委派。Registers a delegate that will be called when this CancellationToken is canceled.

Register(Action, Boolean) Register(Action, Boolean) Register(Action, Boolean) Register(Action, Boolean)

註冊委派,當取消這個 CancellationToken 時將會呼叫該委派。Registers a delegate that will be called when this CancellationToken is canceled.

Register(Action<Object>, Object) Register(Action<Object>, Object) Register(Action<Object>, Object) Register(Action<Object>, Object)

註冊委派,當取消這個 CancellationToken 時將會呼叫該委派。Registers a delegate that will be called when this CancellationToken is canceled.

Register(Action<Object>, Object, Boolean) Register(Action<Object>, Object, Boolean) Register(Action<Object>, Object, Boolean) Register(Action<Object>, Object, Boolean)

註冊委派,當取消這個 CancellationToken 時將會呼叫該委派。Registers a delegate that will be called when this CancellationToken is canceled.

ThrowIfCancellationRequested() ThrowIfCancellationRequested() ThrowIfCancellationRequested() ThrowIfCancellationRequested()

如果已要求取消這個語彙基元,則擲回 OperationCanceledExceptionThrows a OperationCanceledException if this token has had cancellation requested.

UnsafeRegister(Action<Object>, Object) UnsafeRegister(Action<Object>, Object) UnsafeRegister(Action<Object>, Object) UnsafeRegister(Action<Object>, Object)

運算子

Equality(CancellationToken, CancellationToken) Equality(CancellationToken, CancellationToken) Equality(CancellationToken, CancellationToken) Equality(CancellationToken, CancellationToken)

判斷兩個 CancellationToken 執行個體是否相等。Determines whether two CancellationToken instances are equal.

Inequality(CancellationToken, CancellationToken) Inequality(CancellationToken, CancellationToken) Inequality(CancellationToken, CancellationToken) Inequality(CancellationToken, CancellationToken)

判斷兩個 CancellationToken 執行個體是否不相等。Determines whether two CancellationToken instances are not equal.

適用於

執行緒安全性

所有 public 和 protected 成員CancellationToken是安全執行緒,且可能會從多個執行緒同時使用。All public and protected members of CancellationToken are thread-safe and may be used concurrently from multiple threads.

另請參閱