Classe task_group

A classe task_group representa uma coleção de trabalhos paralelos que podem ser aguardados ou cancelados.

Sintaxe

class task_group;

Membros

Construtores públicos

Métodos públicos

Comentários

Ao contrário da classe fortemente restrita structured_task_group, a classe task_group é muito mais geral. Ele não tem nenhuma das restrições descritas pelo structured_task_group. Os objetos task_group podem ser usados com segurança entre threads e utilizados de forma livre. A desvantagem do constructo task_group é que ele pode não funcionar tão bem quanto o constructo structured_task_group para tarefas que executam pequenas quantidades de trabalho.

Para saber mais, confira Paralelismo da tarefa.

Hierarquia de herança

task_group

Requisitos

Cabeçalho: ppl.h

Namespace: simultaneidade

cancelar

Fazendo o máximo para cancelar a subárvore de trabalho ancorada neste grupo de tarefas. Toda tarefa agendada no grupo de tarefas será cancelada transitivamente, se possível.

void cancel();

Comentários

Para obter mais informações, consulte Cancelamento.

está cancelando

Informa ao chamador se o grupo de tarefas está no meio de um cancelamento. Isso não indica necessariamente que o método cancel foi chamado no objeto task_group (embora isso certamente qualifique esse método a retornar true). Pode ser o caso de o objeto task_group estar executando em linha e um grupo de tarefas mais acima na árvore de trabalho foi cancelado. Em casos como este, onde o runtime pode determinar antecipadamente que o cancelamento fluirá através deste objeto task_group, true também será retornado.

bool is_canceling();

Valor de retorno

Uma indicação de se o objeto task_group está no meio de um cancelamento (ou se é garantido que esteja em breve).

Comentários

Para obter mais informações, consulte Cancelamento.

execução

Agenda uma tarefa no objeto task_group. Se um objeto task_handle for passado como um parâmetro para run, o chamador será responsável por gerenciar o tempo de vida do objeto task_handle. A versão do método que usa uma referência a um objeto de função como parâmetro envolve a alocação de heap dentro do runtime que pode ter um desempenho menor do que usar a versão que usa uma referência a um objeto task_handle. A versão que usa o parâmetro _Placement faz com que a tarefa seja desviada para execução no local especificado por esse parâmetro.

template<
   typename _Function
>
void run(
   const _Function& _Func
);

template<
   typename _Function
>
void run(
   const _Function& _Func,
   location& _Placement
);

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

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

Parâmetros

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

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

_Posicionamento
Uma referência ao local em que a tarefa representada pelo parâmetro _Func deve ser executada.

_Task_handle
Um identificador para o trabalho que está sendo agendado. Observe que o chamador é responsável pelo tempo de vida deste objeto. O runtime continuará a esperar que permaneça ativo até que o método wait ou run_and_wait tenha sido chamado neste objeto task_group.

Comentários

O runtime agenda a função de trabalho fornecida para ser executada posteriormente, o que pode ser após o retorno da função de chamada. Esse método usa um objeto task_handle para manter uma cópia da função de trabalho fornecida. Dessa maneira, todas as alterações de estado que ocorrem em um objeto de função que você passa para esse método não aparecerão na cópia desse objeto de função. Além disso, certifique-se de que o tempo de vida de todos os objetos que você passa por ponteiro ou por referência à função de trabalho permaneça válido até que a função de trabalho retorne.

Se o task_group for destruído como resultado do desempilhamento da pilha devido a uma exceção, não é necessário garantir que uma chamada tenha sido feita para o método wait ou run_and_wait. Nesse caso, o destrutor cancelará a tarefa e aguardará pela conclusão da tarefa representada pelo parâmetro _Task_handle.

O método lança uma exceção invalid_multiple_scheduling se o identificador de tarefa fornecido pelo parâmetro _Task_handle já tiver sido agendado em um objeto de grupo de tarefas por meio do método run e não houver nenhuma chamada intermediária para o método wait ou run_and_wait nesse grupo de tarefas.

run_and_wait

Agenda uma tarefa a ser executada em linha no contexto de chamada com a assistência do objeto task_group para suporte completo ao cancelamento. Em seguida, a função aguarda até que todo o trabalho no objeto task_group tenha sido concluído ou cancelado. Se um objeto task_handle for passado como um parâmetro para run_and_wait, o chamador será responsável por gerenciar o tempo de vida do objeto task_handle.

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 o corpo da tarefa.

_Task_handle
Um identificador da tarefa que será executada em linha no contexto de chamada. Observe que o chamador é responsável pelo tempo de vida deste objeto. O tempo de execução continuará esperando que ele permaneça ativo até que o método run_and_wait finalize a execução.

_Func
Uma função que será chamada para invocar o corpo do trabalho. Isso pode ser uma expressão 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 atendida ou se o grupo de tarefas foi cancelado, devido a uma operação de cancelamento explícita ou a uma exceção lançada por uma de suas tarefas. Para saber mais, consulte task_group_status.

Comentários

Observe que uma ou mais das tarefas agendadas para esse objeto task_group podem ser executadas em linha no contexto de chamada.

Se uma ou mais das tarefas agendadas para esse objeto task_group gerar uma exceção, o runtime selecionará uma dessas exceções e a propagará da chamada para o método run_and_wait.

Após o retorno do método run_and_wait em um objeto task_group, o runtime redefine o objeto para um estado limpo em que ele pode ser reutilizado. Isso inclui o caso em que o objeto task_group foi cancelado.

No caminho não excepcional de execução, você tem um mandato para chamar esse método ou o método wait antes que o destruidor do task_group seja executado.

grupo_de_tarefas

Constrói um novo objeto task_group.

task_group();

task_group(
   cancellation_token _CancellationToken
);

Parâmetros

_CancellationToken
Um token de cancelamento a ser associado a esse grupo de tarefas. O grupo de tarefas será cancelado assim que o token for cancelado.

Comentários

O construtor que recebe um token de cancelamento cria um task_group que será cancelado quando a origem associada ao token for cancelada. Fornecer um token de cancelamento explícito também impede esse grupo de tarefas de participar de um cancelamento implícito de um grupo pai com um token diferente ou nenhum token.

~ task_group

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

~task_group();

Comentários

Se o destrutor for executado como resultado de uma execução normal (e não de um desenrolar de pilha devido a uma exceção) e os métodos wait ou run_and_wait não tiverem sido chamados, o destrutor poderá gerar uma exceção missing_wait.

aguarde

Aguarda até que todo o trabalho no objeto task_group seja concluído ou cancelado.

task_group_status wait();

Valor de retorno

Uma indicação de se a espera foi atendida ou se o grupo de tarefas foi cancelado devido a uma operação de cancelamento explícita ou uma exceção sendo lançada de uma das tarefas. Para saber mais, consulte task_group_status.

Comentários

Observe que uma ou mais das tarefas agendadas para esse objeto task_group podem ser executadas em linha no contexto de chamada.

Se uma ou mais das tarefas agendadas para esse objeto task_group gerar uma exceção, o runtime selecionará uma dessas exceções e a propagará da chamada para o método wait.

Chamar wait em um objeto task_group redefine para um estado limpo em que ele pode ser reutilizado. Isso inclui o caso em que o objeto task_group foi cancelado.

No caminho não excepcional de execução, você tem a obrigação de chamar este método ou o método run_and_wait antes que o destruidor do task_group seja executado.

Confira também

Namespace de concorrência
Classe structured_task_group
Classe task_handle