Structured task collections represent groups of work which follow a strictly LIFO ordered paradigm queueing and waiting respectively. They can only be waited on once and can only be used from a single thread of execution. More...

#include <concrt.h>

Inheritance diagram for Concurrency::details::_StructuredTaskCollection:

Public Member Functions
	_StructuredTaskCollection ()
	Construct a new structured task collection. More...

_CRTIMP	_StructuredTaskCollection (_CancellationTokenState *_PTokenState)
	Construct a new structured task collection whose cancellation is goverened by the supplied cancellation token. More...

_CRTIMP	~_StructuredTaskCollection ()
	Destruct a task collection and wait on all associated work to finish. Clients must call '_StructuredTaskCollection::_Wait' or '_StructuredTaskCollection::_RunAndWait' prior to destructing the object. If there are chores remaining in the queues, an exception (missing_wait) is thrown. If the destructor is running because of exception unwinding, it will abort any scheduled work. If another exception occurs because work is aborted, the process will terminate (C++ semantics). More...

_CRTIMP void	_Schedule (_UnrealizedChore _PChore, location _PLocation)
	Schedules a chore that can potentially run in parallel. The chore is pushed onto the associated workstealing queue, and will be executed in a LIFO order. Note that the specified chore can be scheduled only on a single task collection at a given time. Any attempt to schedule the same chore multiple times on one or more task collection will result in an invalid_multiple_scheduling exception. After the chore is guaranteed to have been executed (by calling the _Wait method), it can be rescheduled to an arbitrary task collection. More...

_CRTIMP void	_Schedule (_UnrealizedChore *_PChore)
	Schedules a chore that can potentially run in parallel. The chore is pushed onto the associated workstealing queue, and will be executed in a LIFO order. Note that the specified chore can be scheduled only on a single task collection at a given time. Any attempt to schedule the same chore multiple times on one or more task collection will result in an invalid_multiple_scheduling exception. After the chore is guaranteed to have been executed (by calling the _Wait method), it can be rescheduled to an arbitrary task collection. More...

_CRTIMP void	_Cancel ()
	Cancels work on the task collection. More...

_CRTIMP bool	_IsCanceling ()
	Informs the caller whether or not the task collection is currently in the midst of cancellation. Note that this does not necessarily indicate that Cancel was called on the collection (although such certainly qualifies this function to return true). It can be the case that the task collection is executing inline and a task collection further up in the work tree was canceled. In cases such as these where we can determine ahead of time that cancellation will flow through this collection, true will be returned as well. More...

_CRTIMP _TaskCollectionStatus __stdcall	_RunAndWait (_UnrealizedChore *_PChore=NULL)
	A cancellation friendly wrapper with which to execute _PChore and then waits for all chores running in the _StructuredTaskCollection to finish (normally or abnormally). This method encapsulates all the running tasks in an exception handling block, and will re-throw any exceptions that occur in any of it tasks (if those exceptions occur on another thread, they are marshaled from that thread to the thread where the _StructuredTaskCollection was created, and re-thrown). After this function returns, the _StructuredTaskCollection cannot be used for scheduling further work. More...

_TaskCollectionStatus	_Wait ()
	Waits for all chores running in the _StructuredTaskCollection to finish (normally or abnormally). This method encapsulates all the running tasks in an exception handling block, and will re-throw any exceptions that occur in any of it tasks (if those exceptions occur on another thread, they are marshaled from that thread to the thread where the _StructuredTaskCollection was created, and re-thrown). After this function returns, the _StructuredTaskCollection cannot be used for scheduling further work. More...

void	_CancelStolenContexts ()
	Called to cancel any contexts which stole chores from the given collection. More...

Public Member Functions inherited from Concurrency::details::_TaskCollectionBase
	_TaskCollectionBase ()

	_TaskCollectionBase (_CancellationTokenState *_PTokenState)

void *	_OwningContext () const

int	_InliningDepth () const

bool	_IsCurrentlyInlined () const

bool	_IsStructured ()

_CancellationTokenState *	_GetTokenState (_CancellationTokenRegistration **_PRegistration=NULL)

Private Member Functions
void	_Construct ()

_CRTIMP void	_Abort ()
	Internal routine to abort work on the task collection. More...

_CRTIMP void	_CleanupToken ()
	Internal routine to clean up after a cancellation token. More...

bool	_TaskCleanup ()
	Performs task cleanup normally done at destruction time. More...

void	_Initialize ()
	Internal initialization of the structured task collection More...

void	_WaitOnStolenChores (long _StolenChoreCount)
	Waits on a specified number of stolen chores. More...

void	_CountUp ()
	Indicates that a stolen chore has completed. More...

Static Private Member Functions
static void __cdecl	_CancelViaToken (_StructuredTaskCollection *pCollection)
	The callback which is made when a cancellation occurs via a token associated with a structured_task_group on the boundary of two cancellation tokens. More...

Private Attributes
_CONCRT_BUFFER	_M_event [(sizeof(void *)+sizeof(_CONCRT_BUFFER)-1)/sizeof(_CONCRT_BUFFER)]

Friends
class	_UnrealizedChore

Additional Inherited Members
Protected Types inherited from Concurrency::details::_TaskCollectionBase
enum	_TaskCollectionBaseState { _CollectionNotInitialized = LONG_MIN, _CollectionInitializationInProgress = LONG_MIN+1, _CollectionInitialized = 0 }

Protected Member Functions inherited from Concurrency::details::_TaskCollectionBase
std::exception_ptr *	_Exception () const

bool	_IsAbnormalExit () const

size_t	_CancelState () const

bool	_IsMarkedForCancellation () const

bool	_PerformedInlineCancel () const

bool	_PerformedPendingCancel () const

_TaskCollectionBase *	_SafeGetParent ()

bool	_WillInterruptForPendingCancel ()

void	_RaisedException ()

void	_RethrowException ()

bool	_MarkCancellation ()

void	_FinishCancelState (size_t _NewCancelState)

void	_RaisedCancel ()

Protected Attributes inherited from Concurrency::details::_TaskCollectionBase
_TaskCollectionBase *	_M_pParent

int	_M_inliningDepth: 28

int	_M_inlineFlags: 4

_CancellationTokenState *	_M_pTokenState

void *	_M_pOwningContext

long	_M_unpoppedChores

volatile long	_M_completedStolenChores

std::exception_ptr *	_M_pException

Static Protected Attributes inherited from Concurrency::details::_TaskCollectionBase
static const size_t	_S_cancelBitsMask = 0x3

static const size_t	_S_cancelNone = 0x0

static const size_t	_S_cancelStarted = 0x1

static const size_t	_S_cancelDeferredShootdownOwner = 0x2

static const size_t	_S_cancelShotdownOwner = 0x3

static const size_t	_S_nonNull = 0x8

static const size_t	_S_cancelException = 0xC

static const int	_S_notInlined = -1

static const int	_S_structured = 0x00000001

static const int	_S_localCancel = 0x00000002

static const int	_S_reserved = 0x0000000C

Detailed Description

Structured task collections represent groups of work which follow a strictly LIFO ordered paradigm queueing and waiting respectively. They can only be waited on once and can only be used from a single thread of execution.

Constructor & Destructor Documentation

Concurrency::details::_StructuredTaskCollection::_StructuredTaskCollection ( )

inline

Construct a new structured task collection.

         {
             _Construct();
             _M_pTokenState = NULL;
         }

_CRTIMP Concurrency::details::_StructuredTaskCollection::_StructuredTaskCollection ( _CancellationTokenState * _PTokenState )

Construct a new structured task collection whose cancellation is goverened by the supplied cancellation token.

Parameters

_PTokenState When this cancellation token is canceled, the structured task group will be canceled.

_CRTIMP Concurrency::details::_StructuredTaskCollection::~_StructuredTaskCollection ( )

Destruct a task collection and wait on all associated work to finish. Clients must call '_StructuredTaskCollection::_Wait' or '_StructuredTaskCollection::_RunAndWait' prior to destructing the object. If there are chores remaining in the queues, an exception (missing_wait) is thrown. If the destructor is running because of exception unwinding, it will abort any scheduled work. If another exception occurs because work is aborted, the process will terminate (C++ semantics).

Member Function Documentation

_CRTIMP void Concurrency::details::_StructuredTaskCollection::_Abort ( )

private

Internal routine to abort work on the task collection.

_CRTIMP void Concurrency::details::_StructuredTaskCollection::_Cancel ( )

Cancels work on the task collection.

void Concurrency::details::_StructuredTaskCollection::_CancelStolenContexts ( )

Called to cancel any contexts which stole chores from the given collection.

static void __cdecl Concurrency::details::_StructuredTaskCollection::_CancelViaToken ( _StructuredTaskCollection * pCollection )

staticprivate

The callback which is made when a cancellation occurs via a token associated with a structured_task_group on the boundary of two cancellation tokens.

_CRTIMP void Concurrency::details::_StructuredTaskCollection::_CleanupToken ( )

private

Internal routine to clean up after a cancellation token.

void Concurrency::details::_StructuredTaskCollection::_Construct ( )

inlineprivate

         {
             _M_pOwningContext = NULL;
             _M_inlineFlags = _S_structured;
         }

void Concurrency::details::_StructuredTaskCollection::_CountUp ( )

private

Indicates that a stolen chore has completed.

void Concurrency::details::_StructuredTaskCollection::_Initialize ( )

private

Internal initialization of the structured task collection

_CRTIMP bool Concurrency::details::_StructuredTaskCollection::_IsCanceling ( )

Informs the caller whether or not the task collection is currently in the midst of cancellation. Note that this does not necessarily indicate that Cancel was called on the collection (although such certainly qualifies this function to return true). It can be the case that the task collection is executing inline and a task collection further up in the work tree was canceled. In cases such as these where we can determine ahead of time that cancellation will flow through this collection, true will be returned as well.

Returns: An indication of whether the task collection is in the midst of a cancellation (or is guaranteed to be shortly).

_CRTIMP _TaskCollectionStatus __stdcall Concurrency::details::_StructuredTaskCollection::_RunAndWait ( _UnrealizedChore * _PChore = NULL )

A cancellation friendly wrapper with which to execute _PChore and then waits for all chores running in the _StructuredTaskCollection to finish (normally or abnormally). This method encapsulates all the running tasks in an exception handling block, and will re-throw any exceptions that occur in any of it tasks (if those exceptions occur on another thread, they are marshaled from that thread to the thread where the _StructuredTaskCollection was created, and re-thrown). After this function returns, the _StructuredTaskCollection cannot be used for scheduling further work.

Parameters

_PChore An _UnrealizedChore which when non-null will be called to invoke the chore in a cancellation friendly manner.

Returns: An indication of the status of the wait.

_CRTIMP void Concurrency::details::_StructuredTaskCollection::_Schedule	(	_UnrealizedChore *	_PChore,
		location *	_PLocation
	)

Schedules a chore that can potentially run in parallel. The chore is pushed onto the associated workstealing queue, and will be executed in a LIFO order. Note that the specified chore can be scheduled only on a single task collection at a given time. Any attempt to schedule the same chore multiple times on one or more task collection will result in an invalid_multiple_scheduling exception. After the chore is guaranteed to have been executed (by calling the _Wait method), it can be rescheduled to an arbitrary task collection.

Parameters

_PChore	The new unrealized chore to schedule
_PLocation	The location where the unrealized chore should execute. Specifying the value NULL here indicates that the unrealized chore does not have specific placement.

_CRTIMP void Concurrency::details::_StructuredTaskCollection::_Schedule ( _UnrealizedChore * _PChore )

Schedules a chore that can potentially run in parallel. The chore is pushed onto the associated workstealing queue, and will be executed in a LIFO order. Note that the specified chore can be scheduled only on a single task collection at a given time. Any attempt to schedule the same chore multiple times on one or more task collection will result in an invalid_multiple_scheduling exception. After the chore is guaranteed to have been executed (by calling the _Wait method), it can be rescheduled to an arbitrary task collection.

Parameters

_PChore The new unrealized chore to schedule

bool Concurrency::details::_StructuredTaskCollection::_TaskCleanup ( )

inlineprivate

Performs task cleanup normally done at destruction time.

         {
             //
             // Users are required to call Wait() before letting the destructor run. Otherwise, throw. Note that before throwing,
             // we must actually wait on the tasks because they contain pointers into stack frames and unwinding without the wait is
             // instant stack corruption.
             //
             if (_M_unpoppedChores > 0)
             {
                 _Abort();
 
                 if (!__uncaught_exception())
                 {
                     return false;
                 }
             }
 
             return true;
         }

_TaskCollectionStatus Concurrency::details::_StructuredTaskCollection::_Wait ( )

inline

Waits for all chores running in the _StructuredTaskCollection to finish (normally or abnormally). This method encapsulates all the running tasks in an exception handling block, and will re-throw any exceptions that occur in any of it tasks (if those exceptions occur on another thread, they are marshaled from that thread to the thread where the _StructuredTaskCollection was created, and re-thrown). After this function returns, the _StructuredTaskCollection cannot be used for scheduling further work.

Returns: An indication of the status of the wait.

         {
             return _RunAndWait();
         }

void Concurrency::details::_StructuredTaskCollection::_WaitOnStolenChores ( long _StolenChoreCount )

private

Waits on a specified number of stolen chores.

Parameters

_StolenChoreCount The number of stolen chores to wait on.

Friends And Related Function Documentation

friend class _UnrealizedChore

friend

Member Data Documentation

_CONCRT_BUFFER Concurrency::details::_StructuredTaskCollection::_M_event[(sizeof(void *)+sizeof(_CONCRT_BUFFER)-1)/sizeof(_CONCRT_BUFFER)]

private

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

VS2013/inc/concrt.h

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation