CancellationTokenSource 類別
定義
重要
部分資訊涉及發行前產品,在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。
向 CancellationToken 發出訊號,表示應該將它取消。
public ref class CancellationTokenSource : IDisposable
public ref class CancellationTokenSource sealed : IDisposable
public class CancellationTokenSource : IDisposable
[System.Runtime.InteropServices.ComVisible(false)]
public sealed class CancellationTokenSource : IDisposable
[System.Runtime.InteropServices.ComVisible(false)]
public class CancellationTokenSource : IDisposable
type CancellationTokenSource = class
interface IDisposable
[<System.Runtime.InteropServices.ComVisible(false)>]
type CancellationTokenSource = class
interface IDisposable
Public Class CancellationTokenSource
Implements IDisposable
Public NotInheritable Class CancellationTokenSource
Implements IDisposable
- 繼承
-
CancellationTokenSource
- 屬性
- 實作
範例
下列範例會使用亂數產生器來模擬從十一個不同檢測讀取 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.
備註
從 .NET Framework 4 開始,.NET Framework會使用統一模型來合作取消涉及兩個物件的非同步或長時間執行的同步作業:
CancellationTokenSource物件,它會透過其 Token 屬性提供解除標記,並藉由呼叫 或 CancelCancelAfter 方法來傳送取消訊息。
CancellationToken物件,指出是否要求取消。
合作式取消模型的一般實作模式是:
具現化 CancellationTokenSource 物件,該物件會管理並傳送取消通知給個別的取消權杖。
傳遞由 CancellationTokenSource.Token 屬性傳回的權杖給每個接聽取消的工作或執行緒。
CancellationToken.IsCancellationRequested從接收取消權杖的作業呼叫 方法。 提供每個工作或執行緒回應取消要求的機制。 不論您選擇取消作業,以及執行作業的方式,都取決於您的應用程式邏輯。
呼叫 CancellationTokenSource.Cancel 方法以提供取消的通知。 這會將 CancellationToken.IsCancellationRequested 解除標記的每個複本上的 屬性設定為
true
。當您使用 CancellationTokenSource 完成後,請呼叫 Dispose 方法。
如需詳細資訊,請參閱受控執行緒中的取消作業。
重要
此型別代表 IDisposable 介面。 當您完成使用 類型的實例時,應該直接或間接處置它。 若要直接處置型別,請呼叫其 try
/finally
區塊中的 Dispose 方法。 若要間接處置它,請使用語言建構函式,例如 using
(在 C# 中) 或 Using
(在 Visual Basic 中)。 如需詳細資訊,請參閱 IDisposable 介面文章中的<使用實作 IDisposable 的物件>一節。
建構函式
CancellationTokenSource() |
初始化 CancellationTokenSource 類別的新執行個體。 |
CancellationTokenSource(Int32) |
初始化 CancellationTokenSource 類別的新執行個體,過了指定的延遲時間 (以毫秒為單位) 之後,將會取消這個執行個體。 |
CancellationTokenSource(TimeSpan) |
初始化 CancellationTokenSource 類別的新執行個體,在指定的時間範圍之後,將會取消這個執行個體。 |
CancellationTokenSource(TimeSpan, TimeProvider) |
初始化 類別的新實例,這個實例 CancellationTokenSource 將在指定的 TimeSpan 之後取消。 |
屬性
IsCancellationRequested |
取得是否已為這個 CancellationTokenSource 要求取消。 |
Token |
取得與這個 CancellationToken 關聯的 CancellationTokenSource。 |
方法
適用於
執行緒安全性
的所有公用和受保護成員 CancellationTokenSource 都是安全線程,而且可以從多個執行緒同時使用,但 除外 Dispose() ,只有在 物件上 CancellationTokenSource 所有其他作業都已完成時,才必須使用。
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應