C++ Rest SDK
The C++ REST SDK is a Microsoft project for cloud-based client-server communication in native code using a modern asynchronous C++ API design. This project aims to help C++ developers connect to and interact with services.
Public Types | Public Member Functions | Public Attributes | Friends | List of all members
pplx::task< void > Class Template Reference

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 void 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...
 
return _M_unitTask _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 _M_unitTask _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...
 
void 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< void > &_Rhs) const
 Determines whether two task objects represent the same internal task. More...
 
bool operator!= (const task< void > &_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< details::_Unit_type >::_Type & _GetImpl () const
 Return the underlying implementation for this task. More...
 
void _SetImpl (const details::_Task_ptr< details::_Unit_type >::_Type &_Impl)
 Set the implementation of the task to be the supplied implementaion. More...
 
void _SetImpl (details::_Task_ptr< details::_Unit_type >::_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, void >::_TaskOfType
 An internal version of then that takes additional flags and executes the continuation inline. Used for runtime internal continuations only. More...
 

Public Attributes

const task_options_TaskOptions
 
cancellation_token _CancellationToken
 

Friends

template<typename T >
class task
 
template<typename T >
class task_completion_event
 

Detailed Description

template<>
class pplx::task< void >

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.

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

Member Typedef Documentation

typedef void pplx::task< void >::result_type

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

Constructor & Destructor Documentation

pplx::task< void >::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).

Member Function Documentation

template<typename _Ty >
pplx::task< void >::__declspec ( noinline  )

Constructs a task object.

Template Parameters
_TyThe type of the parameter from which the task is to be constructed.
Parameters
_ParamThe 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.

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 _Function >
pplx::task< void >::__declspec ( noinline  ) const

Adds a continuation task to this task.

Template Parameters
_FunctionThe type of the function object that will be invoked by this task.
Parameters
_FuncThe 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.
_CancellationTokenThe 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.
_ContinuationContextA 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).

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

Create an underlying task implementation.

const details::_Task_ptr<details::_Unit_type>::_Type& pplx::task< void >::_GetImpl ( ) const
inline

Return the underlying implementation for this task.

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

Sets a property determining whether the task is apartment aware.

void pplx::task< void >::_SetImpl ( const details::_Task_ptr< details::_Unit_type >::_Type &  _Impl)
inline

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

void pplx::task< void >::_SetImpl ( details::_Task_ptr< details::_Unit_type >::_Type &&  _Impl)
inline

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

void pplx::task< void >::_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 _Function >
auto pplx::task< void >::_Then ( const _Function &  _Func,
details::_CancellationTokenState _PTokenState,
details::_TaskInliningMode_t  _InliningMode = details::_ForceInline 
) const -> typename details::_ContinuationTypeTraits<_Function, void>::_TaskOfType
inline

An internal version of then that takes additional flags and executes the continuation inline. Used for runtime internal continuations only.

void pplx::task< void >::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.

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.

bool pplx::task< void >::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.
bool pplx::task< void >::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).

bool pplx::task< void >::operator!= ( const task< void > &  _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.
bool pplx::task< void >::operator== ( const task< void > &  _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.
scheduler_ptr pplx::task< void >::scheduler ( ) const
inline

Returns the scheduler for this task

Returns
A pointer to the scheduler
task_status pplx::task< void >::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.

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