CancellationToken Estructura

Definición

Propaga la notificación de que las operaciones deberían cancelarse.Propagates notification that operations should be canceled.

public value class CancellationToken
[System.Runtime.InteropServices.ComVisible(false)]
public struct CancellationToken
type CancellationToken = struct
Public Structure CancellationToken
Herencia
CancellationToken
Atributos

Ejemplos

En el ejemplo siguiente se utiliza 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.The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. Un valor de cero indica que se ha producido un error en la medida para un instrumento, en cuyo caso se debe cancelar la operación y no se debe calcular la media global.A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed.

Para controlar la posible cancelación de la operación, en el ejemplo se crea una instancia de un objeto CancellationTokenSource que genera un token de cancelación que se pasa a un objeto TaskFactory.To handle the possible cancellation of the operation, the example instantiates a CancellationTokenSource object that generates a cancellation token which is passed to a TaskFactory object. A su vez, el objeto TaskFactory pasa el token de cancelación a cada una de las tareas responsables de recopilar las lecturas de un instrumento determinado.The TaskFactory object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. 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.The TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) method is called to ensure that the mean is computed only after all readings have been gathered successfully. Si una tarea no se ha cancelado porque se ha cancelado, la llamada al método TaskFactory.ContinueWhenAll produce una excepción.If a task has not because it has been cancelled, the call to the TaskFactory.ContinueWhenAll method throws an exception.

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

Un CancellationToken permite la cancelación cooperativa entre subprocesos, elementos de trabajo del grupo de subprocesos o objetos Task.A CancellationToken enables cooperative cancellation between threads, thread pool work items, or Task objects. Cree un token de cancelación mediante la creación de una instancia de un objeto CancellationTokenSource, que administra los tokens de cancelación recuperados de su propiedad CancellationTokenSource.Token.You create a cancellation token by instantiating a CancellationTokenSource object, which manages cancellation tokens retrieved from its CancellationTokenSource.Token property. A continuación, se pasa el token de cancelación a cualquier número de subprocesos, tareas u operaciones que deben recibir un aviso de cancelación.You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. El token no se puede usar para iniciar la cancelación.The token cannot be used to initiate cancellation. Cuando el objeto propietario llama a CancellationTokenSource.Cancel, la propiedad IsCancellationRequested en cada copia del token de cancelación se establece en true.When the owning object calls CancellationTokenSource.Cancel, the IsCancellationRequested property on every copy of the cancellation token is set to true. Los objetos que reciben la notificación pueden responder de la manera adecuada.The objects that receive the notification can respond in whatever manner is appropriate.

Para obtener más información y ejemplos de código, vea cancelación en subprocesos administrados.For more information and code examples see Cancellation in Managed Threads.

Constructores

CancellationToken(Boolean)

Inicializa el CancellationToken.Initializes the CancellationToken.

Propiedades

CanBeCanceled

Obtiene si este token es capaz de existir en el estado cancelado.Gets whether this token is capable of being in the canceled state.

IsCancellationRequested

Obtiene si se ha solicitado la cancelación para este token.Gets whether cancellation has been requested for this token.

None

Devuelve un valor CancellationToken vacío.Returns an empty CancellationToken value.

WaitHandle

Obtiene un WaitHandle que se señala cuando el token se cancela.Gets a WaitHandle that is signaled when the token is canceled.

Métodos

Equals(CancellationToken)

Determina si la instancia de CancellationToken actual es igual que el token especificado.Determines whether the current CancellationToken instance is equal to the specified token.

Equals(Object)

Determina si la instancia de CancellationToken actual es igual que la instancia de Object especificada.Determines whether the current CancellationToken instance is equal to the specified Object.

GetHashCode()

Sirve como función hash de un objeto CancellationToken.Serves as a hash function for a CancellationToken.

Register(Action)

Registra un delegado que se invocará cuando se cancele este objeto CancellationToken.Registers a delegate that will be called when this CancellationToken is canceled.

Register(Action, Boolean)

Registra un delegado que se invocará cuando se cancele este objeto CancellationToken.Registers a delegate that will be called when this CancellationToken is canceled.

Register(Action<Object>, Object)

Registra un delegado que se invocará cuando se cancele este objeto CancellationToken.Registers a delegate that will be called when this CancellationToken is canceled.

Register(Action<Object>, Object, Boolean)

Registra un delegado que se invocará cuando se cancele este objeto CancellationToken.Registers a delegate that will be called when this CancellationToken is canceled.

ThrowIfCancellationRequested()

Produce OperationCanceledException si este token ha tenido una solicitud de cancelación.Throws a OperationCanceledException if this token has had cancellation requested.

UnsafeRegister(Action<Object>, Object)

Registra un delegado que se invoca cuando se cancela este objeto CancellationToken.Registers a delegate that is called when this CancellationToken is canceled.

Operadores

Equality(CancellationToken, CancellationToken)

Determina si dos instancias de CancellationToken son iguales.Determines whether two CancellationToken instances are equal.

Inequality(CancellationToken, CancellationToken)

Determina si dos instancias de CancellationToken no son iguales.Determines whether two CancellationToken instances are not equal.

Se aplica a

Seguridad para subprocesos

Todos los miembros públicos y protegidos de CancellationToken son seguros para subprocesos y se pueden usar simultáneamente desde varios subprocesos.All public and protected members of CancellationToken are thread-safe and may be used concurrently from multiple threads.

Consulte también: