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

Metodi pubblici

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 membro cancel 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.

• Molti gruppi possono essere utilizzati solo in ordine completamente annidato. Se vengono dichiarati due oggetti structured_task_group, il secondo oggetto dichiarato (quello interno) deve essere distrutto prima che qualsiasi metodo, tranne cancel o is_canceling, sia chiamato sul primo oggetto (quello esterno). Questa condizione vale sia nel caso in cui si dichiarano semplicemente più structured_task_group oggetti all'interno di ambiti annidati funzionalmente, sia nel caso di un'attività messa in coda all'oggetto structured_task_group tramite i metodi run 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

annulla

Fa il massimo sforzo per annullare il sottogruppo di attività radicato in questo gruppo di lavoro. Se possibile, ogni attività pianificata nel gruppo di attività verrà annullata in modo transitivo.

void cancel();

Osservazioni:

Per altre informazioni, vedere Annullamento.

sta annullando

Informa l'utente chiamante se il gruppo di attività è attualmente nel corso di 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 oggetto structured_task_group, anche true verrà restituito.

bool is_canceling();

Valore restituito

Indicazione del fatto che l'oggetto structured_task_group si trova in fase di annullamento (o lo sarà presto con certezza).

Osservazioni:

Per altre informazioni, vedere Annullamento.

eseguire

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
Un riferimento all'attività in programmazione. Si noti che il chiamante ha la responsabilità per la durata di questo oggetto. Il runtime continuerà ad aspettarsi che rimanga attivo fino a quando non viene chiamato il metodo wait o il metodo run_and_wait su questo oggetto structured_task_group.

_Collocamento
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 il structured_task_group viene distrutto a causa dello smantellamento dello stack di un'eccezione, non è necessario garantire che sia stata effettuata una chiamata al metodo wait o al run_and_wait. In questo caso, il distruttore interromperà e attenderà correttamente il completamento dell'attività rappresentata dal parametro _Task_handle.

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

esegui_e_attendi

Pianifica un'attività da eseguire direttamente nel contesto chiamante con l'assistenza dell'oggetto structured_task_group per il pieno supporto dell'annullamento. 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 in linea nel contesto chiamante. Si noti che il chiamante ha la responsabilità per la durata di questo oggetto. Il runtime continuerà a prevedere che rimanga attivo fino al termine dell'esecuzione del metodo run_and_wait.

_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 in linea nel contesto chiamante.

Se una o più delle attività pianificate per questo structured_task_group oggetto generano un'eccezione, il runtime selezionerà una di queste eccezioni e la propagherà al di fuori della chiamata al metodo run_and_wait.

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 metodo wait prima che il distruttore di structured_task_group venga eseguito.

gruppo_task_strutturato

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 strutturato di attività. Il gruppo di attività strutturato verrà annullato quando il token viene annullato.

Osservazioni:

Il costruttore che accetta un token di annullamento crea 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 strutturato di attività viene inoltre isolato dal coinvolgimento in un annullamento implicito dal gruppo padre con un token diverso o nessun token.

~gruppo_di_compiti_structurati

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 a seguito della normale esecuzione (ad esempio, non disallocazione dello stack a causa di un'eccezione) e né il metodo wait né il metodo run_and_wait è stato chiamato, il distruttore può generare un'eccezione missing_wait.

attendere

Attende fino al completamento o all'annullamento di tutto il lavoro su structured_task_group.

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 in linea nel contesto chiamante.

Se una o più delle attività pianificate per questo structured_task_group oggetto generano un'eccezione, il runtime selezionerà una di queste eccezioni e la propagherà al di fuori della chiamata al metodo wait.

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 metodo run_and_wait prima che il distruttore di structured_task_group venga eseguito.

Vedi anche

Spazio dei nomi concorrenza
Classe task_group
Classe task_handle