CancellationToken 結構

定義

命名空間:: System.Threading

組件:: mscorlib.dll, System.Threading.Tasks.dll

組件:: netstandard.dll, System.Runtime.dll

組件:: System.Threading.Tasks.dll

組件:: System.Runtime.dll

組件:: mscorlib.dll

組件:: netstandard.dll

來源:: CancellationToken.cs

來源:: CancellationToken.cs

來源:: CancellationToken.cs

來源:: CancellationToken.cs

來源:: CancellationToken.cs

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

傳播應該取消作業的通知。

public value class CancellationToken

public value class CancellationToken : IEquatable<System::Threading::CancellationToken>

public struct CancellationToken

public readonly struct CancellationToken : IEquatable<System.Threading.CancellationToken>

public readonly struct CancellationToken

[System.Runtime.InteropServices.ComVisible(false)]
public struct CancellationToken

type CancellationToken = struct

[<System.Runtime.InteropServices.ComVisible(false)>]
type CancellationToken = struct

Public Structure CancellationToken

Public Structure CancellationToken
Implements IEquatable(Of CancellationToken)

繼承: Object

ValueType
CancellationToken

屬性: ComVisibleAttribute

實作: IEquatable<CancellationToken>

範例

以下範例使用隨機數產生器模擬資料收集應用程式，該應用程式從十一種不同儀器讀取 10 個整數值。值為零表示某儀器的測量失敗，此時應取消操作，且不計算整體平均值。

為了處理可能的消去，範例中實例化一個 CancellationTokenSource 物件，產生一個消去標記，並傳遞給物件 TaskFactory 。接著， TaskFactory 物件將消除標記傳遞給負責收集特定儀器讀數的任務。 TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken)此方法的使用是為了確保平均值僅在所有讀數成功收集後才計算。如果任務因被取消而未完成， TaskFactory.ContinueWhenAll 該方法會拋出例外。

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.

備註

A CancellationToken 允許執行緒、執行緒池工作項目或 Task 物件間的合作取消。你透過實例化一個 CancellationTokenSource 物件來建立消去標記，該物件會管理從其 CancellationTokenSource.Token 屬性中取得的消去標記。接著你將取消標記傳給任何數量的執行緒、任務或操作，這些執行緒或操作應該會收到取消通知。該令牌無法用來啟動取消。當擁有物件呼叫 CancellationTokenSource.Cancel時， IsCancellationRequested 每個消去標記的副本上的屬性都設為 true。接收通知的物件可以以任何適當的方式回應。

欲了解更多資訊與程式碼範例，請參閱「管理執行緒中的取消」。

建構函式

名稱	Description
CancellationToken(Boolean)	初始化 CancellationToken。

屬性

名稱	Description
CanBeCanceled	判斷該代幣是否能處於取消狀態。
IsCancellationRequested	會查詢是否已經申請取消這個代幣。
None	回傳一個空 CancellationToken 值。
WaitHandle	當代幣被取消時，會收到 WaitHandle 一個信號。

方法

名稱	Description
Equals(CancellationToken)	判斷目前 CancellationToken 實例是否等於指定的標記。
Equals(Object)	判斷當前 CancellationToken 實例是否等於指定的 Object。
GetHashCode()	作為的 CancellationToken雜湊函數。
Register(Action, Boolean)	登記一位代表，當取消時 CancellationToken 會被召喚。
Register(Action)	登記一位代表，當取消時 CancellationToken 會被召喚。
Register(Action<Object,CancellationToken>, Object)	註冊一個代表，當取消令牌被取消時會被呼叫。
Register(Action<Object>, Object, Boolean)	登記一位代表，當取消時 CancellationToken 會被召喚。
Register(Action<Object>, Object)	登記一位代表，當取消時 CancellationToken 會被召喚。
ThrowIfCancellationRequested()	如果這個代幣已經被要求取消，就會拋出 a OperationCanceledException 。
UnsafeRegister(Action<Object,CancellationToken>, Object)	註冊一個代表，當取消令牌被取消時會被呼叫。
UnsafeRegister(Action<Object>, Object)	註冊一個代表，當此任務 CancellationToken 被取消時會被呼叫。

操作員

名稱	Description
Equality(CancellationToken, CancellationToken)	判斷兩個 CancellationToken 實例是否相等。
Inequality(CancellationToken, CancellationToken)	判斷兩個 CancellationToken 實例是否不相等。

適用於

執行緒安全性

所有公開且受保護的成員 CancellationToken 皆為執行緒安全，且可同時從多個執行緒使用。

另請參閱

意見反應

此頁面對您有幫助嗎？