CancellationTokenSource Класс
Определение
Важно!
Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
Отправляет токену 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 свойство и отправляет сообщение об отмене путем вызова метода Cancel или CancelAfter .
Объект CancellationToken , указывающий, запрашивается ли отмена.
Общая схема реализации модели совместной отмены выглядит следующим образом:
Создается экземпляр объекта CancellationTokenSource, который управляет уведомлениями об отмене и передает их отдельным токенам отмены.
В каждую задачу или поток, ожидающий отмены, передается токен, возвращенный свойством CancellationTokenSource.Token.
CancellationToken.IsCancellationRequested Вызовите метод из операций, получающих маркер отмены. Предоставьте механизм для каждой задачи или потока, который будет отвечать на запрос отмены. Выбор отмены операции и способ ее выполнения зависит от логики приложения.
Вызывается метод CancellationTokenSource.Cancel для предоставления уведомления об отмене. При этом свойству CancellationToken.IsCancellationRequested каждой копии маркера отмены присваивается значение
true
.Вызовите метод по Dispose завершении работы с CancellationTokenSource объектом .
См. дополнительные сведения об отмене в управляемых потоках.
Важно!
Этот тип реализует интерфейс IDisposable. Завершив использование экземпляра типа , его следует удалить прямо или косвенно. Чтобы сделать это прямо, вызовите его метод Dispose в блоке try
/finally
. Чтобы сделать это косвенно, используйте языковые конструкции, такие как 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. |
Методы
Cancel() |
Передает запрос на отмену. |
Cancel(Boolean) |
Передает запрос отмены и определяет, будут ли последующие обратные вызовы и отменяемые операции обрабатываться при возникновении исключения. |
CancelAfter(Int32) |
Планирует операцию отмены для данного объекта CancellationTokenSource после указанного числа миллисекунд. |
CancelAfter(TimeSpan) |
Планирует операции отмены для данного объекта CancellationTokenSource после указанного промежутка времени. |
CancelAsync() |
Асинхронно передает запрос на отмену. |
CreateLinkedTokenSource(CancellationToken) |
Создает CancellationTokenSource, который будет находиться в состоянии отмены, когда указанный токен находится в состоянии отмены. |
CreateLinkedTokenSource(CancellationToken, CancellationToken) |
Создает объект CancellationTokenSource, который будет иметь отмененное состояние, если какой-либо из исходных токенов находится в отмененном состоянии. |
CreateLinkedTokenSource(CancellationToken[]) |
Создает объект CancellationTokenSource, который будет иметь отмененное состояние, если любой из исходных токенов в заданном массиве находится в отмененном состоянии. |
CreateLinkedTokenSource(ReadOnlySpan<CancellationToken>) |
Отправляет токену CancellationToken сигнал отмены. |
Dispose() |
Освобождает все ресурсы, используемые текущим экземпляром класса CancellationTokenSource. |
Dispose(Boolean) |
Освобождает неуправляемые ресурсы, используемые классом CancellationTokenSource (при необходимости освобождает и управляемые ресурсы). |
Equals(Object) |
Определяет, равен ли указанный объект текущему объекту. (Унаследовано от Object) |
GetHashCode() |
Служит хэш-функцией по умолчанию. (Унаследовано от Object) |
GetType() |
Возвращает объект Type для текущего экземпляра. (Унаследовано от Object) |
MemberwiseClone() |
Создает неполную копию текущего объекта Object. (Унаследовано от Object) |
ToString() |
Возвращает строку, представляющую текущий объект. (Унаследовано от Object) |
TryReset() |
Пытается сбросить CancellationTokenSource для использования для несвязанной операции. |
Применяется к
Потокобезопасность
Все открытые и защищенные члены CancellationTokenSource являются потокобезопасными и могут использоваться одновременно из нескольких потоков, за исключением Dispose(), которые необходимо использовать только после завершения всех остальных операций CancellationTokenSource с объектом.
См. также раздел
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по