Classe task (Runtime de Simultaneidade)

A classe task da Biblioteca de Padrões Paralelos (PPL). O objeto task representa o trabalho que pode ser executado de forma assíncrona e simultânea com outras tarefas e o trabalho paralelo produzido por algoritmos paralelos no Runtime de Simultaneidade. Produz um resultado de tipo _ResultType após uma conclusão bem-sucedida. Tarefas do tipo task<void> não produzem resultados. Uma tarefa pode ser aguardada e cancelada independentemente de outras tarefas. Ela também pode ser composta por outras tarefas usando continuações (then) e os padrões de junção (when_all) e escolha (when_any). Quando um objeto de tarefa é atribuído a uma nova variável, o comportamento é o de std::shared_ptr; em outras palavras, ambos os objetos representam a mesma tarefa subjacente.

Sintaxe

template <>
class task<void>;

template<typename _ResultType>
class task;

Parâmetros

_ResultType
O tipo do resultado que a tarefa produz.

Membros

Typedefs públicos

Nome	Descrição
result_type	O tipo do resultado que um objeto desta classe produz.

Construtores públicos

Nome	Descrição
task	Sobrecarregado. Constrói um objeto task.

Métodos públicos

Nome	Descrição
get	Sobrecarregado. Retorna o resultado produzido por essa tarefa. Se a tarefa não estiver em um estado terminal, uma chamada para get irá aguardar a conclusão da tarefa. Este método não retorna um valor quando chamado em uma tarefa com um result_type de void.
is_apartment_aware	Determina se a tarefa desvincula uma interface de Windows Runtime IAsyncInfo ou se é descendente de tal tarefa.
is_done	Determina se a tarefa foi concluída.
scheduler	Retorna o agendador para essa tarefa
then	Sobrecarregado. Adiciona uma tarefa de continuação para essa tarefa.
wait	Aguarda que essa tarefa alcance um estado terminal. É possível para wait executar a tarefa em linha, se todas as dependências de tarefas forem atendidas, e ela ainda não tiver sido escolhida para execução por um trabalho em segundo plano.

Operadores públicos

Nome	Descrição
operator!=	Sobrecarregado. Determina se dois objetos task representam tarefas internas diferentes.
operator=	Sobrecarregado. Substitui o conteúdo de um objeto task por outro.
operator==	Sobrecarregado. Determina se dois objetos task representam a mesma tarefa interna.

Comentários

Para saber mais, confira Paralelismo da tarefa.

Hierarquia de herança

task

Requisitos

Cabeçalho: ppltasks.h

Namespace: concurrency

get

Retorna o resultado produzido por essa tarefa. Se a tarefa não estiver em um estado terminal, uma chamada para get irá aguardar a conclusão da tarefa. Este método não retorna um valor quando chamado em uma tarefa com um result_type de void.

_ResultType get() const;

void get() const;

Valor de retorno

O resultado da tarefa.

Comentários

Se a tarefa for cancelada, uma chamada a get lançará uma exceção task_canceled. Se a tarefa encontrou uma exceção diferente ou uma exceção foi propagada para ela a partir de uma tarefa antecedente, uma chamada para get gerará essa exceção.

Importante

Em um aplicativo de Plataforma Universal do Windows (UWP), não chame concurrency::task::wait ou get ( wait chama get) no código executado no thread da interface do usuário. Caso contrário, o runtime gerará concurrency::invalid_operation porque esses métodos bloqueiam o thread atual e podem fazer com que o aplicativo fique sem resposta. No entanto, você pode chamar o método get para receber o resultado da tarefa antecedente em uma continuação baseada em tarefa porque o resultado está disponível imediatamente.

is_apartment_aware

Determina se a tarefa desvincula uma interface de Windows Runtime IAsyncInfo ou se é descendente de tal tarefa.

bool is_apartment_aware() const;

Valor de retorno

true se a tarefa desencapsular uma interface IAsyncInfo ou for descendente dessa tarefa; caso contrário, false.

Método task::is_done (tempo de execução de simultaneidade)

Determina se a tarefa foi concluída.

bool is_done() const;

Valor de retorno

True se a tarefa tiver sido concluída; caso contrário, false.

Comentários

A função retornará true se a tarefa for concluída ou cancelada (com ou sem exceção do usuário).

operator!=

Determina se dois objetos task representam tarefas internas diferentes.

bool operator!= (const task<_ResultType>& _Rhs) const;

bool operator!= (const task<void>& _Rhs) const;

Parâmetros

_Rhs
A tarefa a ser comparada.

Valor de retorno

true se os objetos se referirem a tarefas subjacentes diferentes; caso contrário, false.

operator=

Substitui o conteúdo de um objeto task por outro.

task& operator= (const task& _Other);

task& operator= (task&& _Other);

Parâmetros

_Other
O objeto de origem task .

Valor de retorno

Comentários

Como task se comporta como um ponteiro inteligente, após uma atribuição de cópia, esses objetos task representam a mesma tarefa real que _Other faz.

operator==

Determina se dois objetos task representam a mesma tarefa interna.

bool operator== (const task<_ResultType>& _Rhs) const;

bool operator== (const task<void>& _Rhs) const;

Parâmetros

_Rhs
A tarefa a ser comparada.

Valor de retorno

true se os objetos se referirem à mesma tarefa subjacente; caso contrário, false.

task::scheduler Método (tempo de execução de simultaneidade)

Retorna o agendador para essa tarefa

scheduler_ptr scheduler() const;

Valor de retorno

Um ponteiro para o agendador

task

Constrói um objeto task.

task();

template<typename T>
__declspec(
    noinline) explicit task(T _Param);

template<typename T>
__declspec(
    noinline) explicit task(T _Param, const task_options& _TaskOptions);

task(
    const task& _Other);

task(
    task&& _Other);

Parâmetros

T
O tipo do parâmetro do qual a tarefa deve ser construída.

_Param
O parâmetro do qual a tarefa deve ser construída. Isso pode ser um lambda, um objeto de função, um objeto task_completion_event<result_type> ou um Windows::Foundation::IAsyncInfo se você estiver usando tarefas em seu aplicativo Windows Runtime. O lambda ou objeto de função devem ser um tipo equivalente a std::function<X(void)>, em que X pode ser uma variável de tipo result_type, task<result_type> ou um Windows::Foundation::IAsyncInfo em aplicativos Windows Runtime.

_TaskOptions
As opções de tarefa incluem token de cancelamento, agendador etc.

_Other
O objeto de origem task .

Comentários

O construtor padrão para um task só está presente para permitir que as tarefas sejam usadas em contêineres. Uma tarefa padrão construída não pode ser usada até que você atribua uma tarefa válida a ela. Métodos como get, wait ou then lançarão uma exceção invalid_argument quando chamado em uma tarefa padrão construída.

Uma tarefa criada a partir de um task_completion_event será concluída (e terá suas continuações agendadas) quando o evento de conclusão da tarefa estiver definido.

A versão do construtor que recebe um token de cancelamento cria uma tarefa que pode ser cancelada usando o cancellation_token_source do qual o token foi obtido. Tarefas criadas sem um token de cancelamento não podem ser canceladas.

Tarefas criadas a partir de uma interface Windows::Foundation::IAsyncInfo ou de um lambda que retorna uma interface IAsyncInfo chegam ao estado terminal quando a operação ou ação assíncrona fechada do Windows Runtime é concluída. Da mesma forma, as tarefas criadas a partir de uma lambda que retorna um task<result_type> alcançam seus estados terminais quando a tarefa interna atinge seu estado terminal, e não quando o lambda retorna.

task se comporta como um ponteiro inteligente e é seguro para passar por valor. Ele pode ser acessado por vários threads sem a necessidade de bloqueios.

As sobrecargas do construtor que usam uma interface Windows::Foundation::IAsyncInfo ou um lambda que retorna tal interface só estão disponíveis para aplicativos Windows Runtime.

Para saber mais, confira Paralelismo da tarefa.

e, em seguida,

Adiciona uma tarefa de continuação para essa tarefa.

template<typename _Function>
__declspec(
    noinline) auto then(const _Function& _Func) const -> typename details::_ContinuationTypeTraits<_Function,
    _ResultType>::_TaskOfType;

template<typename _Function>
__declspec(
    noinline) auto then(const _Function& _Func,
    const task_options& _TaskOptions) const -> typename details::_ContinuationTypeTraits<_Function,
    _ResultType>::_TaskOfType;

template<typename _Function>
__declspec(
    noinline) auto then(const _Function& _Func,
    cancellation_token _CancellationToken,
    task_continuation_context _ContinuationContext) const -> typename details::_ContinuationTypeTraits<_Function,
    _ResultType>::_TaskOfType;

template<typename _Function>
__declspec(
    noinline) auto then(const _Function& _Func,
    const task_options& _TaskOptions = task_options()) const -> typename details::_ContinuationTypeTraits<_Function,
    void>::_TaskOfType;

template<typename _Function>
__declspec(
    noinline) auto then(const _Function& _Func,
    cancellation_token _CancellationToken,
    task_continuation_context _ContinuationContext) const -> typename details::_ContinuationTypeTraits<_Function,
    void>::_TaskOfType;

Parâmetros

_Function
O tipo do objeto de função que será invocado por essa tarefa.

_Func
A função de continuação a ser executada quando essa tarefa for concluída. Essa função de continuação deve tomar como entrada uma variável de result_type ou task<result_type>, onde result_type é o tipo do resultado que essa tarefa produz.

_TaskOptions
As opções de tarefa incluem token de cancelamento, agendador e contexto de continuação. Por padrão, as três opções anteriores são herdadas da tarefa anterior

_CancellationToken
O token de cancelamento a ser associado à nova tarefa de continuação. Uma tarefa de continuação criada sem um token de cancelamento herdará o token de sua tarefa precedente.

_ContinuationContext
Uma variável que especifica onde a continuação deve ser executada. Essa variável só é útil quando usada em um aplicativo UWP. Para obter mais informações, consulte task_continuation_context

Valor de retorno

A tarefa de continuação recém-criada. O tipo de resultado da tarefa retornada é determinado pelo que _Func retornar.

Comentários

As sobrecargas de then que recebem um lambda ou functor que retorna uma interface Windows::Foundation::IAsyncInfo só estão disponíveis para aplicativos Windows Runtime.

Para obter mais informações sobre como usar continuações de tarefa para redigir trabalhos assíncronos, consulte Paralelismo de Tarefa.

wait

Aguarda que essa tarefa alcance um estado terminal. É possível para wait executar a tarefa em linha, se todas as dependências de tarefas forem atendidas, e ela ainda não tiver sido escolhida para execução por um trabalho em segundo plano.

task_status wait() const;

Valor de retorno

Um valor task_status que pode ser completed ou canceled. Se a tarefa tiver encontrado uma exceção durante a execução ou uma exceção tiver sido propagada para ela de uma tarefa precedente, wait lançará essa exceção.

Comentários

Importante

Em um aplicativo de Plataforma Universal do Windows (UWP), não chame wait em código executado no thread da interface do usuário. Caso contrário, o runtime gerará concurrency::invalid_operation porque esse método bloqueia o thread atual e pode fazer com que o aplicativo fique sem resposta. No entanto, você pode chamar o método concurrency::task::get para receber o resultado da tarefa antecedente em uma continuação baseada em tarefa.

Confira também

Namespace de simultaneidade