CancellationTokenSource Classe

Definizione

Spazio dei nomi:

System.Threading

Assembly:

System.Runtime.dll

Source:

CancellationTokenSource.cs

Segnala a un oggetto 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 CancellationTokenSource oggetto che genera un token di annullamento passato a un TaskFactory oggetto . L'oggetto TaskFactory passa a sua volta il token di annullamento a ognuna delle attività responsabili della raccolta delle letture per uno strumento specifico. Il TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) metodo viene chiamato per garantire 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 TaskFactory.ContinueWhenAll chiamata al metodo 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 Token proprietà e invia un messaggio di annullamento chiamando il Cancel relativo metodo o CancelAfter .

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

Il criterio generale per implementare il modello di annullamento cooperativo è il seguente:

• 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 attesa di annullamento.

• Chiamare il CancellationToken.IsCancellationRequested metodo 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 eseguire questa operazione, dipende dalla logica dell'applicazione.

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

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

Per altre informazioni, vedere Annullamento nei thread gestiti.

Importante

Il 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, utilizzare un costrutto di linguaggio come 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 CancellationTokenSource classe che verrà annullata dopo l'oggetto specificato TimeSpan.

Proprietà

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

Metodi

Cancel()	Comunica una richiesta di annullamento.
Cancel(Boolean)	Passa una richiesta di annullamento e specifica se i callback restanti e le operazioni annullabili devono essere elaborati se si verifica un'eccezione.
CancelAfter(Int32)	Programma un'operazione di annullamento in questo oggetto CancellationTokenSource dopo il numero di millisecondi specificato.
CancelAfter(TimeSpan)	Programma un'operazione di annullamento in questo oggetto CancellationTokenSource dopo l'intervallo di tempo specificato.
CancelAsync()	Comunica una richiesta di annullamento in modo asincrono.
CreateLinkedTokenSource(CancellationToken)	Crea un oggetto CancellationTokenSource che sarà in stato annullato quando il token specificato si troverà in stato annullato.
CreateLinkedTokenSource(CancellationToken, CancellationToken)	Crea un oggetto CancellationTokenSource che sarà in stato annullato quando uno dei token di origine si troverà in stato annullato.
CreateLinkedTokenSource(CancellationToken[])	Crea un oggetto CancellationTokenSource che sarà nello stato annullato quando uno dei token di origine nella matrice specificata si troverà 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 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 l'oggetto Type dell'istanza corrente. (Ereditato da Object)
MemberwiseClone()	Crea una copia superficiale dell'oggetto Object corrente. (Ereditato da Object)
ToString()	Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object)
TryReset()	Tenta di reimpostare l'oggetto CancellationTokenSource da utilizzare 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 devono essere usati solo quando tutte le altre operazioni sull'oggetto CancellationTokenSource sono state completate.

Vedi anche

• Annullamento
• Annullamento delle attività