CancellationTokenSource Clase

Definición

Espacio de nombres:

System.Threading

Ensamblado:

System.Runtime.dll

Source:

CancellationTokenSource.cs

Indica a un CancellationToken que se debe cancelar.

public ref class CancellationTokenSource : IDisposable

public class CancellationTokenSource : IDisposable

type CancellationTokenSource = class
    interface IDisposable

Public Class CancellationTokenSource
Implements IDisposable

Herencia

Object

CancellationTokenSource

Implementaciones

IDisposable

Ejemplos

En el ejemplo siguiente se usa un generador de números aleatorios para emular una aplicación de recopilación de datos que lee 10 valores enteros de once instrumentos diferentes. Un valor de cero indica que se ha producido un error en la medida de un instrumento, en cuyo caso se debe cancelar la operación y no se debe calcular ninguna media general.

Para controlar la posible cancelación de la operación, el ejemplo crea una instancia de un objeto CancellationTokenSource que genera un token de cancelación que se pasa a un objeto TaskFactory. A su vez, el objeto TaskFactory pasa el token de cancelación a cada una de las tareas responsables de recopilar lecturas para un instrumento determinado. Se llama al método TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) para asegurarse de que la media se calcula solo después de que todas las lecturas se hayan recopilado correctamente. Si no se ha completado una tarea porque se ha cancelado, la llamada al método TaskFactory.ContinueWhenAll produce una excepción.

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.

Comentarios

A partir de .NET Framework 4, .NET Framework usa un modelo unificado para la cancelación cooperativa de operaciones sincrónicas asincrónicas o de larga duración que implican dos objetos:

• Objeto CancellationTokenSource, que proporciona un token de cancelación a través de su propiedad Token y envía un mensaje de cancelación llamando a su método Cancel o CancelAfter.

• Objeto CancellationToken, que indica si se solicita la cancelación.

El patrón general para implementar el modelo de cancelación cooperativa es:

• Cree una instancia de un objeto CancellationTokenSource, que administra y envía una notificación de cancelación a los tokens de cancelación individuales.

• Pase el token devuelto por la propiedad CancellationTokenSource.Token a cada tarea o subproceso que escucha la cancelación.

• Llame al método CancellationToken.IsCancellationRequested desde operaciones que reciben el token de cancelación. Proporcione un mecanismo para que cada tarea o subproceso responda a una solicitud de cancelación. Tanto si decide cancelar una operación como si lo hace exactamente, depende de la lógica de la aplicación.

• Llame al método CancellationTokenSource.Cancel para proporcionar una notificación de cancelación. Esto establece la propiedad CancellationToken.IsCancellationRequested en cada copia del token de cancelación en true.

• Llame al método Dispose cuando haya terminado con el objeto CancellationTokenSource.

Para obtener más información, consulte Cancelación en subprocesos administrados.

Importante

Este tipo implementa la interfaz IDisposable. Cuando haya terminado de usar una instancia del tipo, debe eliminarla directa o indirectamente. Para eliminar el tipo directamente, llame a su método Dispose en un bloque try/finally. Para eliminarlo indirectamente, use una construcción de lenguaje como using (en C#) o Using (en Visual Basic). Para obtener más información, vea la sección "Using an Object that Implements IDisposable" (Usar un objeto que implementa IDisposable) en el tema IDisposable interfaz.

Constructores

CancellationTokenSource()	Inicializa una nueva instancia de la clase CancellationTokenSource.
CancellationTokenSource(Int32)	Inicializa una nueva instancia de la clase CancellationTokenSource que se cancelará después del retraso especificado en milisegundos.
CancellationTokenSource(TimeSpan)	Inicializa una nueva instancia de la clase CancellationTokenSource que se cancelará después del intervalo de tiempo especificado.
CancellationTokenSource(TimeSpan, TimeProvider)	Inicializa una nueva instancia de la clase CancellationTokenSource que se cancelará después del TimeSpanespecificado.

Propiedades

IsCancellationRequested	Obtiene si se ha solicitado la cancelación para este CancellationTokenSource.
Token	Obtiene el CancellationToken asociado a este CancellationTokenSource.

Métodos

Cancel()	Comunica una solicitud de cancelación.
Cancel(Boolean)	Comunica una solicitud de cancelación y especifica si se deben procesar las devoluciones de llamada restantes y las operaciones cancelables si se produce una excepción.
CancelAfter(Int32)	Programa una operación de cancelación en este CancellationTokenSource después del número especificado de milisegundos.
CancelAfter(TimeSpan)	Programa una operación de cancelación en este CancellationTokenSource después del intervalo de tiempo especificado.
CancelAsync()	Comunica una solicitud de cancelación de forma asincrónica.
CreateLinkedTokenSource(CancellationToken)	Crea un CancellationTokenSource que estará en estado cancelado cuando el token proporcionado esté en estado cancelado.
CreateLinkedTokenSource(CancellationToken, CancellationToken)	Crea un CancellationTokenSource que estará en estado cancelado cuando alguno de los tokens de origen esté en estado cancelado.
CreateLinkedTokenSource(CancellationToken[])	Crea un CancellationTokenSource que estará en estado cancelado cuando cualquiera de los tokens de origen de la matriz especificada esté en estado cancelado.
Dispose()	Libera todos los recursos usados por la instancia actual de la clase CancellationTokenSource.
Dispose(Boolean)	Libera los recursos no administrados utilizados por la clase CancellationTokenSource y, opcionalmente, libera los recursos administrados.
Equals(Object)	Determina si el objeto especificado es igual al objeto actual. (Heredado de Object)
GetHashCode()	Actúa como función hash predeterminada. (Heredado de Object)
GetType()	Obtiene el Type de la instancia actual. (Heredado de Object)
MemberwiseClone()	Crea una copia superficial del Objectactual. (Heredado de Object)
ToString()	Devuelve una cadena que representa el objeto actual. (Heredado de Object)
TryReset()	Intenta restablecer el CancellationTokenSource que se va a usar para una operación no relacionada.

Seguridad para subprocesos

Todos los miembros públicos y protegidos de CancellationTokenSource son seguros para subprocesos y se pueden usar simultáneamente desde varios subprocesos, con la excepción de Dispose(), que solo se debe usar cuando se hayan completado todas las demás operaciones del objeto CancellationTokenSource.

Consulte también

• de cancelación de
• de cancelación de tareas de