Classe structured_task_group

La classe structured_task_group rappresenta una raccolta altamente strutturata di lavoro parallelo. È possibile mettere in coda attività parallele singole a un structured_task_group usando gli oggetti task_handle, e attenderne il completamento, oppure annullare il gruppo di attività prima di aver terminato l'esecuzione, interrompendo in tal modo qualsiasi attività che non abbia avviato l'esecuzione.

Sintassi

class structured_task_group;

Membri

Costruttori pubblici

Nome	Descrizione
Structured_task_group	Con overload. Costruisce un oggetto structured_task_group nuovo.
Distruttore ~structured_task_group	Elimina un oggetto structured_task_group . È previsto chiamare il wait metodo o run_and_wait sull'oggetto prima dell'esecuzione del distruttore, a meno che il distruttore non venga eseguito in seguito alla rimozione dello stack a causa di un'eccezione.

Metodi pubblici

Nome	Descrizione
cancel	Tenta di annullare l'albero secondario del lavoro radicato in questo gruppo di attività. Se possibile, ogni attività pianificata nel gruppo di attività verrà annullata in modo transitivo.
is_canceling	Informa il chiamante se il gruppo di attività è attualmente incluso in un annullamento. Ciò non indica necessariamente che il cancel metodo è stato chiamato sull'oggetto structured_task_group (anche se tale certamente qualifica questo metodo per restituire true). È possibile che l'oggetto structured_task_group sia in esecuzione inline e che un gruppo di attività più avanti nell'albero di lavoro sia stato annullato. Nei casi come questi in cui il runtime può determinare in anticipo che l'annullamento scorrerà attraverso questo structured_task_group oggetto, true verrà restituito anche .
run	Con overload. Pianifica un'attività sull'oggetto structured_task_group . Il chiamante gestisce la durata dell'oggetto task_handle passato nel _Task_handle parametro . La versione che accetta il parametro _Placement comporta che per l'attività venga data priorità all'esecuzione nella posizione specificata da quel parametro.
run_and_wait	Con overload. Pianifica l'esecuzione di un'attività inline nel contesto chiamante con l'assistenza dell'oggetto per il supporto completo dell'annullamento structured_task_group . Se un task_handle oggetto viene passato come parametro a run_and_wait, il chiamante è responsabile della gestione della durata dell'oggetto task_handle . La funzione attende quindi che tutto il lavoro sull'oggetto structured_task_group sia stato completato o annullato.
Aspettare	Attende il completamento o l'annullamento di tutto il structured_task_group lavoro su .

Osservazioni:

Esistono diverse restrizioni severe all'utilizzo di un structured_task_group oggetto per ottenere prestazioni:

• Un singolo structured_task_group oggetto non può essere utilizzato da più thread. Tutte le operazioni su un structured_task_group oggetto devono essere eseguite dal thread che ha creato l'oggetto . Le due eccezioni a questa regola sono le funzioni cancel membro e is_canceling. L'oggetto potrebbe non trovarsi nell'elenco di acquisizione di un'espressione lambda e essere usato all'interno di un'attività, a meno che l'attività non usi una delle operazioni di annullamento.

• Tutte le attività pianificate per un structured_task_group oggetto vengono pianificate tramite l'uso di task_handle oggetti di cui è necessario gestire in modo esplicito la durata.

• Più gruppi possono essere usati solo in ordine assolutamente annidato. Se vengono dichiarati due structured_task_group oggetti, il secondo deve essere dichiarato (quello interno) deve essere distrutto prima di qualsiasi metodo tranne cancel o is_canceling viene chiamato sul primo (quello esterno). Questa condizione è vera sia nel caso in cui si dichiarano semplicemente più structured_task_group oggetti all'interno degli stessi ambiti annidati dal livello funzionale, sia nel caso di un'attività accodata all'oggetto structured_task_group tramite i run metodi o run_and_wait .

• A differenza della classe generale task_group , tutti gli stati della structured_task_group classe sono finali. Dopo aver accodato le attività nel gruppo e averne atteso il completamento, non è possibile utilizzare nuovamente lo stesso gruppo.

Per altre informazioni, vedere Parallelismo delle attività.

Gerarchia di ereditarietà

structured_task_group

Requisiti

Intestazione: ppl.h

Spazio dei nomi: Concurrency

cancel

Tenta di annullare l'albero secondario del lavoro radicato in questo gruppo di attività. Se possibile, ogni attività pianificata nel gruppo di attività verrà annullata in modo transitivo.

void cancel();

Osservazioni:

Per altre informazioni, vedere Annullamento.

is_canceling

Informa il chiamante se il gruppo di attività è attualmente incluso in un annullamento. Ciò non indica necessariamente che il cancel metodo è stato chiamato sull'oggetto structured_task_group (anche se tale certamente qualifica questo metodo per restituire true). È possibile che l'oggetto structured_task_group sia in esecuzione inline e che un gruppo di attività più avanti nell'albero di lavoro sia stato annullato. Nei casi come questi in cui il runtime può determinare in anticipo che l'annullamento scorrerà attraverso questo structured_task_group oggetto, true verrà restituito anche .

bool is_canceling();

Valore restituito

Indicazione del fatto che l'oggetto structured_task_group si trova in mezzo a un annullamento (o che sia garantito di essere a breve).

Osservazioni:

Per altre informazioni, vedere Annullamento.

run

Pianifica un'attività sull'oggetto structured_task_group . Il chiamante gestisce la durata dell'oggetto task_handle passato nel _Task_handle parametro . La versione che accetta il parametro _Placement comporta che per l'attività venga data priorità all'esecuzione nella posizione specificata da quel parametro.

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

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

Parametri

_Funzione
Tipo dell'oggetto funzione che verrà richiamato per eseguire il corpo dell'handle di attività.

_Task_handle
Handle per il lavoro pianificato. Si noti che il chiamante ha la responsabilità per la durata di questo oggetto. Il runtime continuerà a aspettarsi che sia attivo fino a quando non viene chiamato il wait metodo o run_and_wait su questo structured_task_group oggetto.

_Posizionamento
Riferimento alla posizione in cui deve essere eseguita l'attività rappresentata dal parametro _Task_handle.

Osservazioni:

Il runtime crea una copia della funzione di lavoro passata a questo metodo. Qualsiasi modifica dello stato che si verifica in un oggetto funzione passato a questo metodo non verrà visualizzata nella copia dell'oggetto funzione.

Se i structured_task_group distruttori come risultato della rimozione dello stack da un'eccezione, non è necessario garantire che sia stata effettuata una chiamata al wait metodo o run_and_wait . In questo caso, il distruttore annulla e attende il completamento dell'attività rappresentata dal _Task_handle parametro .

Genera un'eccezione invalid_multiple_scheduling se l'handle di attività specificato dal _Task_handle parametro è già stato pianificato in un oggetto gruppo di attività tramite il run metodo e non è stata eseguita alcuna chiamata al wait metodo o run_and_wait su tale gruppo di attività.

run_and_wait

Pianifica l'esecuzione di un'attività inline nel contesto chiamante con l'assistenza dell'oggetto per il supporto completo dell'annullamento structured_task_group . Se un task_handle oggetto viene passato come parametro a run_and_wait, il chiamante è responsabile della gestione della durata dell'oggetto task_handle . La funzione attende quindi che tutto il lavoro sull'oggetto structured_task_group sia stato completato o annullato.

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

Parametri

_Funzione
Tipo dell'oggetto funzione che sarà richiamato per eseguire l'attività.

_Task_handle
Handle per l'attività che verrà eseguita inline nel contesto chiamante. Si noti che il chiamante ha la responsabilità per la durata di questo oggetto. Il runtime continuerà ad aspettarsi che sia attivo fino al termine dell'esecuzione del run_and_wait metodo.

_Func
Funzione che verrà chiamata per richiamare il corpo del lavoro. Può trattarsi di un'espressione lambda o di un altro oggetto che supporta una versione dell'operatore di chiamata di funzione con la firma void operator()().

Valore restituito

Indica se l'attesa è stata soddisfatta o se il gruppo di attività è stato annullato, a causa di un'operazione di annullamento esplicita o di un'eccezione generata da una delle attività. Per altre informazioni, vedere task_group_status

Osservazioni:

Si noti che una o più delle attività pianificate per questo structured_task_group oggetto possono essere eseguite inline nel contesto chiamante.

Se una o più delle attività pianificate per questo structured_task_group oggetto generano un'eccezione, il runtime selezionerà un'eccezione di questo tipo dalla scelta e la propaga all'esterno della chiamata al run_and_wait metodo .

Dopo la restituzione da parte di questa funzione, lo stato dell'oggetto structured_task_group viene considerato finale e non deve essere utilizzato. Si noti che l'utilizzo dopo la restituzione del run_and_wait metodo comporterà un comportamento non definito.

Nel percorso di esecuzione non eccezionale è necessario chiamare questo metodo o il wait metodo prima del distruttore dell'esecuzione structured_task_group .

Structured_task_group

Costruisce un oggetto structured_task_group nuovo.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Parametri

_Cancellationtoken
Token di annullamento da associare a questo gruppo di attività strutturato. Il gruppo di attività strutturato verrà annullato quando il token viene annullato.

Osservazioni:

Tramite il costruttore che accetta un token di annullamento viene creato un oggetto structured_task_group che verrà annullato quando l'origine associata al token viene annullata. Se si specifica un token di annullamento esplicito, questo gruppo di attività strutturato viene inoltre isolato dalla partecipazione a un annullamento implicito da un gruppo padre con un token diverso o nessun token.

~Structured_task_group

Elimina un oggetto structured_task_group . È previsto chiamare il wait metodo o run_and_wait sull'oggetto prima dell'esecuzione del distruttore, a meno che il distruttore non venga eseguito in seguito alla rimozione dello stack a causa di un'eccezione.

~structured_task_group();

Osservazioni:

Se il distruttore viene eseguito come risultato della normale esecuzione (ad esempio, non rimozione dello stack a causa di un'eccezione) e nessuno dei wait metodi né run_and_wait è stato chiamato, il distruttore può generare un'eccezione missing_wait .

wait

Attende il completamento o l'annullamento di tutto il structured_task_group lavoro su .

task_group_status wait();

Valore restituito

Indica se l'attesa è stata soddisfatta o se il gruppo di attività è stato annullato, a causa di un'operazione di annullamento esplicita o di un'eccezione generata da una delle attività. Per altre informazioni, vedere task_group_status

Osservazioni:

Si noti che una o più delle attività pianificate per questo structured_task_group oggetto possono essere eseguite inline nel contesto chiamante.

Se una o più delle attività pianificate per questo structured_task_group oggetto generano un'eccezione, il runtime selezionerà un'eccezione di questo tipo dalla scelta e la propaga all'esterno della chiamata al wait metodo .

Dopo la restituzione da parte di questa funzione, lo stato dell'oggetto structured_task_group viene considerato finale e non deve essere utilizzato. Si noti che l'utilizzo dopo la restituzione del wait metodo comporterà un comportamento non definito.

Nel percorso di esecuzione non eccezionale è necessario chiamare questo metodo o il run_and_wait metodo prima del distruttore dell'esecuzione structured_task_group .

Vedi anche

Spazio dei nomi concurrency
Classe task_group
Classe task_handle