Freigeben über

structured_task_group-Klasse

  • Artikel

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 task_handle stellen und warten, bis sie abgeschlossen werden, oder Sie können die Aufgabengruppe abbrechen, bevor deren Ausführung beendet wird, wodurch auch alle Aufgaben abgebrochen werden, deren Ausführung nicht gestartet wurde.

Syntax

class structured_task_group;

Member

Öffentliche Konstruktoren

Name Beschreibung
structured_task_group Überladen. Erstellt ein neues structured_task_group-Objekt.
~structured_task_group Destruktor Zerstört ein structured_task_group -Objekt. Es wird erwartet, dass Sie die Methode oder run_and_wait die wait Methode für das Objekt vor dem Ausführen des Destruktors aufrufen, es sei denn, der Destruktor wird aufgrund einer Ausnahme als Ergebnis der Stapelaussetzung ausgeführt.

Öffentliche Methoden

Name Beschreibung
cancel Es wird versucht, die Unterstruktur der Arbeit abzubrechen, die in dieser Aufgabengruppe verwurzelt ist. Alle vorgänge, die für die Vorgangsgruppe geplant sind, werden nach Möglichkeit transitiv abgebrochen.
is_canceling Informiert den Anrufer darüber, ob sich die Aufgabengruppe derzeit mitten in einer Abbruchzeit befindet. Dies weist nicht unbedingt darauf hin, dass die cancel Methode für das structured_task_group Objekt aufgerufen wurde (obwohl diese Methode sicherlich für die Rückgabe truequalifiziert). Es kann vorkommen, dass das structured_task_group Objekt inline ausgeführt wird und eine Aufgabengruppe weiter oben in der Arbeitsstruktur abgebrochen wurde. In Fällen wie diesen, in denen die Laufzeit vor dem Ablauf des Abbruchs durch dieses structured_task_group Objekt bestimmen kann, true wird ebenfalls zurückgegeben.
run Überladen. Plant einen Vorgang für das structured_task_group Objekt. Der Aufrufer verwaltet die Lebensdauer des objekts, das task_handle _Task_handle im Parameter übergeben wird. Die Version, die den Parameter _Placement verwendet, bewirkt, dass die Aufgabe an dem durch diesen Parameter angegebenen Speicherort ausgeführt wird.
run_and_wait Überladen. Plant, dass eine Aufgabe im Aufrufkontext inline ausgeführt wird, wobei das Objekt unterstützung structured_task_group für die vollständige Abbruchunterstützung unterstützt. 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 structured_task_group am Objekt abgeschlossen oder abgebrochen wurden.
wait Wartet, bis alle Arbeiten an dem structured_task_group Vorgang abgeschlossen oder abgebrochen wurden.

Hinweise

Es gibt eine Reihe schwerwiegender Einschränkungen für die Verwendung eines structured_task_group Objekts, um die Leistung zu erzielen:

  • 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 befindet sich möglicherweise nicht in der Aufnahmeliste eines Lambda-Ausdrucks und wird innerhalb einer Aufgabe verwendet, es sei denn, die Aufgabe verwendet 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 die zweite deklariert werden (die innere) destruktieren, bevor eine Methode cancel außer oder is_canceling für die erste (die äußere) 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 run_and_wait in die structured_task_group run 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

cancel

Es wird versucht, die Unterstruktur der Arbeit abzubrechen, die in dieser Aufgabengruppe verwurzelt ist. Alle vorgänge, die für die Vorgangsgruppe geplant sind, werden nach Möglichkeit transitiv abgebrochen.

void cancel();

Hinweise

Weitere Informationen finden Sie unter "Stornierung".

is_canceling

Informiert den Anrufer darüber, ob sich die Aufgabengruppe derzeit mitten in einer Abbruchzeit befindet. Dies weist nicht unbedingt darauf hin, dass die cancel Methode für das structured_task_group Objekt aufgerufen wurde (obwohl diese Methode sicherlich für die Rückgabe truequalifiziert). Es kann vorkommen, dass das structured_task_group Objekt inline ausgeführt wird und eine Aufgabengruppe weiter oben in der Arbeitsstruktur abgebrochen wurde. In Fällen wie diesen, in denen die Laufzeit vor dem Ablauf des Abbruchs durch dieses structured_task_group Objekt bestimmen kann, true wird 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".

run

Plant einen Vorgang für das structured_task_group Objekt. Der Aufrufer verwaltet die Lebensdauer des objekts, das task_handle _Task_handle im 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 Textkörper des Aufgabenhandle 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 sie aktiv ist, bis die Methode oder run_and_wait die 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 die structured_task_group Destruktierung als Ergebnis der Abkopplung von Stapeln von einer Ausnahme ausfällt, müssen Sie nicht garantieren, dass ein Aufruf an die wait Methode oder run_and_wait die 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 der vom _Task_handle Parameter angegebene Vorgangshandle bereits über die run Methode auf ein Aufgabengruppenobjekt geplant wurde und es keinen dazwischen liegenden Aufruf der wait Aufgabe oder run_and_wait Methode für diese Aufgabengruppe gab.

run_and_wait

Plant, dass eine Aufgabe im Aufrufkontext inline ausgeführt wird, wobei das Objekt unterstützung structured_task_group für die vollständige Abbruchunterstützung unterstützt. 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 structured_task_group am 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 Laufzeit erwartet weiterhin, dass sie 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 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 solche Ausnahme der Auswahl aus und verteilt sie aus dem Aufruf der run_and_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 run_and_wait Methode zu einem nicht definierten Verhalten führt.

Im nicht außergewöhnlichen Ausführungspfad verfügen Sie über ein Mandat, entweder diese Methode oder die wait Methode vor dem Destruktor der structured_task_group Ausgeführten aufzurufen.

structured_task_group

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 Abbruchtoken, 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 die Methode oder run_and_wait die wait Methode für das Objekt vor dem Ausführen des Destruktors aufrufen, es sei denn, der Destruktor wird aufgrund einer Ausnahme als Ergebnis der Stapelaussetzung ausgeführt.

~structured_task_group();

Hinweise

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

wait

Wartet, bis alle Arbeiten an dem structured_task_group Vorgang 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 solche Ausnahme der Auswahl aus und verteilt 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 nicht außergewöhnlichen Ausführungspfad verfügen Sie über ein Mandat, entweder diese Methode oder die run_and_wait Methode vor dem Destruktor der structured_task_group Ausgeführten aufzurufen.

Siehe auch

Concurrency-Namespace
task_group-Klasse
task_handle-Klasse