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

Nome	Descrição
task_group	Sobrecarregado. Constrói um novo objeto task_group.
Destruidor ~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.

Métodos públicos

Nome	Descrição
cancel	Tenta ao máximo cancelar a subárvore do trabalho com raiz nesse grupo de tarefas. Toda tarefa agendada no grupo de tarefas será cancelada transitivamente, se possível.
is_canceling	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 esses em que o runtime pode determinar antecipadamente que o cancelamento fluirá por esse objeto task_group, true também será retornado.
run	Sobrecarregado. 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.
run_and_wait	Sobrecarregado. 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.
wait	A função aguarda até que todo o trabalho no objeto task_group tenha sido concluído ou cancelado.

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 maneiras livres. 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: concurrency

cancel

Tenta ao máximo cancelar a subárvore do trabalho com raiz nesse 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.

is_canceling

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 esses em que o runtime pode determinar antecipadamente que o cancelamento fluirá por esse objeto task_group, true também será retornado.

bool is_canceling();

Valor de Devolução

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.

run

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 identificador de tarefa.

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

_Placement
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 ele viva 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 se destruir como resultado do desenrolamento da pilha de uma exceção, você não precisará garantir que uma chamada tenha sido feita para o método wait ou run_and_wait. Nesse caso, o destruidor cancelará e aguardará a conclusão da tarefa representada pelo parâmetro _Task_handle.

O método gera 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 intervindo 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 runtime continuará esperando que ele viva até que o método run_and_wait conclua a execução.

_Func
Uma função que será chamada para invocar o corpo do trabalho. Isso pode ser um exceção lambda ou outro objeto que dá suporte a uma versão do operador de chamada de função com a assinatura void operator()().

Valor de Devolução

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

task_group

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 quando o token for cancelado.

Comentários

O construtor que usa um token de cancelamento cria um task_group que será cancelado quando a fonte 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 destruidor for executado como resultado da execução normal (por exemplo, não desenrolar a pilha devido a uma exceção) e os métodos wait ou run_and_wait não tiverem sido chamados, o destruidor poderá gerar uma exceção missing_wait.

wait

A função aguarda até que todo o trabalho no objeto task_group tenha sido concluído ou cancelado.

task_group_status wait();

Valor de Devolução

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 um mandato para chamar esse método ou o método run_and_wait antes que o destruidor do task_group seja executado.

Confira também

Namespace de simultaneidade
Classe structured_task_group
Classe task_handle