CancellationTokenSource 类

定义

命名空间:

System.Threading

程序集:

System.Runtime.dll

Source:

CancellationTokenSource.cs

向 CancellationToken 发出应取消的信号。

C#

public class CancellationTokenSource : IDisposable

继承

Object

CancellationTokenSource

实现

IDisposable

示例

以下示例使用随机数生成器模拟从 11 个不同的仪器读取 10 个整型值的数据收集应用程序。 值为零表示一个检测的度量值已失败，在这种情况下，应取消操作，并且不应计算总体平均值。

为了处理操作的可能取消，该示例实例化一个 CancellationTokenSource 对象，该对象生成传递给 TaskFactory 对象的取消令牌。 TaskFactory 对象反过来会将取消令牌传递给负责收集特定仪器读取的每个任务。 调用 TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) 方法以确保仅在成功收集所有读数后计算平均值。 如果任务因已取消而尚未完成，则对 TaskFactory.ContinueWhenAll 方法的调用将引发异常。

C#

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.

注解

从 .NET Framework 4 开始，.NET Framework 使用统一模型来协作取消涉及两个对象的异步或长时间运行的同步操作：

• CancellationTokenSource 对象，它通过其 Token 属性提供取消令牌，并通过调用其 Cancel 或 CancelAfter 方法发送取消消息。

• 一个 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	获取与此 CancellationTokenSource关联的 CancellationToken。

方法

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 对象上所有其他操作完成时使用。

另请参阅

• 取消
• 任务取消