The Parallel Patterns Library (PPL) task class. 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. It produces a result of type _ResultType on successful completion. Tasks of type task<void> produce no result. A task can be waited upon and canceled independently of other tasks. It can also be composed with other tasks using continuations(then), and join(when_all) and choice(when_any) patterns. More...

#include <pplxtasks.h>

Public Types
typedef _ReturnType	result_type
	The type of the result an object of this class produces. More...

Public Member Functions
	task ()
	Constructs a `task` object. More...

template<typename _Ty >
	__declspec (noinline) explicit task(_Ty _Param)
	Constructs a `task` object. More...

template<typename _Ty >
	__declspec (noinline) explicit task(_Ty _Param
	Constructs a `task` object. More...

	_CreateImpl (_TaskOptions.get_cancellation_token()._GetImplValue(), _TaskOptions.get_scheduler())

	_SetTaskCreationCallstack (details::_get_internal_task_options(_TaskOptions)._M_hasPresetCreationCallstack?details::_get_internal_task_options(_TaskOptions)._M_presetCreationCallstack:_CAPTURE_CALLSTACK())

	_TaskInitMaybeFunctor (_Param, details::_IsCallable(_Param, 0))

	task (const task &_Other)
	Constructs a `task` object. More...

	task (task &&_Other)
	Constructs a `task` object. More...

task &	operator= (const task &_Other)
	Replaces the contents of one `task` object with another. More...

task &	operator= (task &&_Other)
	Replaces the contents of one `task` object with another. More...

template<typename _Function >
	__declspec (noinline) auto then(const _Function &_Func) const -> typename details::_ContinuationTypeTraits< _Function, _ReturnType >::_TaskOfType
	Adds a continuation task to this task. More...

template<typename _Function >
	__declspec (noinline) auto then(const _Function &_Func
	Adds a continuation task to this task. More...

return	_ThenImpl (_Func, _TaskOptions)

template<typename _Function >
	__declspec (noinline) auto then(const _Function &_Func
	Adds a continuation task to this task. More...

	details::_get_internal_task_options (_TaskOptions)._set_creation_callstack(_CAPTURE_CALLSTACK())

return	_ThenImpl (_Func, _TaskOptions)

task_status	wait () const
	Waits for this task to reach a terminal state. 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. More...

_ReturnType	get () const
	Returns the result this task produced. If the task is not in a terminal state, a call to `get` will wait for the task to finish. This method does not return a value when called on a task with a `result_type` of `void`. More...

bool	is_done () const
	Determines if the task is completed. More...

scheduler_ptr	scheduler () const
	Returns the scheduler for this task More...

bool	is_apartment_aware () const
	Determines whether the task unwraps a Windows Runtime `IAsyncInfo` interface or is descended from such a task. More...

bool	operator== (const task< _ReturnType > &_Rhs) const
	Determines whether two `task` objects represent the same internal task. More...

bool	operator!= (const task< _ReturnType > &_Rhs) const
	Determines whether two `task` objects represent different internal tasks. More...

void	_CreateImpl (details::_CancellationTokenState *_Ct, scheduler_ptr _Scheduler)
	Create an underlying task implementation. More...

const details::_Task_ptr< _ReturnType >::_Type &	_GetImpl () const
	Return the underlying implementation for this task. More...

void	_SetImpl (const typename details::_Task_ptr< _ReturnType >::_Type &_Impl)
	Set the implementation of the task to be the supplied implementaion. More...

void	_SetImpl (typename details::_Task_ptr< _ReturnType >::_Type &&_Impl)
	Set the implementation of the task to be the supplied implementaion using a move instead of a copy. More...

void	_SetAsync (bool _Async=true)
	Sets a property determining whether the task is apartment aware. More...

void	_SetTaskCreationCallstack (const details::_TaskCreationCallstack &_callstack)
	Sets a field in the task impl to the return callstack for calls to the task constructors and the then method. More...

template<typename _Function >
auto	_Then (const _Function &_Func, details::_CancellationTokenState *_PTokenState, details::_TaskInliningMode_t _InliningMode=details::_ForceInline) const -> typename details::_ContinuationTypeTraits< _Function, _ReturnType >::_TaskOfType
	An internal version of then that takes additional flags and always execute the continuation inline by default. When _ForceInline is set to false, continuations inlining will be limited to default _DefaultAutoInline. This function is Used for runtime internal continuations only. More...

Public Attributes
const task_options &	_TaskOptions

cancellation_token	_CancellationToken

Friends
template<typename T >
class	task

Detailed Description

template<typename _ReturnType>
class pplx::task< _ReturnType >

The Parallel Patterns Library (PPL) task class. 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. It produces a result of type _ResultType on successful completion. Tasks of type task<void> produce no result. A task can be waited upon and canceled independently of other tasks. It can also be composed with other tasks using continuations(then), and join(when_all) and choice(when_any) patterns.

Template Parameters

_ReturnType The result type of this task.

For more information, see Task Parallelism (Concurrency Runtime).

Member Typedef Documentation

template<typename _ReturnType>

typedef _ReturnType pplx::task< _ReturnType >::result_type

The type of the result an object of this class produces.

Constructor & Destructor Documentation

template<typename _ReturnType>

pplx::task< _ReturnType >::task ( )

inline

Constructs a task object.

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. Methods such as get, wait or then will throw an invalid_argument exception when called on a default constructed task.

A task that is created from a task_completion_event will complete (and have its continuations scheduled) when the task completion event is set.

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.

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

The constructor overloads that take a Windows::Foundation::IAsyncInfo interface or a lambda returning such an interface, are only available to Windows Store apps.

For more information, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

pplx::task< _ReturnType >::task ( const task< _ReturnType > & _Other )

inline

Constructs a task object.

Parameters

_Other The source task object.

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. Methods such as get, wait or then will throw an invalid_argument exception when called on a default constructed task.

A task that is created from a task_completion_event will complete (and have its continuations scheduled) when the task completion event is set.

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.

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

The constructor overloads that take a Windows::Foundation::IAsyncInfo interface or a lambda returning such an interface, are only available to Windows Store apps.

For more information, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

pplx::task< _ReturnType >::task ( task< _ReturnType > && _Other )

inline

Constructs a task object.

Parameters

_Other The source task object.

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. Methods such as get, wait or then will throw an invalid_argument exception when called on a default constructed task.

A task that is created from a task_completion_event will complete (and have its continuations scheduled) when the task completion event is set.

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.

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

The constructor overloads that take a Windows::Foundation::IAsyncInfo interface or a lambda returning such an interface, are only available to Windows Store apps.

For more information, see Task Parallelism (Concurrency Runtime).

Member Function Documentation

template<typename _ReturnType>

template<typename _Ty >

pplx::task< _ReturnType >::__declspec ( noinline )

inline

Constructs a task object.

Template Parameters

_Ty	The type of the parameter from which the task is to be constructed.

Parameters

_Param The parameter from which the task is to be constructed. 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 Store app. 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 Store apps.

_Token The cancellation token to associate with this task. A task created without a cancellation token cannot be canceled. It implicitly receives the token cancellation_token::none().

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. Methods such as get, wait or then will throw an invalid_argument exception when called on a default constructed task.

A task that is created from a task_completion_event will complete (and have its continuations scheduled) when the task completion event is set.

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.

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

The constructor overloads that take a Windows::Foundation::IAsyncInfo interface or a lambda returning such an interface, are only available to Windows Store apps.

For more information, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

template<typename _Ty >

pplx::task< _ReturnType >::__declspec ( noinline )

Constructs a task object.

Template Parameters

_Ty	The type of the parameter from which the task is to be constructed.

Parameters

_Param The parameter from which the task is to be constructed. 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 Store app. 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 Store apps.

_TaskOptions The task options include cancellation token, scheduler etc

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. Methods such as get, wait or then will throw an invalid_argument exception when called on a default constructed task.

A task that is created from a task_completion_event will complete (and have its continuations scheduled) when the task completion event is set.

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.

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

The constructor overloads that take a Windows::Foundation::IAsyncInfo interface or a lambda returning such an interface, are only available to Windows Store apps.

For more information, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

template<typename _Function >

pplx::task< _ReturnType >::__declspec ( noinline ) const -> typename details::_ContinuationTypeTraits<_Function, _ReturnType>::_TaskOfType

inline

Adds a continuation task to this task.

Template Parameters

_Function The type of the function object that will be invoked by this task.

Parameters

_Func The continuation function to execute when this task completes. 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.

Returns: The newly created continuation task. The result type of the returned task is determined by what _Func returns.

The overloads of then that take a lambda or functor that returns a Windows::Foundation::IAsyncInfo interface, are only available to Windows Store apps.

For more information on how to use task continuations to compose asynchronous work, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

template<typename _Function >

pplx::task< _ReturnType >::__declspec ( noinline ) const

Adds a continuation task to this task.

Template Parameters

_Function The type of the function object that will be invoked by this task.

Parameters

_Func	The continuation function to execute when this task completes. 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. By default the former 3 options are inherited from the antecedent task

Returns: The newly created continuation task. The result type of the returned task is determined by what _Func returns.

The overloads of then that take a lambda or functor that returns a Windows::Foundation::IAsyncInfo interface, are only available to Windows Store apps.

For more information on how to use task continuations to compose asynchronous work, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

template<typename _Function >

pplx::task< _ReturnType >::__declspec ( noinline ) const

Adds a continuation task to this task.

Template Parameters

_Function The type of the function object that will be invoked by this task.

Parameters

_Func	The continuation function to execute when this task completes. 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.
_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. This variable is only useful when used in a Windows Store style app. For more information, see task_continuation_context

Returns: The newly created continuation task. The result type of the returned task is determined by what _Func returns.

The overloads of then that take a lambda or functor that returns a Windows::Foundation::IAsyncInfo interface, are only available to Windows Store apps.

For more information on how to use task continuations to compose asynchronous work, see Task Parallelism (Concurrency Runtime).

template<typename _ReturnType>

void pplx::task< _ReturnType >::_CreateImpl	(	details::_CancellationTokenState *	_Ct,
		scheduler_ptr	_Scheduler
	)

inline

Create an underlying task implementation.

template<typename _ReturnType>

const details::_Task_ptr<_ReturnType>::_Type& pplx::task< _ReturnType >::_GetImpl ( ) const

inline

Return the underlying implementation for this task.

template<typename _ReturnType>

void pplx::task< _ReturnType >::_SetAsync ( bool _Async = true )

inline

Sets a property determining whether the task is apartment aware.

template<typename _ReturnType>

void pplx::task< _ReturnType >::_SetImpl ( const typename details::_Task_ptr< _ReturnType >::_Type & _Impl )

inline

Set the implementation of the task to be the supplied implementaion.

template<typename _ReturnType>

void pplx::task< _ReturnType >::_SetImpl ( typename details::_Task_ptr< _ReturnType >::_Type && _Impl )

inline

Set the implementation of the task to be the supplied implementaion using a move instead of a copy.

template<typename _ReturnType>

void pplx::task< _ReturnType >::_SetTaskCreationCallstack ( const details::_TaskCreationCallstack & _callstack )

inline

Sets a field in the task impl to the return callstack for calls to the task constructors and the then method.

template<typename _ReturnType>

template<typename _Function >

auto pplx::task< _ReturnType >::_Then	(	const _Function &	_Func,
		details::_CancellationTokenState *	_PTokenState,
		details::_TaskInliningMode_t	_InliningMode = `details::_ForceInline`
	)		const -> typename details::_ContinuationTypeTraits<_Function, _ReturnType>::_TaskOfType

inline

An internal version of then that takes additional flags and always execute the continuation inline by default. When _ForceInline is set to false, continuations inlining will be limited to default _DefaultAutoInline. This function is Used for runtime internal continuations only.

template<typename _ReturnType>

_ReturnType pplx::task< _ReturnType >::get ( ) const

inline

Returns the result this task produced. If the task is not in a terminal state, a call to get will wait for the task to finish. This method does not return a value when called on a task with a result_type of void.

Returns: The result of the task.

If the task is canceled, a call to get will throw a task_canceled exception. 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.

template<typename _ReturnType>

bool pplx::task< _ReturnType >::is_apartment_aware ( ) const

inline

Determines whether the task unwraps a Windows Runtime IAsyncInfo interface or is descended from such a task.

Returns: true if the task unwraps an IAsyncInfo interface or is descended from such a task, false otherwise.

template<typename _ReturnType>

bool pplx::task< _ReturnType >::is_done ( ) const

inline

Determines if the task is completed.

Returns: True if the task has completed, false otherwise.

The function returns true if the task is completed or canceled (with or without user exception).

template<typename _ReturnType>

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

inline

Determines whether two task objects represent different internal tasks.

Returns: true if the objects refer to different underlying tasks, and false otherwise.

template<typename _ReturnType>

task& pplx::task< _ReturnType >::operator= ( const task< _ReturnType > & _Other )

inline

Replaces the contents of one task object with another.

Parameters

_Other The source task object.

As task behaves like a smart pointer, after a copy assignment, this task objects represents the same actual task as _Other does.

template<typename _ReturnType>

task& pplx::task< _ReturnType >::operator= ( task< _ReturnType > && _Other )

inline

Replaces the contents of one task object with another.

Parameters

_Other The source task object.

As task behaves like a smart pointer, after a copy assignment, this task objects represents the same actual task as _Other does.

template<typename _ReturnType>

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

inline

Determines whether two task objects represent the same internal task.

Returns: true if the objects refer to the same underlying task, and false otherwise.

template<typename _ReturnType>

scheduler_ptr pplx::task< _ReturnType >::scheduler ( ) const

inline

Returns the scheduler for this task

Returns: A pointer to the scheduler

template<typename _ReturnType>

task_status pplx::task< _ReturnType >::wait ( ) const

inline

Waits for this task to reach a terminal state. 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.

Returns: A task_status value which could be either completed or canceled. If the task encountered an exception during execution, or an exception was propagated to it from an antecedent task, wait will throw that exception.

Member Data Documentation

template<typename _ReturnType>

const task_options& pplx::task< _ReturnType >::_TaskOptions

Initial value:

{

details::_ValidateTaskConstructorArgs<_ReturnType,_Ty>(_Param)

The documentation for this class was generated from the following file:

include/pplx/pplxtasks.h

Public Types

Public Member Functions

Public Attributes

Friends

Detailed Description

template<typename _ReturnType> class pplx::task< _ReturnType >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename _ReturnType>
class pplx::task< _ReturnType >