CancellationTokenSource クラス

定義

名前空間:

System.Threading

アセンブリ:

System.Runtime.dll

ソース:

CancellationTokenSource.cs

取り消す必要があることを CancellationToken に通知します。

public ref class CancellationTokenSource : IDisposable

public class CancellationTokenSource : IDisposable

type CancellationTokenSource = class
    interface IDisposable

Public Class CancellationTokenSource
Implements IDisposable

継承

Object

CancellationTokenSource

実装

IDisposable

例

次の例では、乱数ジェネレーターを使用して、11 個の異なるインストルメントから 10 個の整数値を読み取るデータ収集アプリケーションをエミュレートします。 値が 0 の場合は、1 つの装置で測定が失敗したことを示します。この場合、操作を取り消して、全体の平均を計算する必要はありません。

この例では、操作のキャンセルの可能性を処理するために、TaskFactory オブジェクトに渡されるキャンセル トークンを生成する CancellationTokenSource オブジェクトをインスタンス化します。 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 では、次の 2 つのオブジェクトを含む非同期または実行時間の長い同期操作を協調的に取り消す統合モデルが使用されます。

• 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)	指定した TimeSpanの後に取り消される CancellationTokenSource クラスの新しいインスタンスを初期化します。

プロパティ

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 オブジェクトに対する他のすべての操作が完了した場合にのみ使用する必要があります。

こちらもご覧ください

• 取り消し
• タスクの取り消し