structured_task_group-Klasse

Die structured_task_group-Klasse stellt eine stark strukturierte Auflistung paralleler Arbeit dar. Sie können einzelne parallele Aufgaben mithilfe von structured_task_group-Objekten in eine Warteschlange task_handle stellen und abwarten, bis sie abgeschlossen sind, oder die Aufgabenliste abbrechen, bevor deren Ausführung beendet ist. Dadurch werden auch alle Aufgaben abgebrochen, deren Ausführung noch nicht begonnen wurde.

Syntax

class structured_task_group;

Mitglieder

Öffentliche Konstruktoren

Öffentliche Methoden

Hinweise

Es gibt eine Reihe schwerwiegender Einschränkungen für die Verwendung eines structured_task_group Objekts zur Leistungssteigerung.

• Ein einzelnes structured_task_group Objekt kann nicht von mehreren Threads verwendet werden. Alle Vorgänge für ein structured_task_group Objekt müssen vom Thread ausgeführt werden, der das Objekt erstellt hat. Die beiden Ausnahmen dieser Regel sind die Memberfunktionen cancel und is_canceling. Das Objekt darf sich nicht in der Erfassungsliste eines Lambda-Ausdrucks befinden und in einer Aufgabe verwendet werden, es sei denn, die Aufgabe nutzt einen der Abbruchvorgänge.

• Alle vorgänge, die für ein structured_task_group Objekt geplant sind, werden mithilfe von task_handle Objekten geplant, von denen Sie die Lebensdauer explizit verwalten müssen.

• Mehrere Gruppen können nur in absolut geschachtelter Reihenfolge verwendet werden. Wenn zwei structured_task_group Objekte deklariert werden, muss das zweite (innere) zerstört werden, bevor eine Methode außer cancel oder is_canceling auf das erste (äußere) Objekt aufgerufen wird. Diese Bedingung gilt sowohl für das einfache Deklarieren mehrerer structured_task_group Objekte innerhalb derselben oder funktional geschachtelter Bereiche als auch für den Fall eines Vorgangs, der über die Methoden structured_task_group in die runrun_and_wait Warteschlange gestellt wurde.

• Im Gegensatz zur allgemeinen task_group Klasse sind alle Zustände in der structured_task_group Klasse abgeschlossen. Nachdem Sie Aufgaben in die Warteschlange der Gruppe eingereiht und auf den Abschluss gewartet haben, verwenden Sie möglicherweise nicht erneut dieselbe Gruppe.

Weitere Informationen finden Sie unter Task Parallelism.

Vererbungshierarchie

structured_task_group

Anforderungen

Kopfzeile: ppl.h

Namespace: Parallelität

Abbrechen

Es wird eine bestmögliche Anstrengung unternommen, die Teilstruktur der Arbeit abzubrechen, die in dieser Aufgabengruppe verankert ist. Alle Aufgaben, die für die Aufgabengruppe geplant sind, werden, sofern möglich, auch transitiv abgebrochen.

void cancel();

Hinweise

Weitere Informationen finden Sie unter "Stornierung".

wird abgebrochen

Informiert den Anrufer darüber, ob sich die Aufgabengruppe derzeit inmitten eines Abbruchvorgangs befindet. Dies weist nicht unbedingt darauf hin, dass die Methode cancel auf das Objekt structured_task_group angewendet wurde (obwohl diese Methode sicherlich qualifiziert ist, um true zurückzugeben). Es kann vorkommen, dass das structured_task_group Objekt im Inline-Modus ausgeführt wird und eine Aufgabengruppe weiter oben im Arbeitsbaum abgebrochen wurde. In Fällen wie diesen, in denen die Laufzeit im Voraus bestimmen kann, dass der Abbruch durch dieses structured_task_group-Objekt erfolgt, wird true ebenfalls zurückgegeben.

bool is_canceling();

Rückgabewert

Ein Hinweis darauf, ob sich das structured_task_group Objekt mitten in einer Stornierung befindet (oder kurz darauf garantiert ist).

Hinweise

Weitere Informationen finden Sie unter "Stornierung".

ausführen

Plant einen Vorgang für das structured_task_group Objekt. Der Aufrufer verwaltet die Lebensdauer des Objekts, das im _Task_handle-Parameter übergeben wird. Die Version, die den Parameter _Placement verwendet, bewirkt, dass die Aufgabe an dem durch diesen Parameter angegebenen Speicherort ausgeführt wird.

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle);

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle,
    location& _Placement);

Parameter

_Funktion
Der Typ des Funktionsobjekts, das aufgerufen wird, um den Körper des Task-Handles auszuführen.

_Task_handle
Ein Handle für die geplante Arbeit. Beachten Sie, dass der Aufrufer für die Lebensdauer dieses Objekts verantwortlich ist. Die Laufzeit erwartet weiterhin, dass es vorhanden bleibt, bis entweder die wait- oder die run_and_wait-Methode für dieses structured_task_group-Objekt aufgerufen wurde.

_Platzierung
Ein Verweis auf den Speicherort, an dem die durch den _Task_handle Parameter dargestellte Aufgabe ausgeführt werden soll.

Hinweise

Die Laufzeit erstellt eine Kopie der Arbeitsfunktion, die Sie an diese Methode übergeben. Alle Zustandsänderungen, die in einem Funktionsobjekt auftreten, das Sie an diese Methode übergeben, werden nicht in Ihrer Kopie dieses Funktionsobjekts angezeigt.

Wenn der structured_task_group-Destruktor als Ergebnis des Ablaufs des Stapels durch eine Ausnahme hervorgerufen wird, müssen Sie nicht garantieren, dass ein Aufruf an die wait- oder run_and_wait-Methode erfolgt ist. In diesem Fall wird der Destruktor ordnungsgemäß abbrechen und warten, bis die Aufgabe, die durch den _Task_handle Parameter dargestellt wird, abgeschlossen ist.

Löst eine invalid_multiple_scheduling Ausnahme aus, wenn das vom _Task_handle Parameter angegebene Task-Handle bereits über die run Methode auf ein Task-Group-Objekt eingeplant wurde und es keinen dazwischen liegenden Aufruf der wait oder run_and_wait Methode für diese Aufgabengruppe gab.

run_and_wait

Plant eine Aufgabe, die im Aufrufkontext mit der Hilfe des structured_task_group-Objekts inline ausgeführt wird, um die vollständige Abbruchunterstützung zu gewährleisten. Wenn ein task_handle Objekt als Parameter run_and_waitübergeben wird, ist der Aufrufer für die Verwaltung der Lebensdauer des task_handle Objekts verantwortlich. Die Funktion wartet dann, bis alle Arbeiten am structured_task_group Objekt abgeschlossen oder abgebrochen wurden.

template<class _Function>
task_group_status run_and_wait(task_handle<_Function>& _Task_handle);

template<class _Function>
task_group_status run_and_wait(const _Function& _Func);

Parameter

_Funktion
Der Typ des Funktionsobjekts, das aufgerufen wird, um die Aufgabe auszuführen.

_Task_handle
Ein Handle für die Aufgabe, die im aufrufenden Kontext inline ausgeführt wird. Beachten Sie, dass der Aufrufer für die Lebensdauer dieses Objekts verantwortlich ist. Die Runtime-Umgebung erwartet, dass sie weiterhin bis zum Abschluss der Ausführung der run_and_wait Methode live ist.

_Func
Eine Funktion, die aufgerufen wird, um den Textkörper der Arbeit aufzurufen. Dies kann ein Lambda- oder ein anderes Objekt sein, das eine Version des Funktionsaufrufoperators mit der Signatur void operator()()unterstützt.

Rückgabewert

Ein Hinweis darauf, ob die Wartezeit erfüllt wurde oder die Aufgabengruppe aufgrund eines expliziten Abbruchvorgangs oder einer Ausnahme, die von einer seiner Aufgaben ausgelöst wird, abgebrochen wurde. Weitere Informationen finden Sie unter task_group_status

Hinweise

Beachten Sie, dass eine oder mehrere der für dieses structured_task_group Objekt geplanten Aufgaben inline im aufrufenden Kontext ausgeführt werden können.

Wenn eine oder mehrere der für dieses structured_task_group-Objekt geplanten Aufgaben eine Ausnahme werfen, wählt die Laufzeit eine dieser Ausnahmen aus und leitet sie aus dem Aufruf der run_and_wait-Methode weiter.

Nachdem diese Funktion zurückgegeben wurde, wird das structured_task_group Objekt in einem endgültigen Zustand betrachtet und sollte nicht verwendet werden. Beachten Sie, dass die Verwendung nach der Rückgabe der run_and_wait Methode zu einem nicht definierten Verhalten führt.

Im normalen Ausführungspfad haben Sie die Vorgabe, entweder diese Methode oder die wait Methode aufzurufen, bevor der Destruktor von structured_task_group ausgeführt wird.

strukturierte Aufgaben-Gruppe

Erstellt ein neues structured_task_group-Objekt.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Parameter

_CancellationToken
Ein Abbruchtoken, das dieser strukturierten Aufgabengruppe zugeordnet werden soll. Die strukturierte Aufgabengruppe wird abgebrochen, wenn das Token abgebrochen wird.

Hinweise

Der Konstruktor, der ein Abbruchtoken akzeptiert, erstellt ein structured_task_group, das abgebrochen wird, wenn die dem Token zugeordnete Quelle abgebrochen wird. Wenn Sie ein explizites Abbruchtoken bereitstellen, wird diese strukturierte Aufgabengruppe auch von der Teilnahme an einem impliziten Abbruch einer übergeordneten Gruppe mit einem anderen Token oder keinem Token isoliert.

~structured_task_group

Zerstört ein structured_task_group -Objekt. Es wird erwartet, dass Sie entweder die wait-Methode oder die run_and_wait-Methode für das Objekt aufrufen, bevor der Destruktor ausgeführt wird, es sei denn, der Destruktor wird infolge eines Stack-Unwindings aufgrund einer Ausnahme ausgeführt.

~structured_task_group();

Hinweise

Wenn der Destruktor als Ergebnis der normalen Ausführung (z. B. nicht aufgrund eines Stack-Unwindings durch eine Ausnahme) ausgeführt wird und weder die wait- noch die run_and_wait-Methoden aufgerufen wurden, kann der Destruktor eine missing_wait-Ausnahme auslösen.

warten

Wartet, bis alle Arbeiten an dem structured_task_group abgeschlossen oder abgebrochen wurden.

task_group_status wait();

Rückgabewert

Ein Hinweis darauf, ob die Wartezeit erfüllt oder die Aufgabengruppe abgebrochen wurde, aufgrund eines expliziten Abbruchvorgangs oder einer Ausnahme, die von einem seiner Aufgaben ausgelöst wird. Weitere Informationen finden Sie unter task_group_status

Hinweise

Beachten Sie, dass eine oder mehrere der für dieses structured_task_group Objekt geplanten Aufgaben inline im aufrufenden Kontext ausgeführt werden können.

Wenn mindestens eine der für dieses structured_task_group Objekt geplanten Aufgaben eine Ausnahme auslöst, wählt die Laufzeit eine Ausnahme ihrer Wahl und propagiert sie aus dem Aufruf der wait Methode.

Nachdem diese Funktion zurückgegeben wurde, wird das structured_task_group Objekt in einem endgültigen Zustand betrachtet und sollte nicht verwendet werden. Beachten Sie, dass die Verwendung nach der Rückgabe der wait Methode zu einem nicht definierten Verhalten führt.

Im regulären Ausführungspfad sind Sie verpflichtet, entweder diese Methode oder die run_and_wait Methode aufzurufen, bevor der Destruktor von structured_task_group ausgeführt wird.

Siehe auch

Concurrency-Namespace
task_group-Klasse
task_handle-Klasse