structured_task_group třída

Třída structured_task_group představuje vysoce strukturovanou kolekci paralelní práce. Jednotlivé paralelní úkoly můžete zařadit do fronty k structured_task_group pomocí task_handle objektů a buď čekat na jejich dokončení, nebo zrušit skupinu úloh dříve, než začnou provádění, což přeruší všechny úkoly, které ještě nebyly spuštěny.

Syntaxe

class structured_task_group;

Členové

Veřejné konstruktory

Název	Popis
strukturovaná_skupina_úloh	Přetíženo. Vytvoří nový structured_task_group objekt.
~structured_task_group Destruktor	structured_task_group Zničí objekt. Očekává se, že zavoláte buď metodu wait, nebo metodu run_and_wait nejprve před spuštěním destruktoru, pokud se destruktor nespouští jako výsledek zpětného rozbalování zásobníku kvůli výjimce.

Veřejné metody

Název	Popis
zrušit	Vynakládá maximální úsilí ke zrušení dílčího stromu práce, který vychází z této skupiny úloh. Pokud je to možné, zruší se každý úkol naplánovaný ve skupině úloh.
ruší_se	Informuje volajícího, zda je úkolová skupina právě uprostřed rušení. To nemusí nutně znamenat, že cancel metoda byla volána na structured_task_group objekt (ačkoli to jistě kvalifikuje tuto metodu k vrácení true). Může nastat situace, kdy je objekt structured_task_group spouštěn inline a skupina úloh dále v stromu úloh byla zrušena. V případech, kdy může modul runtime předem určit, že zrušení proběhne skrze tento structured_task_group objekt, se vrátí také true.
Spusťte	Přetíženo. Naplánuje úkol na objektu structured_task_group . Volající spravuje životnost objektu task_handle předaného v parametru _Task_handle . Verze, která přebírá parametr _Placement, upřednostňuje spuštění úlohy na místě určeném tímto parametrem.
run_and_wait	Přetíženo. Naplánuje úlohu tak, aby byla spuštěna přímo v aktuálním kontextu volání s pomocí objektu structured_task_group pro plnou podporu zrušení. task_handle Pokud je objekt předán jako parametr run_and_wait, volající je zodpovědný za správu životnosti objektutask_handle. Funkce pak počká, dokud není veškerá práce na objektu structured_task_group dokončena nebo zrušena.
Počkej	Čeká, až bude veškerá práce na structured_task_group dokončena nebo zrušena.

Poznámky

Pro získání výkonu existuje řada závažných omezení použití objektu structured_task_group :

• Jeden structured_task_group objekt nemůže používat více vláken. Všechny operace s objektem structured_task_group musí provádět vlákno, které objekt vytvořilo. Dvě výjimky tohoto pravidla jsou členské funkce cancel a is_canceling. Objekt nemusí být v seznamu zachycovaných prvků lambda výrazu a může být použit během úkolu pouze tehdy, pokud úkol využívá některou z operací zrušení.

• Všechny úkoly naplánované na structured_task_group objekt jsou naplánovány prostřednictvím task_handle objektů, u nichž musíte jejich životnost explicitně spravovat.

• Více skupin lze použít pouze v naprosto vnořeném pořadí. Pokud jsou deklarovány dva structured_task_group objekty, druhý objekt (vnitřní) musí být zdestruován dříve, než je na první (vnější) objekt zavolána jakákoli metoda kromě cancel nebo is_canceling. Tato podmínka platí jak v případě, kdy jednoduše deklarujete více structured_task_group objektů ve stejném nebo funkčně vnořeném oboru, tak v případě úlohy, která byla do fronty structured_task_group zařazena prostřednictvím metod run nebo run_and_wait.

• Na rozdíl od obecné task_group třídy jsou všechny stavy ve structured_task_group třídě konečné. Jakmile do skupiny zařadíte úkoly do fronty a počkáte na jejich dokončení, nesmíte stejnou skupinu znovu používat.

Další informace naleznete v Paralelismu úkolů.

Hierarchie dědičnosti

structured_task_group

Požadavky

Hlavička: ppl.h

Obor názvů: souběžnost

zrušit

Vynakládá maximální úsilí ke zrušení dílčího stromu práce, který vychází z této skupiny úloh. Pokud je to možné, zruší se každý úkol naplánovaný ve skupině úloh.

void cancel();

Poznámky

Další informace najdete v tématu Zrušení.

ruší se

Informuje volajícího, zda je úkolová skupina právě uprostřed rušení. To nemusí nutně znamenat, že cancel metoda byla volána na structured_task_group objekt (ačkoli to jistě kvalifikuje tuto metodu k vrácení true). Může nastat situace, kdy je objekt structured_task_group spouštěn inline a skupina úloh dále v stromu úloh byla zrušena. V případech, kdy může modul runtime předem určit, že zrušení proběhne skrze tento structured_task_group objekt, se vrátí také true.

bool is_canceling();

Návratová hodnota

Označení, zda je objekt structured_task_group uprostřed probíhajícího zrušení (nebo je zaručeno, že brzy bude).

Poznámky

Další informace najdete v tématu Zrušení.

provozovat

Naplánuje úkol na objektu structured_task_group . Volající spravuje životnost objektu task_handle předaného v parametru _Task_handle . Verze, která přebírá parametr _Placement, upřednostňuje spuštění úlohy na místě určeném tímto parametrem.

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

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

Parametry

_Funkce
Typ objektu funkce, který bude vyvolán ke spuštění těla úkolu.

_Task_handle
Identifikátor práce, která je plánována Všimněte si, že volající zodpovídá za životnost tohoto objektu. Prostředí runtime bude nadále očekávat, že objekt structured_task_group bude existovat, dokud není zavolána metoda wait nebo run_and_wait na tomto objektu.

_Umístění
Odkaz na umístění, kde by se měl provést úkol reprezentovaný parametrem _Task_handle .

Poznámky

Modul runtime vytvoří kopii pracovní funkce, kterou předáte této metodě. Všechny změny stavu, ke kterým dochází v objektu funkce, který předáte této metodě, se nezobrazí ve vaší kopii tohoto objektu funkce.

Pokud dojde k destrukci jako výsledek odvíjení zásobníku z výjimky, nemusíte zaručit, že bylo provedeno volání buď na metodu wait, nebo na metodu run_and_wait. V tomto případě destruktor odpovídajícím způsobem zruší a počká na dokončení úlohy reprezentované parametrem _Task_handle .

Vyvolá výjimku invalid_multiple_scheduling v případě, že popisovač úkolu zadaný parametrem _Task_handle již byl naplánován na objekt skupiny úloh prostřednictvím metody run, aniž by došlo k volání metody wait nebo run_and_wait v této skupině úloh.

run_and_wait

Naplánuje úlohu tak, aby byla spuštěna přímo v aktuálním kontextu volání s pomocí objektu structured_task_group pro plnou podporu zrušení. task_handle Pokud je objekt předán jako parametr run_and_wait, volající je zodpovědný za správu životnosti objektutask_handle. Funkce pak počká, dokud není veškerá práce na objektu structured_task_group dokončena nebo zrušena.

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);

Parametry

_Funkce
Typ objektu funkce, který bude vyvolán ke spuštění úkolu.

_Task_handle
Identifikátor úlohy, která se spustí přímo v aktuálním kontextu volání. Všimněte si, že volající zodpovídá za životnost tohoto objektu. Modul runtime bude i nadále očekávat, že zůstane aktivní, dokud metoda run_and_wait nedokončí provádění.

_Func
Funkce, která bude volána k provádění hlavní části úkolu. Může se jednat o lambda nebo jiný objekt, který podporuje verzi operátoru volání funkce s podpisem void operator()().

Návratová hodnota

Označení, jestli bylo čekání splněné nebo jestli byla skupina úloh zrušena, a to buď kvůli explicitní operaci zrušení, nebo výjimce z některého z jejích úkolů. Další informace najdete v tématu task_group_status

Poznámky

Všimněte si, že jeden nebo více úkolů naplánovaných na tento structured_task_group objekt může ve volajícím kontextu běžet inline.

Pokud jeden nebo více úkolů naplánovaných pro tento structured_task_group objekt vyvolá výjimku, modul runtime vybere jednu takovou výjimku z výběru a rozšíří ji mimo volání metody run_and_wait .

Po vrácení structured_task_group této funkce se objekt považuje za konečný a neměl by být použit. Všimněte si, že využití po vrácení metody run_and_wait povede k nedefinovanému chování.

V ne-výjimečné cestě provádění máte povinnost volat buď tuto metodu, nebo metodu wait před spuštěním destruktoru structured_task_group.

strukturovaná_skupina_úkolů

Vytvoří nový structured_task_group objekt.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Parametry

_CancellationToken
Token pro zrušení, který se má přidružit k této strukturované skupině úloh. Při zrušení tokenu se zruší strukturovaná skupina úloh.

Poznámky

Konstruktor, který přebírá token zrušení, vytvoří structured_task_group , který bude zrušen při zrušení zdroje přidruženého k tokenu. Poskytnutí explicitního cancellation tokenu také chrání tuto strukturovanou skupinu úloh před zahájením implicitního zrušení z nadřazené skupiny s jiným tokenem nebo bez tokenu.

~strukturovaná_skupina_úkolů

structured_task_group Zničí objekt. Očekává se, že zavoláte buď metodu wait, nebo metodu run_and_wait nejprve před spuštěním destruktoru, pokud se destruktor nespouští jako výsledek zpětného rozbalování zásobníku kvůli výjimce.

~structured_task_group();

Poznámky

Pokud se destruktor spustí jako výsledek běhu programu (například bez odvíjení zásobníku kvůli výjimce) a metody wait ani run_and_wait nebyly volány, destruktor může vyhodit missing_wait výjimku.

počkejte

Čeká, až bude veškerá práce na structured_task_group dokončena nebo zrušena.

task_group_status wait();

Návratová hodnota

Označení, jestli bylo čekání splněné nebo jestli byla skupina úloh zrušena, a to buď kvůli explicitní operaci zrušení, nebo výjimce z některého z jejích úkolů. Další informace najdete v tématu task_group_status

Poznámky

Všimněte si, že jeden nebo více úkolů naplánovaných na tento structured_task_group objekt může ve volajícím kontextu běžet inline.

Pokud jeden nebo více úkolů naplánovaných pro tento structured_task_group objekt vyvolá výjimku, modul runtime vybere jednu takovou výjimku z výběru a rozšíří ji mimo volání metody wait .

Po vrácení structured_task_group této funkce se objekt považuje za konečný a neměl by být použit. Upozorňujeme, že použití po vrácení metody wait povede k nedefinovanému chování.

V ne-výjimečné cestě provádění máte povinnost volat buď tuto metodu, nebo metodu run_and_wait před spuštěním destruktoru structured_task_group.

Viz také

concurrency – obor názvů
třída task_group
Třída task_handle