Concurrency::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 <ppltasks.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 (typename details::_ContinuationTypeTraits< _Function, void >::_StdFuncT(_Func), _Options)
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 (typename details::_ContinuationTypeTraits< _Function, void >::_StdFuncT(_Func), _Options)
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...
const details::_Task_ptr< details::_Unit_type >::_Type &	_ThenGetImpl () const
void	_SetImpl (const details::_Task_ptr< details::_Unit_type >::_Type &_Impl)
	Set the implementation of the task to be the supplied implementation. More...
void	_SetImpl (details::_Task_ptr< details::_Unit_type >::_Type &&_Impl)
	Set the implementation of the task to be the supplied implementation 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
auto	_ContinuationContext = _TaskOptions.get_continuation_context()
auto	_Options = details::_ThenImplOptions::_CreateOptions(_TaskOptions, _ContinuationContext, _ThenGetImpl()->_GetScheduler())
cancellation_token	_CancellationToken

Private Member Functions
void	_TaskInitNoFunctor (task_completion_event< void > &_Event)
	Initializes a task using a task completion event. More...
template<typename _Function >
void	_TaskInitMaybeFunctor (_Function &_Func, std::true_type)
	Initializes a task using a callable object. More...
template<typename _Ty >
void	_TaskInitMaybeFunctor (_Ty &_Param, std::false_type)
	Initializes a task using a non-callable object. More...

Private Attributes
task< details::_Unit_type >	_M_unitTask

Friends
template<typename _Ty >
class	task
template<typename _Ty >
class	task_completion_event

Detailed Description

template<>
class Concurrency::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 Concurrency::task< void >::result_type

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

Constructor & Destructor Documentation

Concurrency::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 lambda that returns a task<result_type> reach their terminal state when the inner task reaches its terminal state, and not when the lambda 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).

           : _M_unitTask()
    {
        // The default constructor should create a task with a nullptr impl. This is a signal that the
        // task is not usable and should throw if any wait(), get() or then() APIs are used.
    }

Member Function Documentation

template<typename _Ty >

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

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 lambda that returns a task<result_type> reach their terminal state when the inner task reaches its terminal state, and not when the lambda 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 >

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

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

inline

Create an underlying task implementation.

    {
        _M_unitTask._CreateImpl(_Ct, _Scheduler);
    }

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

inline

Return the underlying implementation for this task.

    {
        return _M_unitTask._M_Impl;
    }

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

inline

Sets a property determining whether the task is apartment aware.

    {
        _M_unitTask._SetAsync(_Async);
    }

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

inline

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

    {
        _M_unitTask._SetImpl(_Impl);
    }

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

inline

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

    {
        _M_unitTask._SetImpl(std::move(_Impl));
    }

void Concurrency::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.

    {
        _M_unitTask._SetTaskCreationCallstack(_callstack);
    }

template<typename _Function >

void Concurrency::task< void >::_TaskInitMaybeFunctor ( _Function &  _Func, std::true_type    )

inlineprivate

Initializes a task using a callable object.

    {
        _M_unitTask._TaskInitWithFunctor<void, _Function>(_Func);
    }

template<typename _Ty >

void Concurrency::task< void >::_TaskInitMaybeFunctor ( _Ty &  _Param, std::false_type    )

inlineprivate

Initializes a task using a non-callable object.

    {
        _TaskInitNoFunctor(_Param);
    }

void Concurrency::task< void >::_TaskInitNoFunctor ( task_completion_event< void > &  _Event )

inlineprivate

Initializes a task using a task completion event.

    {
        _M_unitTask._TaskInitNoFunctor(_Event._M_unitEvent);
    }

template<typename _Function >

auto Concurrency::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.

    {

        // inherit from antecedent
        auto _Scheduler = _ThenGetImpl()->_GetScheduler();

        // Note: _ThenImpl's implementation makes a copy of the continuation_context when it schedules the continuation.  '
        //       The Continuation Context used to create the _ThenImplOptions must still exist when _ThenImpl executes.
        auto _Default_Context = task_continuation_context::use_default();
        details::_ThenImplOptions _Options{ _PTokenState, &_Default_Context, _Scheduler, _CAPTURE_CALLSTACK(), _InliningMode };

#ifndef _PPLTASKS_NO_STDFUNC
        return _M_unitTask._ThenImpl<void>(typename details::_ContinuationTypeTraits<_Function, void>::_StdFuncT(_Func), _Options);
#else
        return _M_unitTask._ThenImpl<void>(_Func, _Options);
#endif
    }

const details::_Task_ptr<details::_Unit_type>::_Type& Concurrency::task< void >::_ThenGetImpl ( ) const

inline

    {
        if (!_M_unitTask._M_Impl)
        {
            details::_DefaultTaskHelper::_NoCallOnDefaultTask_ErrorImpl();
        }

        return _M_unitTask._M_Impl;
    }

return _M_unitTask Concurrency::task< void >::_ThenImpl	(	typename details::_ContinuationTypeTraits< _Function, void >::	_StdFuncT_Func,
		_Options
	)

return _M_unitTask Concurrency::task< void >::_ThenImpl	(	typename details::_ContinuationTypeTraits< _Function, void >::	_StdFuncT_Func,
		_Options
	)

Concurrency::task< void >::details::_get_internal_task_options

(

_TaskOptions

)

void Concurrency::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.

    {
        _M_unitTask.get();
    }

bool Concurrency::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.

    {
        return _M_unitTask.is_apartment_aware();
    }

bool Concurrency::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).

    {
        return _M_unitTask.is_done();
    }

bool Concurrency::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.

    {
        return !operator==(_Rhs);
    }

bool Concurrency::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.

    {
        return (_M_unitTask == _Rhs._M_unitTask);
    }

scheduler_ptr Concurrency::task< void >::scheduler ( ) const

inline

Returns the scheduler for this task

Returns

A pointer to the scheduler

    {
        return _M_unitTask.scheduler();
    }

task_status Concurrency::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.

    {
        return _M_unitTask.wait();
    }

Friends And Related Function Documentation

template<typename _Ty >

friend class task

friend

template<typename _Ty >

friend class task_completion_event

friend

Member Data Documentation

cancellation_token Concurrency::task< void >::_CancellationToken

auto Concurrency::task< void >::_ContinuationContext = _TaskOptions.get_continuation_context()

task<details::_Unit_type> Concurrency::task< void >::_M_unitTask

private

auto Concurrency::task< void >::_Options = details::_ThenImplOptions::_CreateOptions(_TaskOptions, _ContinuationContext, _ThenGetImpl()->_GetScheduler())

const task_options& Concurrency::task< void >::_TaskOptions

---

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

• VS2017/inc/ppltasks.h