Classe structured_task_group

A classe structured_task_group representa uma coleção altamente estruturada de trabalho paralelo. Você pode enfileirar tarefas paralelas individuais para um structured_task_group usando objetos task_handle e aguardar a conclusão deles ou cancelar o grupo de tarefas antes que eles terminem de executar, o que anulará todas as tarefas que não iniciaram a execução.

Sintaxe

class structured_task_group;

Membros

Construtores públicos

Nome	Descrição
structured_task_group	Sobrecarregado. Constrói um novo objeto structured_task_group.
Destruidor ~structured_task_group	Destrói um objeto structured_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 structured_task_group (embora isso certamente qualifique esse método a retornar true). Pode ser o caso de o objeto structured_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 structured_task_group, true também será retornado.
run	Sobrecarregado. Agenda uma tarefa no objeto structured_task_group. O chamador gerencia o tempo de vida do objeto task_handle passado no parâmetro _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 structured_task_group para suporte completo ao cancelamento. 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. Em seguida, a função aguarda até que todo o trabalho no objeto structured_task_group tenha sido concluído ou cancelado.
wait	Aguarda até que todo o trabalho no structured_task_group tenha sido concluído ou seja cancelado.

Comentários

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

• Um único objeto structured_task_group não pode ser usado por vários threads. Todas as operações em um objeto structured_task_group devem ser executadas pelo thread que criou o objeto. As duas exceções a essa regra são as funções membro cancel e is_canceling. O objeto pode não estar na lista de captura de uma expressão lambda e ser usado dentro de uma tarefa, a menos que a tarefa esteja usando uma das operações de cancelamento.

• Todas as tarefas agendadas para um objeto structured_task_group são agendadas por meio do uso de objetos task_handle dos quais você deve gerenciar explicitamente o tempo de vida.

• Vários grupos só podem ser usados em ordem completamente aninhada. Se dois objetos structured_task_group forem declarados, o segundo sendo declarado (o interno) deverá se destruir antes de qualquer método, exceto se cancel ou is_canceling for chamado no primeiro (o externo). Essa condição se mantém verdadeira no caso de simplesmente declarar vários objetos structured_task_group dentro dos mesmos escopos ou funcionalmente aninhados, bem como no caso de uma tarefa que foi enfileirada para o structured_task_group por meio dos métodos run ou run_and_wait.

• Ao contrário da classe geral task_group, todos os estados da classe structured_task_group são finais. Depois de enfileirar tarefas no grupo e esperar que elas sejam concluídas, talvez você não use o mesmo grupo novamente.

Para saber mais, confira Paralelismo da tarefa.

Hierarquia de herança

structured_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 structured_task_group (embora isso certamente qualifique esse método a retornar true). Pode ser o caso de o objeto structured_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 structured_task_group, true também será retornado.

bool is_canceling();

Valor de retorno

Uma indicação de se o objeto structured_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 structured_task_group. O chamador gerencia o tempo de vida do objeto task_handle passado no parâmetro _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<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á invocado para executar o corpo do identificador de tarefa.

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

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

Comentários

O runtime cria uma cópia da função de trabalho que você passa para este método. 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.

Se o structured_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.

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 structured_task_group para suporte completo ao cancelamento. 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. Em seguida, a função aguarda até que todo o trabalho no objeto structured_task_group tenha sido 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 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 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 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 structured_task_group podem ser executadas em linha no contexto de chamada.

Se uma ou mais das tarefas agendadas para esse objeto structured_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.

Depois que essa função retorna, o objeto structured_task_group é considerado em um estado final e não deve ser usado. Observe que a utilização após o retorno do método run_and_wait resultará em um comportamento indefinido.

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 structured_task_group seja executado.

structured_task_group

Constrói um novo objeto structured_task_group.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Parâmetros

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

Comentários

O construtor que usa 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 impede esse grupo de tarefas estruturado de participar de um cancelamento implícito de um grupo pai com um token diferente ou nenhum token.

~ structured_task_group

Destrói um objeto structured_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.

~structured_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

Aguarda até que todo o trabalho no structured_task_group tenha sido concluído ou seja 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 structured_task_group podem ser executadas em linha no contexto de chamada.

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

Depois que essa função retorna, o objeto structured_task_group é considerado em um estado final e não deve ser usado. Observe que a utilização após o retorno do método wait resultará em um comportamento indefinido.

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 structured_task_group seja executado.

Confira também

Namespace de simultaneidade
Classe task_group
Classe task_handle