Concurrency::task_completion_event< _ResultType > Class Template Reference

The task_completion_event class allows you to delay the execution of a task until a condition is satisfied, or start a task in response to an external event. More...

#include <ppltasks.h>

Public Member Functions
	task_completion_event ()
	Constructs a task_completion_event object. More...
bool	set (_ResultType _Result) const
	Sets the task completion event. More...
template<typename _E >
	__declspec (noinline) bool set_exception(_E _Except) const
	__declspec (noinline) bool set_exception(std
	Propagates an exception to all tasks associated with this event. More...
bool	_Cancel () const
	Internal method to cancel the task_completion_event. Any task created using this event will be marked as canceled if it has not already been set. More...
template<typename _ExHolderType >
bool	_Cancel (_ExHolderType _ExHolder, const details::_TaskCreationCallstack &_SetExceptionAddressHint=details::_TaskCreationCallstack()) const
	Internal method to cancel the task_completion_event with the exception provided. Any task created using this event will be canceled with the same exception. More...
template<typename _ExHolderType >
bool	_StoreException (_ExHolderType _ExHolder, const details::_TaskCreationCallstack &_SetExceptionAddressHint=details::_TaskCreationCallstack()) const
	Internal method that stores an exception in the task completion event. This is used internally by when_any. Note, this does not cancel the task completion event. A task completion event with a stored exception can bet set() successfully. If it is canceled, it will cancel with the stored exception, if one is present. More...
void	_ClearStoredException () const
	Internal method that observe and clear the exception stored in the task completion event. This is used internally by when_any. More...
bool	_IsTriggered () const
	Tests whether current event has been either Set, or Canceled. More...

Private Types
typedef details::_Task_completion_event_impl< _ResultType >::_TaskList	_TaskList

Private Member Functions
bool	_CancelInternal () const
	Cancels the task_completion_event. More...
void	_RegisterTask (const typename details::_Task_ptr< _ResultType >::_Type &_TaskParam)
	Register a task with this event. This function is called when a task is constructed using a task_completion_event. More...

Static Private Member Functions
static std::shared_ptr< details::_ExceptionHolder >	_ToExceptionHolder (const std::shared_ptr< details::_ExceptionHolder > &_ExHolder, const details::_TaskCreationCallstack &)
static std::shared_ptr< details::_ExceptionHolder >	_ToExceptionHolder (std::exception_ptr _ExceptionPtr, const details::_TaskCreationCallstack &_SetExceptionAddressHint)

Private Attributes
std::shared_ptr< details::_Task_completion_event_impl< _ResultType > >	_M_Impl

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

Detailed Description

template<typename _ResultType>
class Concurrency::task_completion_event< _ResultType >

The task_completion_event class allows you to delay the execution of a task until a condition is satisfied, or start a task in response to an external event.

Template Parameters

_ResultType

The result type of this task_completion_event class.

Use a task created from a task completion event when your scenario requires you to create a task that will complete, and thereby have its continuations scheduled for execution, at some point in the future. The task_completion_event must have the same type as the task you create, and calling the set method on the task completion event with a value of that type will cause the associated task to complete, and provide that value as a result to its continuations.

If the task completion event is never signaled, any tasks created from it will be canceled when it is destructed.

task_completion_event behaves like a smart pointer, and should be passed by value.

See also

task Class

Member Typedef Documentation

template<typename _ResultType>

typedef details::_Task_completion_event_impl<_ResultType>::_TaskList Concurrency::task_completion_event< _ResultType >::_TaskList

private

Constructor & Destructor Documentation

template<typename _ResultType>

Concurrency::task_completion_event< _ResultType >::task_completion_event ( )

inline

Constructs a task_completion_event object.

        : _M_Impl(std::make_shared<details::_Task_completion_event_impl<_ResultType>>())
    {
    }

Member Function Documentation

template<typename _ResultType>

template<typename _E >

Concurrency::task_completion_event< _ResultType >::__declspec ( noinline  ) const

inline

    {
        // It is important that _CAPTURE_CALLSTACK() evaluates to the instruction after the call instruction for set_exception.
        return _Cancel(std::make_exception_ptr(_Except), _CAPTURE_CALLSTACK());
    }

template<typename _ResultType>

Concurrency::task_completion_event< _ResultType >::__declspec ( noinline  )

inline

Propagates an exception to all tasks associated with this event.

The exception_ptr that indicates the exception to set this event with.

    {
        // It is important that _CAPTURE_CALLSTACK() evaluates to the instruction after the call instruction for set_exception.
        return _Cancel(_ExceptionPtr, _CAPTURE_CALLSTACK());
    }

template<typename _ResultType>

bool Concurrency::task_completion_event< _ResultType >::_Cancel ( ) const

inline

Internal method to cancel the task_completion_event. Any task created using this event will be marked as canceled if it has not already been set.

    {
        // Cancel with the stored exception if one exists.
        return _CancelInternal();
    }

template<typename _ResultType>

template<typename _ExHolderType >

bool Concurrency::task_completion_event< _ResultType >::_Cancel ( _ExHolderType  _ExHolder, const details::_TaskCreationCallstack &  _SetExceptionAddressHint = details::_TaskCreationCallstack ()  ) const

inline

Internal method to cancel the task_completion_event with the exception provided. Any task created using this event will be canceled with the same exception.

    {
        bool _Canceled;
        if(_StoreException(_ExHolder, _SetExceptionAddressHint))
        {
            _Canceled = _CancelInternal();
            _ASSERTE(_Canceled);
        }
        else
        {
            _Canceled = false;
        }
        return _Canceled;
    }

template<typename _ResultType>

bool Concurrency::task_completion_event< _ResultType >::_CancelInternal ( ) const

inlineprivate

Cancels the task_completion_event.

    {
        // Cancellation of task completion events is an internal only utility. Our usage is such that _CancelInternal
        // will never be invoked if the task completion event has been set.
        _ASSERTE(!_M_Impl->_M_fHasValue);
        if (_M_Impl->_M_fIsCanceled)
        {
            return false;
        }

        _TaskList _Tasks;
        bool _Cancel = false;
        {
            ::std::lock_guard<std::mutex> _LockHolder(_M_Impl->_M_taskListCritSec);
            _ASSERTE(!_M_Impl->_M_fHasValue);
            if (!_M_Impl->_M_fIsCanceled)
            {
                _M_Impl->_M_fIsCanceled = true;
                _Tasks.swap(_M_Impl->_M_tasks);
                _Cancel = true;
            }
        }

        bool _UserException = _M_Impl->_HasUserException();

        if (_Cancel)
        {
            for( auto _TaskIt = _Tasks.begin(); _TaskIt != _Tasks.end(); ++_TaskIt )
            {
                // Need to call this after the lock is released. See comments in set().
                if (_UserException)
                {
                    (*_TaskIt)->_CancelWithExceptionHolder(_M_Impl->_M_exceptionHolder, true);
                }
                else
                {
                    (*_TaskIt)->_Cancel(true);
                }
            }
        }
        return _Cancel;
    }

template<typename _ResultType>

void Concurrency::task_completion_event< _ResultType >::_ClearStoredException ( ) const

inline

Internal method that observe and clear the exception stored in the task completion event. This is used internally by when_any.

    {
        ::std::lock_guard<std::mutex> _LockHolder(_M_Impl->_M_taskListCritSec);
        if (_M_Impl->_M_exceptionHolder)
        {
            details::atomic_exchange(_M_Impl->_M_exceptionHolder->_M_exceptionObserved, 1l);
            _M_Impl->_M_exceptionHolder.reset();
        }
    }

template<typename _ResultType>

bool Concurrency::task_completion_event< _ResultType >::_IsTriggered ( ) const

inline

Tests whether current event has been either Set, or Canceled.

    {
        return _M_Impl->_M_fHasValue || _M_Impl->_M_fIsCanceled;
    }

template<typename _ResultType>

void Concurrency::task_completion_event< _ResultType >::_RegisterTask ( const typename details::_Task_ptr< _ResultType >::_Type &  _TaskParam )

inlineprivate

Register a task with this event. This function is called when a task is constructed using a task_completion_event.

    {
        enum { _Nothing, _Trigger, _Cancel } _Action = _Nothing;
        {
            ::std::lock_guard<std::mutex> _LockHolder(_M_Impl->_M_taskListCritSec);

            //If an exception was already set on this event, then cancel the task with the stored exception.
            if (_M_Impl->_HasUserException())
            {
                _Action = _Cancel;
            }
            else if (_M_Impl->_M_fHasValue)
            {
                _Action = _Trigger;
            }
            else
            {
                _M_Impl->_M_tasks.push_back(_TaskParam);
            }
        }

        switch (_Action)
        {
        case _Trigger:
            _TaskParam->_FinalizeAndRunContinuations(_M_Impl->_M_value.Get());
            break;
        case _Cancel:
            _TaskParam->_CancelWithExceptionHolder(_M_Impl->_M_exceptionHolder, true);
            break;
        case _Nothing:
        default:
            break;
        }
    }

template<typename _ResultType>

template<typename _ExHolderType >

bool Concurrency::task_completion_event< _ResultType >::_StoreException ( _ExHolderType  _ExHolder, const details::_TaskCreationCallstack &  _SetExceptionAddressHint = details::_TaskCreationCallstack ()  ) const

inline

Internal method that stores an exception in the task completion event. This is used internally by when_any. Note, this does not cancel the task completion event. A task completion event with a stored exception can bet set() successfully. If it is canceled, it will cancel with the stored exception, if one is present.

    {
        ::std::lock_guard<std::mutex> _LockHolder(_M_Impl->_M_taskListCritSec);
        if (!_IsTriggered() && !_M_Impl->_HasUserException())
        {
            // Create the exception holder only if we have ensured there we will be successful in setting it onto the
            // task completion event. Failing to do so will result in an unobserved task exception.
            _M_Impl->_M_exceptionHolder = _ToExceptionHolder(_ExHolder, _SetExceptionAddressHint);
            return true;
        }
        return false;
    }

template<typename _ResultType>

static std::shared_ptr<details::_ExceptionHolder> Concurrency::task_completion_event< _ResultType >::_ToExceptionHolder ( const std::shared_ptr< details::_ExceptionHolder > &  _ExHolder, const details::_TaskCreationCallstack &    )

inlinestaticprivate

    {
        return _ExHolder;
    }

template<typename _ResultType>

static std::shared_ptr<details::_ExceptionHolder> Concurrency::task_completion_event< _ResultType >::_ToExceptionHolder ( std::exception_ptr  _ExceptionPtr, const details::_TaskCreationCallstack &  _SetExceptionAddressHint  )

inlinestaticprivate

    {
        return std::make_shared<details::_ExceptionHolder>(_ExceptionPtr, _SetExceptionAddressHint);
    }

template<typename _ResultType>

bool Concurrency::task_completion_event< _ResultType >::set ( _ResultType  _Result ) const

inline

Sets the task completion event.

Parameters

_Result

The result to set this event with.

Returns

The method returns true if it was successful in setting the event. It returns false if the event is already set.

In the presence of multiple or concurrent calls to set, only the first call will succeed and its result (if any) will be stored in the task completion event. The remaining sets are ignored and the method will return false. When you set a task completion event, all the tasks created from that event will immediately complete, and its continuations, if any, will be scheduled. Task completion objects that have a _ResultType other than void will pass the value to their continuations.

    {
        // Subsequent sets are ignored. This makes races to set benign: the first setter wins and all others are ignored.
        if (_IsTriggered())
        {
            return false;
        }

        _TaskList _Tasks;
        bool _RunContinuations = false;
        {
            ::std::lock_guard<std::mutex> _LockHolder(_M_Impl->_M_taskListCritSec);

            if (!_IsTriggered())
            {
                _M_Impl->_M_value.Set(_Result);
                _M_Impl->_M_fHasValue = true;

                _Tasks.swap(_M_Impl->_M_tasks);
                _RunContinuations = true;
            }
        }

        if (_RunContinuations)
        {
            for( auto _TaskIt = _Tasks.begin(); _TaskIt != _Tasks.end(); ++_TaskIt )
            {
                // If current task was cancelled by a cancellation_token, it would be in cancel pending state.
                if ((*_TaskIt)->_IsPendingCancel())
                    (*_TaskIt)->_Cancel(true);
                else
                {
                    // Tasks created with task_completion_events can be marked as async, (we do this in when_any and when_all
                    // if one of the tasks involved is an async task). Since continuations of async tasks can execute inline, we
                    // need to run continuations after the lock is released.
                    (*_TaskIt)->_FinalizeAndRunContinuations(_M_Impl->_M_value.Get());
                }
            }

            return true;
        }

        return false;
    }

Friends And Related Function Documentation

template<typename _ResultType>

template<typename _Ty >

friend class task

friend

template<typename _ResultType>

template<typename _Ty >

friend class task_completion_event

friend

Member Data Documentation

template<typename _ResultType>

std::shared_ptr<details::_Task_completion_event_impl<_ResultType> > Concurrency::task_completion_event< _ResultType >::_M_Impl

private

---

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

• VS2017/inc/ppltasks.h