Concurrency::details::_Task_impl< _ReturnType > Struct Template Reference

The implementation of a first-class task. This structure contains the task group used to execute the task function and handles the scheduling. The _Task_impl is created as a shared_ptr member of the the public task class, so its destruction is handled automatically. More...

#include <ppltasks.h>

Inheritance diagram for Concurrency::details::_Task_impl< _ReturnType >:

Public Member Functions
	_Task_impl (_CancellationTokenState *_Ct, scheduler_ptr _Scheduler_arg)
virtual	~_Task_impl ()
virtual bool	_CancelAndRunContinuations (bool _SynchronousCancel, bool _UserException, bool _PropagatedFromAncestor, const std::shared_ptr< _ExceptionHolder > &_ExceptionHolder_arg)
	Requests cancellation on the task and schedules continuations if the task can be transitioned to a terminal state. More...
void	_FinalizeAndRunContinuations (_ReturnType _Result)
bool	_TransitionedToStarted ()
bool	_IsDone ()
_ReturnType	_GetResult ()
Public Member Functions inherited from Concurrency::details::_Task_impl_base
	_Task_impl_base (_CancellationTokenState *_PTokenState, scheduler_ptr _Scheduler_arg)
virtual	~_Task_impl_base ()
task_status	_Wait ()
bool	_Cancel (bool _SynchronousCancel)
bool	_CancelWithExceptionHolder (const std::shared_ptr< _ExceptionHolder > &_ExHolder, bool _PropagatedFromAncestor)
bool	_CancelWithException (const std::exception_ptr &_Exception)
void	_RegisterCancellation (std::weak_ptr< _Task_impl_base > _WeakPtr)
void	_DeregisterCancellation ()
bool	_IsCreated ()
bool	_IsStarted ()
bool	_IsPendingCancel ()
bool	_IsCompleted ()
bool	_IsCanceled ()
bool	_HasUserException ()
const std::shared_ptr< _ExceptionHolder > &	_GetExceptionHolder ()
bool	_IsApartmentAware ()
void	_SetAsync (bool _Async=true)
_TaskCreationCallstack	_GetTaskCreationCallstack ()
void	_SetTaskCreationCallstack (const _TaskCreationCallstack &_Callstack)
void	_ScheduleTask (_UnrealizedChore_t *_PTaskHandle, _TaskInliningMode_t _InliningMode)
	Helper function to schedule the task on the Task Collection. More...
void	_RunContinuation (_ContinuationTaskHandleBase *_PTaskHandle)
	Function executes a continuation. This function is recorded by a parent task implementation when a continuation is created in order to execute later. More...
void	_ScheduleContinuationTask (_ContinuationTaskHandleBase *_PTaskHandle)
void	_ScheduleContinuation (_ContinuationTaskHandleBase *_PTaskHandle)
	Schedule the actual continuation. This will either schedule the function on the continuation task's implementation if the task has completed or append it to a list of functions to execute when the task actually does complete. More...
void	_RunTaskContinuations ()
scheduler_ptr	_GetScheduler () const

Public Attributes
_ResultHolder< _ReturnType >	_M_Result
Public Attributes inherited from Concurrency::details::_Task_impl_base
volatile _TaskInternalState	_M_TaskState
bool	_M_fFromAsync
bool	_M_fUnwrappedTask
std::shared_ptr< _ExceptionHolder >	_M_exceptionHolder
::Concurrency::extensibility::critical_section_t	_M_ContinuationsCritSec
_ContinuationList	_M_Continuations
_CancellationTokenState *	_M_pTokenState
_CancellationTokenRegistration *	_M_pRegistration
::Concurrency::details::_TaskCollection_t	_M_TaskCollection
_TaskCreationCallstack	_M_pTaskCreationCallstack
_TaskEventLogger	_M_taskEventLogger

Additional Inherited Members
Public Types inherited from Concurrency::details::_Task_impl_base
enum	_TaskInternalState {   _Created, _Started, _PendingCancel, _Completed,   _Canceled }
typedef _ContinuationTaskHandleBase *	_ContinuationList
Static Public Member Functions inherited from Concurrency::details::_Task_impl_base
template<typename _ReturnType , typename _InternalReturnType >
static void	_AsyncInit (const typename _Task_ptr< _ReturnType >::_Type &_OuterTask, const task< _InternalReturnType > &_UnwrappedTask)

Detailed Description

template<typename _ReturnType>
struct Concurrency::details::_Task_impl< _ReturnType >

The implementation of a first-class task. This structure contains the task group used to execute the task function and handles the scheduling. The _Task_impl is created as a shared_ptr member of the the public task class, so its destruction is handled automatically.

Template Parameters

_ReturnType

The result type of this task.

Constructor & Destructor Documentation

template<typename _ReturnType >

Concurrency::details::_Task_impl< _ReturnType >::_Task_impl ( _CancellationTokenState *  _Ct, scheduler_ptr  _Scheduler_arg  )

inline

            : _Task_impl_base(_Ct, _Scheduler_arg)
        {
#if defined (__cplusplus_winrt)
            _M_unwrapped_async_op = nullptr;
#endif  /* defined (__cplusplus_winrt) */
        }

template<typename _ReturnType >

virtual Concurrency::details::_Task_impl< _ReturnType >::~_Task_impl ( )

inlinevirtual

        {
            // We must invoke _DeregisterCancellation in the derived class destructor. Calling it in the base class destructor could cause
            // a partially initialized _Task_impl to be in the list of registrations for a cancellation token.
            _DeregisterCancellation();
        }

Member Function Documentation

template<typename _ReturnType >

virtual bool Concurrency::details::_Task_impl< _ReturnType >::_CancelAndRunContinuations ( bool  _SynchronousCancel, bool  _UserException, bool  _PropagatedFromAncestor, const std::shared_ptr< _ExceptionHolder > &  _ExHolder  )

inlinevirtual

Requests cancellation on the task and schedules continuations if the task can be transitioned to a terminal state.

Parameters

_SynchronousCancel	Set to true if the cancel takes place as a result of the task body encountering an exception, or because an ancestor or task_completion_event the task was registered with were canceled with an exception. A synchronous cancel is one that assures the task could not be running on a different thread at the time the cancellation is in progress. An asynchronous cancel is one where the thread performing the cancel has no control over the thread that could be executing the task, that is the task could execute concurrently while the cancellation is in progress.
_UserException	Whether an exception other than the internal runtime cancellation exceptions caused this cancellation.
_PropagatedFromAncestor	Whether this exception came from an ancestor task or a task_completion_event as opposed to an exception that was encountered by the task itself. Only valid when _UserException is set to true.
_ExHolder	The exception holder that represents the exception. Only valid when _UserException is set to true.

Implements Concurrency::details::_Task_impl_base.

        {
            enum { _Nothing, _RunContinuations, _Cancel } _Do = _Nothing; 
            {
                ::Concurrency::extensibility::scoped_critical_section_t _LockHolder(_M_ContinuationsCritSec);
                if (_UserException)
                {
                    _ASSERTE(_SynchronousCancel && !_IsCompleted());
                    // If the state is _Canceled, the exception has to be coming from an ancestor.
                    _ASSERTE(!_IsCanceled() || _PropagatedFromAncestor);

                    // We should not be canceled with an exception more than once.
                    _ASSERTE(!_HasUserException());

                    if (_M_TaskState == _Canceled)
                    {
                        // If the task has finished cancelling there should not be any continuation records in the array.
                        return false;
                    }
                    else
                    {
                        _ASSERTE(_M_TaskState != _Completed);
                        _M_exceptionHolder = _ExceptionHolder_arg;
                    }
                }
                else
                {
                    // Completed is a non-cancellable state, and if this is an asynchronous cancel, we're unable to do better than the last async cancel
                    // which is to say, cancellation is already initiated, so return early.
                    if (_IsCompleted() || _IsCanceled() || (_IsPendingCancel() && !_SynchronousCancel))
                    {
                        _ASSERTE(!_IsCompleted() || !_HasUserException());
                        return false;
                    }
                    _ASSERTE(!_SynchronousCancel || !_HasUserException());
                }

                if (_SynchronousCancel)
                {
                    // Be aware that this set must be done BEFORE _M_Scheduled being set, or race will happen between this and wait()
                    _M_TaskState = _Canceled;                    
                    // Cancellation completes the task, so all dependent tasks must be run to cancel them
                    // They are canceled when they begin running (see _RunContinuation) and see that their
                    // ancestor has been canceled.
                    _Do = _RunContinuations;
                }
                else
                {
                    _ASSERTE(!_UserException);

                    if (_IsStarted())
                    {
                        // should not initiate cancellation under a lock
                        _Do = _Cancel;
                    }

                    // The _M_TaskState variable transitions to _Canceled when cancellation is completed (the task is not executing user code anymore).
                    // In the case of a synchronous cancel, this can happen immediately, whereas with an asynchronous cancel, the task has to move from
                    // _Started to _PendingCancel before it can move to _Canceled when it is finished executing.
                    _M_TaskState = _PendingCancel;

                    _M_taskEventLogger._LogCancelTask();
                }                
            }

            switch (_Do) 
            {
                case _Cancel:
                {
#if defined (__cplusplus_winrt)
                    if (_M_unwrapped_async_op != nullptr)
                    {
                        // We will only try to cancel async operation but not unwrapped tasks, since unwrapped tasks cannot be canceled without its token.
                        _M_unwrapped_async_op->Cancel();
                    }
#endif  /* defined (__cplusplus_winrt) */
                    _M_TaskCollection._Cancel();
                    break;
                }
                case _RunContinuations:
                {
                    // Only execute continuations and mark the task as completed if we were able to move the task to the _Canceled state.
                    _M_TaskCollection._Complete();

                    if (_M_Continuations)
                    {
                        // Scheduling cancellation with automatic inlining.
                        _ScheduleFuncWithAutoInline([=](){ _RunTaskContinuations(); }, details::_DefaultAutoInline);
                    }

                    break;
                }
            }
            return true;
        }

template<typename _ReturnType >

void Concurrency::details::_Task_impl< _ReturnType >::_FinalizeAndRunContinuations ( _ReturnType  _Result )

inline

        {
            _M_Result.Set(_Result);

            {
                //
                // Hold this lock to ensure continuations being concurrently either get added
                // to the _M_Continuations vector or wait for the result
                //
                ::Concurrency::extensibility::scoped_critical_section_t _LockHolder(_M_ContinuationsCritSec);

                // A task could still be in the _Created state if it was created with a task_completion_event.
                // It could also be in the _Canceled state for the same reason.
                _ASSERTE(!_HasUserException() && !_IsCompleted());
                if (_IsCanceled())
                {
                    return;
                }

                // Always transition to "completed" state, even in the face of unacknowledged pending cancellation
                _M_TaskState = _Completed;
            }
            _M_TaskCollection._Complete();
            _RunTaskContinuations();
        }

template<typename _ReturnType >

_ReturnType Concurrency::details::_Task_impl< _ReturnType >::_GetResult ( )

inline

        {
            return _M_Result.Get();
        }

template<typename _ReturnType >

bool Concurrency::details::_Task_impl< _ReturnType >::_IsDone ( )

inline

        {     
            return _IsCompleted() || _IsCanceled();
        }

template<typename _ReturnType >

bool Concurrency::details::_Task_impl< _ReturnType >::_TransitionedToStarted ( )

inline

        {
            ::Concurrency::extensibility::scoped_critical_section_t _LockHolder(_M_ContinuationsCritSec);
            // Canceled state could only result from antecedent task's canceled state, but that code path will not reach here.
            _ASSERT(!_IsCanceled());
            if (_IsPendingCancel())
                return false;

            _ASSERTE(_IsCreated());
            _M_TaskState = _Started;
            return true;
        }

Member Data Documentation

template<typename _ReturnType >

_ResultHolder<_ReturnType> Concurrency::details::_Task_impl< _ReturnType >::_M_Result

---

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

• VS2013/inc/ppltasks.h