CancellationTokenSource Classe

Definizione

Spazio dei nomi:

System.Threading

Assembly:

System.Runtime.dll

Origine:

CancellationTokenSource.cs

Segnala a un CancellationToken che deve essere annullato.

public ref class CancellationTokenSource : IDisposable

public class CancellationTokenSource : IDisposable

type CancellationTokenSource = class
    interface IDisposable

Public Class CancellationTokenSource
Implements IDisposable

Ereditarietà

Object

CancellationTokenSource

Implementazioni

IDisposable

Esempio

Nell'esempio seguente viene usato un generatore di numeri casuali per emulare un'applicazione di raccolta dati che legge 10 valori integrali da undici strumenti diversi. Un valore pari a zero indica che la misurazione non è riuscita per uno strumento, nel qual caso l'operazione deve essere annullata e non deve essere calcolata alcuna media complessiva.

Per gestire il possibile annullamento dell'operazione, nell'esempio viene creata un'istanza di un oggetto CancellationTokenSource che genera un token di annullamento che viene passato a un oggetto TaskFactory. L'oggetto TaskFactory passa a sua volta il token di annullamento a ognuna delle attività responsabili della raccolta di letture per uno strumento specifico. Il metodo TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) viene chiamato per assicurarsi che la media venga calcolata solo dopo che tutte le letture sono state raccolte correttamente. Se un'attività non è stata completata perché è stata annullata, la chiamata al metodo TaskFactory.ContinueWhenAll genera un'eccezione.

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.

Commenti

A partire da .NET Framework 4, .NET Framework usa un modello unificato per l'annullamento cooperativo di operazioni sincrone asincrone o a esecuzione prolungata che coinvolgono due oggetti:

• Oggetto CancellationTokenSource, che fornisce un token di annullamento tramite la relativa proprietà Token e invia un messaggio di annullamento chiamando il relativo metodo Cancel o CancelAfter.

• Oggetto CancellationToken, che indica se viene richiesto l'annullamento.

Il modello generale per l'implementazione del modello di annullamento cooperativo è:

• Creare un'istanza di un oggetto CancellationTokenSource, che gestisce e invia la notifica di annullamento ai singoli token di annullamento.

• Passare il token restituito dalla proprietà CancellationTokenSource.Token a ogni attività o thread in ascolto dell'annullamento.

• Chiamare il metodo CancellationToken.IsCancellationRequested dalle operazioni che ricevono il token di annullamento. Fornire un meccanismo per ogni attività o thread per rispondere a una richiesta di annullamento. Se si sceglie di annullare un'operazione e esattamente come si esegue questa operazione, dipende dalla logica dell'applicazione.

• Chiamare il metodo CancellationTokenSource.Cancel per fornire la notifica dell'annullamento. In questo modo la proprietà CancellationToken.IsCancellationRequested su ogni copia del token di annullamento viene impostata su true.

• Chiamare il metodo Dispose al termine dell'oggetto CancellationTokenSource.

Per altre informazioni, vedere annullamento in thread gestiti.

Importante

Questo tipo implementa l'interfaccia IDisposable. Al termine dell'uso di un'istanza del tipo, è necessario eliminarla direttamente o indirettamente. Per eliminare direttamente il tipo, chiamare il metodo Dispose in un blocco try/finally. Per eliminarlo indirettamente, usare un costrutto del linguaggio, ad esempio using (in C#) o Using (in Visual Basic). Per altre informazioni, vedere la sezione "Uso di un oggetto che implementa IDisposable" nell'argomento relativo all'interfaccia IDisposable.

Costruttori

CancellationTokenSource()	Inizializza una nuova istanza della classe CancellationTokenSource.
CancellationTokenSource(Int32)	Inizializza una nuova istanza della classe CancellationTokenSource che verrà annullata dopo il ritardo specificato in millisecondi.
CancellationTokenSource(TimeSpan)	Inizializza una nuova istanza della classe CancellationTokenSource che verrà annullata dopo l'intervallo di tempo specificato.
CancellationTokenSource(TimeSpan, TimeProvider)	Inizializza una nuova istanza della classe CancellationTokenSource che verrà annullata dopo il TimeSpanspecificato.

Proprietà

IsCancellationRequested	Ottiene un valore che indica se l'annullamento è stato richiesto per questo CancellationTokenSource.
Token	Ottiene il CancellationToken associato a questo CancellationTokenSource.

Metodi

Cancel()	Comunica una richiesta di annullamento.
Cancel(Boolean)	Comunica una richiesta di annullamento e specifica se i callback rimanenti e le operazioni annullabili devono essere elaborati se si verifica un'eccezione.
CancelAfter(Int32)	Pianifica un'operazione di annullamento in questo CancellationTokenSource dopo il numero specificato di millisecondi.
CancelAfter(TimeSpan)	Pianifica un'operazione di annullamento in questo CancellationTokenSource dopo l'intervallo di tempo specificato.
CancelAsync()	Comunica una richiesta di annullamento in modo asincrono.
CreateLinkedTokenSource(CancellationToken)	Crea un CancellationTokenSource che si troverà nello stato annullato quando il token fornito si trova nello stato annullato.
CreateLinkedTokenSource(CancellationToken, CancellationToken)	Crea un CancellationTokenSource che si troverà nello stato annullato quando uno dei token di origine si trova nello stato annullato.
CreateLinkedTokenSource(CancellationToken[])	Crea un CancellationTokenSource che si troverà nello stato annullato quando uno dei token di origine nella matrice specificata si trova nello stato annullato.
Dispose()	Rilascia tutte le risorse usate dall'istanza corrente della classe CancellationTokenSource.
Dispose(Boolean)	Rilascia le risorse non gestite usate dalla classe CancellationTokenSource e, facoltativamente, rilascia le risorse gestite.
Equals(Object)	Determina se l'oggetto specificato è uguale all'oggetto corrente. (Ereditato da Object)
GetHashCode()	Funge da funzione hash predefinita. (Ereditato da Object)
GetType()	Ottiene il Type dell'istanza corrente. (Ereditato da Object)
MemberwiseClone()	Crea una copia superficiale del Objectcorrente. (Ereditato da Object)
ToString()	Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object)
TryReset()	Tenta di reimpostare il CancellationTokenSource da usare per un'operazione non correlata.

Thread safety

Tutti i membri pubblici e protetti di CancellationTokenSource sono thread-safe e possono essere usati simultaneamente da più thread, ad eccezione di Dispose(), che deve essere usato solo quando tutte le altre operazioni sull'oggetto CancellationTokenSource sono state completate.

Vedi anche

• annullamento
• annullamento attività