CancellationTokenSource Klasse
Definition
Wichtig
Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.
Signalisiert einem CancellationToken, dass es abgebrochen werden soll.
public ref class CancellationTokenSource : IDisposablepublic ref class CancellationTokenSource sealed : IDisposablepublic class CancellationTokenSource : IDisposable[System.Runtime.InteropServices.ComVisible(false)]
public sealed class CancellationTokenSource : IDisposable[System.Runtime.InteropServices.ComVisible(false)]
public class CancellationTokenSource : IDisposabletype CancellationTokenSource = class
interface IDisposable[<System.Runtime.InteropServices.ComVisible(false)>]
type CancellationTokenSource = class
interface IDisposablePublic Class CancellationTokenSource
Implements IDisposablePublic NotInheritable Class CancellationTokenSource
Implements IDisposable- Vererbung
-
CancellationTokenSource
- Attribute
- Implementiert
Beispiele
Im folgenden Beispiel wird ein Zufallszahlengenerator verwendet, um eine Datensammlungsanwendung zu emulieren, die 10 integrale Werte aus elf verschiedenen Instrumenten liest. Ein Wert von Null gibt an, dass die Messung für ein Instrument fehlgeschlagen ist, in diesem Fall sollte der Vorgang abgebrochen werden und kein Gesamtwert berechnet werden.
Um den möglichen Abbruch des Vorgangs zu behandeln, instanziiert das Beispiel ein CancellationTokenSource -Objekt, das ein Abbruchtoken wird, die generiert an eine TaskFactory Objekt. Das TaskFactory Objekt übergibt wiederum das Abbruchtoken an jede der Aufgaben, die für das Sammeln von Lesevorgängen für ein bestimmtes Instrument verantwortlich sind. Die TaskFactory.ContinueWhenAll<TAntecedentResult,TResult>(Task<TAntecedentResult>[], Func<Task<TAntecedentResult>[],TResult>, CancellationToken) Methode wird aufgerufen, um sicherzustellen, dass das Mittel nur berechnet wird, nachdem alle Lesewerte erfolgreich gesammelt wurden. Wenn eine Aufgabe nicht abgeschlossen wurde, weil sie abgebrochen wurde, löst der Aufruf der TaskFactory.ContinueWhenAll Methode eine Ausnahme aus.
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.
Hinweise
Ab dem .NET Framework 4 verwendet die .NET Framework ein einheitliches Modell für die gemeinsame Abbruch von asynchronen oder lang ausgeführten synchronen Vorgängen, die zwei Objekte umfassen:
Ein CancellationTokenSource Objekt, das ein Abbruchtoken über seine Token Eigenschaft bereitstellt und eine Abbruchnachricht sendet, indem er seine Cancel CancelAfter Methode aufruft.
Ein CancellationToken Objekt, das angibt, ob eine Abbruch angefordert wird.
Das allgemeine Muster für die Implementierung des kooperativen Abbruchmodells lautet:
Instanziieren Sie ein CancellationTokenSource-Objekt, das die Abbruchbenachrichtigung verwaltet und an die einzelnen Abbruchtoken sendet.
Übergeben Sie das zurückgegebene Token über die CancellationTokenSource.Token-Eigenschaft an jede Aufgabe oder Thread, der zum Lauschen verwendet wird, um den Abbruch zu bemerken.
Rufen Sie die Methode von Vorgängen auf, die das CancellationToken.IsCancellationRequested Abbruchtoken empfangen. Stellen Sie einen Mechanismus für jede Aufgabe oder einen Thread bereit, um auf eine Abbruchanforderung zu reagieren. Ob Sie einen Vorgang abbrechen und genau wie Sie es tun, hängt von Ihrer Anwendungslogik ab.
Rufen Sie die CancellationTokenSource.Cancel-Methode auf, um eine Benachrichtigung über den Abbruch bereitzustellen. Dadurch wird die CancellationToken.IsCancellationRequested Eigenschaft auf jeder Kopie des Abbruchtokens auf
truefestgelegt.Rufen Sie die Dispose Methode auf, wenn Sie mit dem CancellationTokenSource Objekt fertig sind.
Weitere Informationen finden Sie unter Abbruch in verwalteten Threads.
Wichtig
Dieser Typ implementiert die IDisposable-Schnittstelle. Wenn Sie die Verwendung einer Instanz des Typs abgeschlossen haben, sollten Sie sie entweder direkt oder indirekt entsorgen. Zum direkten Löschen des Typs rufen Sie seine Dispose-Methode in einem try/catch-Block auf. Zum indirekten Löschen verwenden Sie ein Sprachkonstrukt wie using (in C#) oder Using (in Visual Basic). Weitere Informationen finden Sie im Abschnitt „Verwenden eines Objekts, das IDisposable implementiert“ des Themas „Die IDisposable-Schnittstelle“.
Konstruktoren
| CancellationTokenSource() |
Initialisiert eine neue Instanz der CancellationTokenSource-Klasse. |
| CancellationTokenSource(Int32) |
Initialisiert eine neue Instanz der CancellationTokenSource-Klasse, die nach der angegebenen Verzögerung in Millisekunden abgebrochen wird. |
| CancellationTokenSource(TimeSpan) |
Initialisiert eine neue Instanz der CancellationTokenSource-Klasse, die nach der angegebenen Zeitspanne abgebrochen wird. |
Eigenschaften
| IsCancellationRequested |
Ruft einen Wert ab, der angibt, ob für diese CancellationTokenSource ein Abbruch angefordert wurde. |
| Token |
Ruft den diesem CancellationToken zugeordneten CancellationTokenSource ab. |
Methoden
| Cancel() |
Übermittelt eine Abbruchanforderung. |
| Cancel(Boolean) |
Teilt eine Anforderung für Abbruch mit und gibt an, ob verbleibende Rückrufe und abbrechbare Vorgänge verarbeitet werden sollen, wenn keine Ausnahme auftritt. |
| CancelAfter(Int32) |
Plant einen Abbruch auf diesem CancellationTokenSource nach der angegebenen Anzahl von Millisekunden. |
| CancelAfter(TimeSpan) |
Plant einen Abbruch auf diesem CancellationTokenSource nach der angegebenen Zeitspanne. |
| CreateLinkedTokenSource(CancellationToken) |
Erstellt eine CancellationTokenSource, die sich im Zustand „abgebrochen“ befindet, wenn sich das übergebene Token im Zustand „abgebrochen“ befindet. |
| CreateLinkedTokenSource(CancellationToken, CancellationToken) |
Erstellt eine CancellationTokenSource, für die der Zustand "abgebrochen" festgelegt wird, wenn eines der Quelltoken im Zustand "abgebrochen" ist. |
| CreateLinkedTokenSource(CancellationToken[]) |
Erstellt eine CancellationTokenSource, für die der Zustand "abgebrochen" festgelegt wird, wenn eines der Quelltoken im angegebenen Array im Zustand "abgebrochen" ist. |
| Dispose() |
Gibt alle von der aktuellen Instanz der CancellationTokenSource-Klasse verwendeten Ressourcen frei. |
| Dispose(Boolean) |
Gibt die von der CancellationTokenSource-Klasse verwendeten nicht verwalteten Ressourcen frei und gibt (optional) auch die verwalteten Ressourcen frei. |
| Equals(Object) |
Bestimmt, ob das angegebene Objekt gleich dem aktuellen Objekt ist. (Geerbt von Object) |
| GetHashCode() |
Fungiert als Standardhashfunktion. (Geerbt von Object) |
| GetType() |
Ruft den Type der aktuellen Instanz ab. (Geerbt von Object) |
| MemberwiseClone() |
Erstellt eine flache Kopie des aktuellen Object. (Geerbt von Object) |
| ToString() |
Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt. (Geerbt von Object) |
| TryReset() |
Versucht, den CancellationTokenSource für einen nicht verbundenen Vorgang zu verwendenden Vorgang zurückzusetzen. |
Gilt für
Threadsicherheit
Alle öffentlichen und geschützten Elemente CancellationTokenSource sind threadsicher und können gleichzeitig von mehreren Threads verwendet werden, mit Ausnahme Dispose()von , die nur verwendet werden müssen, wenn alle anderen Vorgänge im CancellationTokenSource Objekt abgeschlossen sind.