CancellationTokenSource Класс

  • Ссылка

Определение

Пространство имен:
System.Threading
Сборка:
System.Threading.Tasks.dll
Сборка:
System.Runtime.dll
Сборка:
mscorlib.dll
Сборка:
netstandard.dll
Source:
CancellationTokenSource.cs
Source:
CancellationTokenSource.cs
Source:
CancellationTokenSource.cs

Отправляет токену 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
Наследование
Object
CancellationTokenSource
Атрибуты
ComVisibleAttribute
Реализации
IDisposable

Примеры

В следующем примере используется генератор случайных чисел для эмуляции приложения для сбора данных, которое считывает 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, который будет иметь отмененное состояние, если любой из исходных токенов в заданном массиве находится в отмененном состоянии.
Dispose()

Освобождает все ресурсы, используемые текущим экземпляром класса CancellationTokenSource.
Dispose(Boolean)

Освобождает неуправляемые ресурсы, используемые классом CancellationTokenSource (при необходимости освобождает и управляемые ресурсы).
Equals(Object)

Определяет, равен ли указанный объект текущему объекту.

(Унаследовано от Object)
GetHashCode()

Служит хэш-функцией по умолчанию.

(Унаследовано от Object)
GetType()

Возвращает объект Type для текущего экземпляра.

(Унаследовано от Object)
MemberwiseClone()

Создает неполную копию текущего объекта Object.

(Унаследовано от Object)
ToString()

Возвращает строку, представляющую текущий объект.

(Унаследовано от Object)
TryReset()

Пытается сбросить CancellationTokenSource для использования для несвязанной операции.

Применяется к

Потокобезопасность

Все открытые и защищенные члены CancellationTokenSource являются потокобезопасными и могут использоваться одновременно из нескольких потоков, за исключением Dispose(), которые необходимо использовать только после завершения всех остальных операций CancellationTokenSource с объектом.

См. также раздел