structured_task_group Classe

A structured_task_group classe representa uma coleção altamente estruturada de tarefas paralelas. Pode colocar em fila tarefas paralelas individuais para um structured_task_group usando objetos task_handle, esperar que sejam concluídas, ou cancelar o grupo de tarefas antes de concluírem a execução, o que abortará quaisquer tarefas que ainda não tenham começado.

Sintaxe

class structured_task_group;

Membros

Construtores Públicos

Métodos Públicos

Observações

Existem várias restrições severas impostas ao uso de um structured_task_group objeto para obter desempenho:

• Um único structured_task_group objeto não pode ser usado por múltiplos threads. Todas as operações sobre um structured_task_group objeto devem ser realizadas pelo thread que criou o objeto. As duas exceções a esta regra são as funções membros cancel e is_canceling. O objeto não pode estar na lista de captura de uma expressão lambda e ser usado dentro de uma tarefa, a menos que a tarefa utilize uma das operações de cancelamento.

• Todas as tarefas agendadas para um structured_task_group objeto são agendadas através do uso de task_handle objetos cujo tempo de vida deve ser gerido explicitamente.

• Múltiplos grupos só podem ser usados por ordem absolutamente aninhada. Se dois structured_task_group objetos forem declarados, o segundo, o interior, deve ser destruído antes que qualquer método, exceto cancel ou is_canceling, seja chamado no primeiro, o exterior. Esta condição é válida tanto no caso de simplesmente declarar múltiplos structured_task_group objetos dentro do mesmo escopo ou em escopos aninhados funcionalmente, como no caso de uma tarefa que foi enfileirada para o structured_task_group através dos métodos run ou run_and_wait.

• Ao contrário da turma geral task_group , todos os estados da structured_task_group turma são finais. Depois de colocares tarefas na fila para o grupo e esperares que fossem concluídas, podes não voltar a usar o mesmo grupo.

Para obter mais informações, consulte paralelismo de tarefas.

Hierarquia de herança

structured_task_group

Requerimentos

Cabeçalho: ppl.h

Namespace: simultaneidade

cancel

Faz um esforço para cancelar a subárvore de trabalho enraizada neste grupo de tarefas. Cada tarefa agendada no grupo de tarefas será cancelada de forma transitiva, se possível.

void cancel();

Observações

Para obter mais informações, consulte Cancelamento.

está_cancelando

Informa o interlocutor se o grupo de tarefa está ou não em processo de cancelamento. Isto não indica necessariamente que o cancel método tenha sido chamado ao structured_task_group objeto (embora isso certamente qualifique este método para devolver true). Pode acontecer que o structured_task_group objeto esteja a executar em linha direta e um grupo de tarefas mais adiante na árvore de trabalho tenha sido cancelado. Em casos como estes, em que o tempo de execução pode determinar antecipadamente que o cancelamento fluirá através deste structured_task_group objeto, true também será devolvido.

bool is_canceling();

Valor de retorno

Uma indicação sobre se o structured_task_group objeto está em processo de cancelamento (ou se é garantido que estará em breve).

Observações

Para obter mais informações, consulte Cancelamento.

execução

Agenda uma tarefa no structured_task_group objeto. O chamador gere a vida útil do task_handle objeto passado no _Task_handle parâmetro. A versão que utiliza o parâmetro _Placement faz com que a tarefa seja enviesada para a execução no local especificado por esse parâmetro.

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

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

Parâmetros

_Function
O tipo do objeto de função que será chamado para executar o corpo do processo da tarefa.

_Task_handle
Um controlo para o trabalho a ser agendado. Note-se que o chamador é responsável pela vida útil deste objeto. O tempo de execução continuará a esperar que exista até que o método wait ou run_and_wait seja chamado no objeto structured_task_group.

_Posicionamento
Uma referência ao local onde a tarefa representada pelo _Task_handle parâmetro deve ser executada.

Observações

O ambiente de execução cria uma cópia da função de trabalho que é passada para este método. Quaisquer alterações de estado que ocorram num objeto função que passes para este método não aparecerão na tua cópia desse objeto função.

Se o método structured_task_group se autodestrói como resultado do desenrolamento da pilha a partir de uma exceção, não precisa de garantir que foi feita uma chamada para os métodos wait ou run_and_wait. Neste caso, o destruidor irá apropriadamente cancelar e esperar que a tarefa representada pelo _Task_handle parâmetro seja concluída.

Lança uma exceção invalid_multiple_scheduling se o identificador da tarefa dado pelo parâmetro _Task_handle já tiver sido agendado num objeto do grupo de tarefas pelo método run e não tiver havido nenhuma chamada intermédia para o método wait ou run_and_wait nesse grupo de tarefas.

executar_e_esperar

Agenda uma tarefa para ser executada em linha no contexto de chamada com a ajuda do structured_task_group objeto para suporte total de cancelamento. Se um task_handle objeto for passado como parâmetro para run_and_wait, o chamador é responsável por gerir a vida útil do task_handle objeto. A função espera então até que todo o trabalho no structured_task_group objeto seja concluído ou cancelado.

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

Parâmetros

_Function
O tipo do objeto de função que será invocado para executar a tarefa.

_Task_handle
Um handle para a tarefa que será executado diretamente no contexto de invocação. Note-se que o chamador é responsável pela vida útil deste objeto. O tempo de execução continuará a esperar que dure até o run_and_wait método terminar a execução.

_Func
Uma função que será chamada para invocar o corpo da obra. Isto pode ser um lambda ou outro objeto que suporta uma versão do operador de chamada de função com a assinatura void operator()().

Valor de retorno

Uma indicação de se a espera foi cumprida ou se o grupo de tarefas foi cancelado, devido a uma operação explícita de cancelamento ou a uma exceção lançada por uma das suas tarefas. Para mais informações, consulte task_group_status

Observações

Note que uma ou mais das tarefas agendadas para este structured_task_group objeto podem ser executadas inline no contexto de chamada.

Se uma ou mais das tarefas agendadas para este structured_task_group objeto lançarem uma exceção, o runtime selecionará uma dessas exceções à sua escolha e propagará essa exceção para fora da chamada para o run_and_wait método.

Depois de esta função regressar, o structured_task_group objeto é considerado num estado final e não deve ser usado. Note que a utilização após o retorno do run_and_wait método resultará num comportamento indefinido.

No caminho de execução não excecional, tens a obrigação de chamar este método ou o método wait antes de o destruidor de structured_task_group ser executado.

grupo_de_tarefas_estruturadas

Constrói um novo structured_task_group objeto.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Parâmetros

_CancellationToken
Um token de cancelamento para associar a este grupo de tarefas estruturado. O grupo de tarefas estruturado será cancelado quando o token for cancelado.

Observações

O construtor que recebe um token de cancelamento cria um structured_task_group que será cancelado quando a fonte associada ao token for cancelada. Fornecer um token de cancelamento explícito também isola este grupo de tarefas estruturadas de participar num cancelamento implícito de um grupo pai com um token diferente ou sem token.

~grupo_estruturado_de_tarefas

Destrói um structured_task_group objeto. Espera-se que chamem o método wait ou run_and_wait no objeto antes da execução do destruidor, a menos que o destruidor esteja a ser executado como resultado do desenrolamento da pilha devido a uma exceção.

~structured_task_group();

Observações

Se o destruidor for executado como resultado da execução normal (por exemplo, não do desenrolamento da pilha devido a uma exceção) e nem o método wait nem run_and_wait tiverem sido chamados, o destruidor pode lançar uma exceção missing_wait .

wait

Espera até que todo o trabalho no structured_task_group esteja concluído ou seja cancelado.

task_group_status wait();

Valor de retorno

Uma indicação de se a espera foi cumprida ou se o grupo de tarefas foi cancelado, devido a uma operação explícita de cancelamento ou a uma exceção lançada por uma das suas tarefas. Para mais informações, consulte task_group_status

Observações

Note que uma ou mais das tarefas agendadas para este structured_task_group objeto podem ser executadas inline no contexto de chamada.

Se uma ou mais das tarefas agendadas para este structured_task_group objeto lançarem uma exceção, o runtime selecionará uma dessas exceções à sua escolha e propagará essa exceção para fora da chamada para o wait método.

Depois de esta função regressar, o structured_task_group objeto é considerado num estado final e não deve ser usado. Note que a utilização após o retorno do wait método resultará num comportamento indefinido.

No caminho de execução não excecional, tens a obrigação de chamar este método ou o método run_and_wait antes de o destruidor de structured_task_group ser executado.

Consulte também

concorrência Namespace
task_group Classe
task_handle Classe