task 类(并发运行时)task Class (Concurrency Runtime)

并行模式库 (PPL) task 类。The Parallel Patterns Library (PPL) task class. task 对象,表示可异步执行的工作,以及可与并发运行时中的并行算法生成的其他任务一起执行的工作。A task object represents work that can be executed asynchronously, and concurrently with other tasks and parallel work produced by parallel algorithms in the Concurrency Runtime. 成功完成后,它将生成类型为 _ResultType 的结果。It produces a result of type _ResultType on successful completion. 类型为 task<void> 的任务不生成任何结果。Tasks of type task<void> produce no result. 可独立于其他任务等待和取消的任务。A task can be waited upon and canceled independently of other tasks. 它还可由其他使用延续任务 ( then),和联接 ( when_all) 以及所选择的 ( when_any) 模式。It can also be composed with other tasks using continuations( then), and join( when_all) and choice( when_any) patterns.

语法Syntax

template <typename T>
class task;

template <>
class task<void>;

template<typename _ReturnType>
class task;

参数Parameters

T
T
_ReturnType
此任务的结果类型。The result type of this task.

成员Members

公共 TypedefPublic Typedefs

名称Name 描述Description
result_type 此类的一个对象生成的结果类型。The type of the result an object of this class produces.

公共构造函数Public Constructors

名称Name 描述Description
tasktask 已重载。Overloaded. 构造 task 对象。Constructs a task object.

公共方法Public Methods

名称Name 描述Description
getget 已重载。Overloaded. 返回此任务产生的结果。Returns the result this task produced. 如果任务不处于终止状态,则对 get 的调用将等待任务完成。If the task is not in a terminal state, a call to get will wait for the task to finish. 在调用 result_typevoid 的任务时,此方法不返回值。This method does not return a value when called on a task with a result_type of void.
is_apartment_awareis_apartment_aware 确定任务是否解包 Windows 运行时 IAsyncInfo 接口或继承自此类任务。Determines whether the task unwraps a Windows Runtime IAsyncInfo interface or is descended from such a task.
is_doneis_done 确定任务是否已完成。Determines if the task is completed.
schedulerscheduler 返回此任务的计划程序Returns the scheduler for this task
thenthen 已重载。Overloaded. 向此任务添加延续任务。Adds a continuation task to this task.
waitwait 等待此任务到达终止状态。Waits for this task to reach a terminal state. wait 可执行内联任务,前提是所有任务依赖项得到满足并且后台辅助线程没有选取它执行。It is possible for wait to execute the task inline, if all of the tasks dependencies are satisfied, and it has not already been picked up for execution by a background worker.

公共运算符Public Operators

名称Name 描述Description
operator!=operator!= 已重载。Overloaded. 确定两个 task 对象是否表示不同的内部任务。Determines whether two task objects represent different internal tasks.
operator=operator= 已重载。Overloaded. 将一个 task 对象的内容替换为另一个对象的内容。Replaces the contents of one task object with another.
operator==operator== 已重载。Overloaded. 确定两个 task 对象是否表示相同的内部任务。Determines whether two task objects represent the same internal task.

备注Remarks

有关详细信息,请参阅任务并行For more information, see Task Parallelism.

继承层次结构Inheritance Hierarchy

task

要求Requirements

标头: ppltasks.hHeader: ppltasks.h

命名空间: 并发Namespace: concurrency

获取get

返回此任务产生的结果。Returns the result this task produced. 如果任务不处于终止状态,则对 get 的调用将等待任务完成。If the task is not in a terminal state, a call to get will wait for the task to finish. 在调用 result_typevoid 的任务时,此方法不返回值。This method does not return a value when called on a task with a result_type of void.

_ReturnType get() const;

void get() const;

返回值Return Value

任务的结果。The result of the task.

备注Remarks

如果任务已取消,调用get将引发task_canceled异常。If the task is canceled, a call to get will throw a task_canceled exception. 如果任务遇到了不同的异常或异常从前面的任务传播到此任务,则对 get 的调用将引发该异常。If the task encountered an different exception or an exception was propagated to it from an antecedent task, a call to get will throw that exception.

重要

在通用 Windows 平台 (UWP) 应用中,请勿调用concurrency::task::waitget(wait调用get) 在 STA 运行的代码中In a Universal Windows Platform (UWP) app, do not call concurrency::task::wait or get ( wait calls get) in code that runs on the STA. 否则,运行时会引发concurrency:: invalid_operation原因这些方法阻止当前线程并可能导致应用停止响应。Otherwise, the runtime throws concurrency::invalid_operation because these methods block the current thread and can cause the app to become unresponsive. 但是,你可以调用get方法来接收基于任务的延续中的先行任务的结果,因为所得的结果立即可用。However, you can call the get method to receive the result of the antecedent task in a task-based continuation because the result is immediately available.

is_apartment_awareis_apartment_aware

确定任务是否解包 Windows 运行时 IAsyncInfo 接口或继承自此类任务。Determines whether the task unwraps a Windows Runtime IAsyncInfo interface or is descended from such a task.

bool is_apartment_aware() const;

返回值Return Value

如果任务解包一个 true 接口或继承自此类任务,则为 IAsyncInfo;否则为 falsetrue if the task unwraps an IAsyncInfo interface or is descended from such a task, false otherwise.

task:: is_done 方法 (并发运行时)task::is_done Method (Concurrency Runtime)

确定任务是否已完成。Determines if the task is completed.

bool is_done() const;

返回值Return Value

如果任务已完成,false 否则,则为 true。True if the task has completed, false otherwise.

备注Remarks

如果任务已完成或取消 (有或没有用户异常),该函数返回 true。The function returns true if the task is completed or canceled (with or without user exception).

operator!=operator!=

确定两个 task 对象是否表示不同的内部任务。Determines whether two task objects represent different internal tasks.

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

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

参数Parameters

_Rhs

返回值Return Value

如果这两个对象引用不同基础任务,则为 true;否则为 falsetrue if the objects refer to different underlying tasks, and false otherwise.

operator=operator=

将一个 task 对象的内容替换为另一个对象的内容。Replaces the contents of one task object with another.

task& operator= (const task& _Other);

task& operator= (task&& _Other);

参数Parameters

_Other
task 对象。The source task object.

返回值Return Value

备注Remarks

task 的行为方式与智能指针的类似,在分配副本之后,此 task 对象与 _Other 表示相同的实际任务。As task behaves like a smart pointer, after a copy assignment, this task objects represents the same actual task as _Other does.

运算符 = =operator==

确定两个 task 对象是否表示相同的内部任务。Determines whether two task objects represent the same internal task.

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

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

参数Parameters

_Rhs

返回值Return Value

如果这两个对象引用同一基础任务,则为 true;否则为 falsetrue if the objects refer to the same underlying task, and false otherwise.

task:: scheduler 方法 (并发运行时)task::scheduler Method (Concurrency Runtime)

返回此任务的计划程序Returns the scheduler for this task

scheduler_ptr scheduler() const;

返回值Return Value

计划程序指针A pointer to the scheduler

任务task

构造 task 对象。Constructs a task object.

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

参数Parameters

T
从中构造任务的参数的类型。The type of the parameter from which the task is to be constructed.

_Param
从中构造任务的参数。The parameter from which the task is to be constructed. 这可能是 lambda、 函数对象,task_completion_event<result_type>对象或如果你要在 Windows 运行时应用程序中使用任务 Windows::Foundation::IAsyncInfo。This could be a lambda, a function object, a task_completion_event<result_type> object, or a Windows::Foundation::IAsyncInfo if you are using tasks in your Windows Runtime app. Lambda 或函数对象应为类型等效于std::function<X(void)>,其中 X 可以是类型的变量的result_typetask<result_type>,或在 Windows 运行时应用 Windows::Foundation::IAsyncInfo。The lambda or function object should be a type equivalent to std::function<X(void)>, where X can be a variable of type result_type, task<result_type>, or a Windows::Foundation::IAsyncInfo in Windows Runtime apps.

_TaskOptions
任务选项包括取消标记、计划程序等The task options include cancellation token, scheduler etc

_Other
task 对象。The source task object.

备注Remarks

task 的默认构造函数仅用于允许在容器中使用任务。The default constructor for a task is only present in order to allow tasks to be used within containers. 只有在分配有效任务后才能使用默认的构造任务。A default constructed task cannot be used until you assign a valid task to it. 等方法getwaitthen将引发invalid_argument异常时对默认构造任务调用。Methods such as get, wait or then will throw an invalid_argument exception when called on a default constructed task.

通过 task_completion_event 创建的任务将在设置任务完成事件后完成(并安排好其延续)。A task that is created from a task_completion_event will complete (and have its continuations scheduled) when the task completion event is set.

采用取消标记的构造函数的版本可创建能够通过使用提供标记的 cancellation_token_source 取消的任务。The version of the constructor that takes a cancellation token creates a task that can be canceled using the cancellation_token_source the token was obtained from. 创建时没有使用取消标记的任务不可取消。Tasks created without a cancellation token are not cancelable.

通过 Windows::Foundation::IAsyncInfo 接口或返回 IAsyncInfo 接口的 lambda 创建的任务在封闭的 Windows 运行时异步操作或行为完成时达到其终止状态。Tasks created from a Windows::Foundation::IAsyncInfo interface or a lambda that returns an IAsyncInfo interface reach their terminal state when the enclosed Windows Runtime asynchronous operation or action completes. 同样,通过返回 task<result_type> 的 lamda 创建的任务在内部任务达到其终止状态时而非 lamda 返回时达到其终止状态。Similarly, tasks created from a lamda that returns a task<result_type> reach their terminal state when the inner task reaches its terminal state, and not when the lamda returns.

task 行为与智能指针的行为类似,可按值安全传递。task behaves like a smart pointer and is safe to pass around by value. 它可以由多个线程访问,而无需锁定。It can be accessed by multiple threads without the need for locks.

采用 Windows::Foundation::IAsyncInfo 接口或返回此类接口,lambda 的构造函数重载才可用于 Windows 运行时应用。The constructor overloads that take a Windows::Foundation::IAsyncInfo interface or a lambda returning such an interface, are only available to Windows Runtime apps.

有关详细信息,请参阅任务并行For more information, see Task Parallelism.

然后then

向此任务添加延续任务。Adds a continuation task to this task.

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

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

template<typename _Function>
__declspec(
    noinline) auto then(const _Function& _Func,
    cancellation_token _CancellationToken,
    task_continuation_context _ContinuationContext) const -> typename details::_ContinuationTypeTraits<_Function,
    _ReturnType>::_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;

参数Parameters

_Function
此任务将调用的函数对象的类型。The type of the function object that will be invoked by this task.

_Func
此任务完成时要执行的延续函数。The continuation function to execute when this task completes. 此延续函数必须将 result_typetask<result_type> 的变量作为输入,其中 result_type 是此任务产生的结果的类型。This continuation function must take as input a variable of either result_type or task<result_type>, where result_type is the type of the result this task produces.

_TaskOptions
任务选项包括取消标记、计划程序和延续上下文。The task options include cancellation token, scheduler and continuation context. 默认情况下,前面的 3 个选项是从前面的任务继承的By default the former 3 options are inherited from the antecedent task

_CancellationToken
要与延续任务相关联的取消标记。The cancellation token to associate with the continuation task. 创建时不带取消标记的延续任务将继承其前面的任务的标记。A continuation task that is created without a cancellation token will inherit the token of its antecedent task.

_ContinuationContext
用于指定执行延续的位置的变量。A variable that specifies where the continuation should execute. 此变量仅在 UWP 应用中使用时有用。This variable is only useful when used in a UWP app. 有关详细信息,请参阅task_continuation_contextFor more information, see task_continuation_context

返回值Return Value

新创建的延续任务。The newly created continuation task. 返回任务的结果类型取决于 _Func 返回的内容。The result type of the returned task is determined by what _Func returns.

备注Remarks

重载then采用 lambda 或函子分别返回 Windows::Foundation::IAsyncInfo 接口,请仅可供 Windows 运行时应用。The overloads of then that take a lambda or functor that returns a Windows::Foundation::IAsyncInfo interface, are only available to Windows Runtime apps.

有关如何使用任务延续撰写异步工作的详细信息,请参阅任务并行For more information on how to use task continuations to compose asynchronous work, see Task Parallelism.

等待wait

等待此任务到达终止状态。Waits for this task to reach a terminal state. wait 可执行内联任务,前提是所有任务依赖项得到满足并且后台辅助线程没有选取它执行。It is possible for wait to execute the task inline, if all of the tasks dependencies are satisfied, and it has not already been picked up for execution by a background worker.

task_status wait() const;

返回值Return Value

可为 task_statuscompletedcanceled 值。A task_status value which could be either completed or canceled. 如果任务在执行期间遇到了异常或异常从前面的任务传播到此任务,则 wait 将引发该异常。If the task encountered an exception during execution, or an exception was propagated to it from an antecedent task, wait will throw that exception.

备注Remarks

重要

在通用 Windows 平台 (UWP) 应用中,请勿调用wait在 STA 运行的代码中In a Universal Windows Platform (UWP) app, do not call wait in code that runs on the STA. 否则,运行时会引发concurrency:: invalid_operation原因是此方法阻止当前线程并可能导致应用停止响应。Otherwise, the runtime throws concurrency::invalid_operation because this method blocks the current thread and can cause the app to become unresponsive. 但是,你可以调用concurrency::task::get方法来接收基于任务的延续中的先行任务的结果。However, you can call the concurrency::task::get method to receive the result of the antecedent task in a task-based continuation.

另请参阅See Also

并发命名空间concurrency Namespace