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個不同的儀器讀取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.

備註

CancellationToken啟用執行緒、執行緒集區工作專案或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.

如需詳細資訊和程式碼範例, 請參閱Managed 執行緒中的取消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)

註冊取消此 CancellationToken 時要呼叫的委派。Registers a delegate that is called when this CancellationToken is canceled.

運算子

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.

適用於

執行緒安全性

所有的CancellationToken公用和受保護成員都是安全線程, 而且可以從多個執行緒同時使用。All public and protected members of CancellationToken are thread-safe and may be used concurrently from multiple threads.

另請參閱