Task collections represent groups of work which step outside the strict structuring of the _StructuredTaskCollection definition. Any groups of work which do not follow LIFO ordering, are waited on multiple times, or are passed between arbitrary threads require utilization of this definition of a task collection. It has additional overhead over the _StructuredTaskCollection. More...

#include <concrt.h>

Inheritance diagram for Concurrency::details::_TaskCollection:

Public Member Functions
_CONCRTIMP	_TaskCollection ()
	Constructs a new task collection. More...

	_TaskCollection (const _TaskCollection &)=delete

_TaskCollection &	operator= (const _TaskCollection &)=delete

_CONCRTIMP	_TaskCollection (_CancellationTokenState *_PTokenState)
	Constructs a new task collection whose cancellation is governed by the specified cancellation token state. More...

_CONCRTIMP	~_TaskCollection ()
	Destroys a task collection. Clients must call '_TaskCollection::_Wait' or '_TaskCollection::_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...

_CONCRTIMP 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. The tasks scheduled into a _TaskCollection are scheduled into the current scheduler. 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 collections 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...

_CONCRTIMP 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. The tasks scheduled into a _TaskCollection are scheduled into the current scheduler. 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 collections 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...

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

_CONCRTIMP bool	_IsCanceling ()
	Informs the caller whether or not the task collection is currently in the midst of a 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...

_CONCRTIMP _TaskCollectionStatus __stdcall	_RunAndWait (_UnrealizedChore *_PChore=NULL)
	A cancellation friendly wrapper with which to execute _PChore and then waits for all chores running in the _TaskCollection 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 _TaskCollection was created, and re-thrown). After this function returns, the _TaskCollection cannot be used for scheduling further work. More...

_TaskCollectionStatus	_Wait ()
	Waits for all chores running in the _TaskCollection 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 _TaskCollection was created, and re-thrown). After this function returns, the _TaskCollection cannot be used for scheduling further work. More...

bool	_IsMarkedForAbnormalExit () const
	Returns whether this task collection is marked for abnormal exit. More...

_TaskCollection *	_OriginalCollection () const
	Returns the object which this is an alias for. More...

bool	_IsAlias () const
	Returns whether the task collection is an alias. More...

void	_RegisterCompletionHandler (TaskProc _Func, void *_PCompletionContext)
	Registers a notification handler for completion of chores More...

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

	_TaskCollectionBase (const _TaskCollectionBase &)=delete

	_TaskCollectionBase (_CancellationTokenState *_PTokenState)

_TaskCollectionBase &	operator= (const _TaskCollectionBase &)=delete

void *	_OwningContext () const

int	_InliningDepth () const

bool	_IsCurrentlyInlined () const

bool	_IsStructured ()

_CancellationTokenState *	_GetTokenState (_CancellationTokenRegistration **_PRegistration=NULL)

Private Member Functions
bool	_IsStaleAlias () const
	Determines if the task collection is a stale alias (an object which was left over from a deferred delete of a direct alias but which happens to match the hash key for a newly allocated task collection) More...

void	_ReleaseAlias ()
	Releases an alias – this will free it if the release is the last man out. More...

	_TaskCollection (_TaskCollection *_POriginCollection, bool _FDirectAlias)
	Constructs an alias collection based on a specified origin collection More...

_TaskCollection *	_Alias ()
	Returns the local alias of a task collection on the current context. More...

void	_Abort (bool _FLeaveCanceled=false)
	Internal routine to abort work on the task collection. More...

bool	_IsIndirectAlias () const
	Returns whether the task collection is an indirect alias. More...

bool	_IsDirectAlias () const
	Returns whether the task collection is a direct alias. More...

bool	_HasDirectAlias () const
	Returns whether this task collection has a direct alias. More...

void	_Cancel (bool _InsideException, _TaskCollection *_PSnapPoint)
	Cancels work on the task collection. This is an internal version. More...

void	_NotifyNewChore ()
	Called for every new chore put into the task collection. Assures appropriate synchronization with waiters. More...

void	_NotifyCompletedChoreAndFree (_UnrealizedChore *_PChore=NULL)
	Called for every completed chore from the task collection. Assures appropriate synchronization with waiters. More...

void	_FullAliasWait (_TaskCollection *_PSnapPoint)
	Waits on the given task collection and every alias. More...

void	_Reset (_TaskCollection *_PSnapPoint)
	Resets the task collection for future usage. More...

void	_RaisedException ()
	Called when an exception is raised on a chore on an unstructured task collection, this makes a determination of what to do with the exception and saves it for potential transport back to the thread performing a join on a task collection. This specifically handles situations on for unstructured task collections before calling _TaskCollectionBase::_RaisedException. More...

void	_RaisedCancel ()
	Called when a cancellation is raised on a chore on a given task collection. This makes a determination of what to do with the exception and saves it for potential transport back to the thread performing a join on a chore collection. Note that every other exception has precedence over a cancellation. More...

bool	_SetCancelState (long _Status)
	Called in order to set the cancellation status of the collection. More...

void	_CancelFromArbitraryThread (bool _InsideException)
	Called to cancel a single alias of a task collection from an arbitrary thread. More...

void	_CancelDirectAliases (bool _InsideException, _TaskCollection *_PSnapPoint)
	Cancels all direct aliases of the task collection. More...

void	_CancelStolenContexts (bool _InsideException, bool _FInlineGated)
	Called to cancel any contexts which stole chores from the given collection. This is PART of a cancellation scheme. The remainder must be handled by the derived class in particular. This should be called last. More...

void *	_GetStealTrackingList () const
	Returns the steal tracking list. More...

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

void	_AbortiveSweep (void *_PCtx)
	Performs an abortive sweep of the WSQ for inline stack overflow. More...

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

Static Private Member Functions
static bool __cdecl	_CollectionMatchPredicate (_UnrealizedChore _PChore, void _PData)
	A predicate function checking whether a given chore belongs to a given collection. More...

static bool __cdecl	_SweepAbortedChore (_UnrealizedChore _PChore, void _PData)
	Called to sweep an aborted chore in the case of inline stack overflow. More...

static void __cdecl	_CancelViaToken (_TaskCollection *_PCollection)
	Called when the task collection is canceled via a cancellation token. More...

Private Attributes
_CONCRT_BUFFER	_M_stealTracker [_SAFERWLIST_SIZE]
	Tracks contexts that have stolen chores from this collection. This is storage for an internal list and lock. Note that this list is only used for detached schedule groups. More...

long	_M_activeStealersForCancellation
	A count of active stealers for CANCELLATION PURPOSES ONLY. This is non-interlocked and guarded by the same lock as the stealers list on this task collection. More...

volatile long	_M_exitCode
	An indication of the exit code of the chore. Anything non-zero here indicates cancellation of one form or another. More...

volatile long	_M_executionStatus
	The status of the task collection. More...

event	_M_event
	An event on which to wait for stolen chores to complete. More...

_TaskCollection *	_M_pOriginalCollection

_TaskCollection *	_M_pNextAlias

void *	_M_pTaskExtension

int	_M_taskCookies [2]

volatile long	_M_flags

volatile long	_M_chaining

DWORD	_M_boundQueueId

int	_M_stackPos

TaskProc	_M_completionHandler

void *	_M_pCompletionContext

Friends
class	_UnrealizedChore

class	::Concurrency::details::ContextBase

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

Task collections represent groups of work which step outside the strict structuring of the _StructuredTaskCollection definition. Any groups of work which do not follow LIFO ordering, are waited on multiple times, or are passed between arbitrary threads require utilization of this definition of a task collection. It has additional overhead over the _StructuredTaskCollection.

Constructor & Destructor Documentation

_CONCRTIMP Concurrency::details::_TaskCollection::_TaskCollection ( )

Constructs a new task collection.

Concurrency::details::_TaskCollection::_TaskCollection ( const _TaskCollection & )

delete

_CONCRTIMP Concurrency::details::_TaskCollection::_TaskCollection ( _CancellationTokenState * _PTokenState )

Constructs a new task collection whose cancellation is governed by the specified cancellation token state.

Parameters

_PTokenState When this cancellation token is canceled, the task collection is canceled.

_CONCRTIMP Concurrency::details::_TaskCollection::~_TaskCollection ( )

Destroys a task collection. Clients must call '_TaskCollection::_Wait' or '_TaskCollection::_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).

Concurrency::details::_TaskCollection::_TaskCollection	(	_TaskCollection *	_POriginCollection,
		bool	_FDirectAlias
	)

private

Constructs an alias collection based on a specified origin collection

Parameters

_POriginCollection	Specifies which collection the newly constructed one will alias
_FDirectAlias	Specifies whether the newly constructed collection is a direct alias

Member Function Documentation

void Concurrency::details::_TaskCollection::_Abort ( bool _FLeaveCanceled = false )

private

Internal routine to abort work on the task collection.

Parameters

_FLeaveCanceled An indication as to whether or not to leave the task collection canceled after the abort.

void Concurrency::details::_TaskCollection::_AbortiveSweep ( void * _PCtx )

private

Performs an abortive sweep of the WSQ for inline stack overflow.

Parameters

_PCtx The context to sweep

_TaskCollection* Concurrency::details::_TaskCollection::_Alias ( )

private

Returns the local alias of a task collection on the current context.

_CONCRTIMP void Concurrency::details::_TaskCollection::_Cancel ( )

Cancels work on the task collection.

void Concurrency::details::_TaskCollection::_Cancel	(	bool	_InsideException,
		_TaskCollection *	_PSnapPoint
	)

private

Cancels work on the task collection. This is an internal version.

Parameters

_InsideException	Indicates whether the cancellation is taking place because of exception unwinding within the runtime
_PSnapPoint	A snapshot of the direct alias list which is what the call will effect

void Concurrency::details::_TaskCollection::_CancelDirectAliases	(	bool	_InsideException,
		_TaskCollection *	_PSnapPoint
	)

private

Cancels all direct aliases of the task collection.

Parameters

_InsideException	Indicates whether the cancellation is taking place because of exception unwinding within the runtime
_PSnapPoint	A snapshot of the direct alias list which is what the call will effect

void Concurrency::details::_TaskCollection::_CancelFromArbitraryThread ( bool _InsideException )

private

Called to cancel a single alias of a task collection from an arbitrary thread.

Parameters

_InsideException Indicates whether the cancellation is taking place because of exception unwinding within the runtime

void Concurrency::details::_TaskCollection::_CancelStolenContexts	(	bool	_InsideException,
		bool	_FInlineGated
	)

private

Called to cancel any contexts which stole chores from the given collection. This is PART of a cancellation scheme. The remainder must be handled by the derived class in particular. This should be called last.

Parameters

_InsideException	Indicates whether the cancellation is taking place because of exception unwinding within the runtime
_FInlineGated	Indicates whether the inline context is safe and blocked from becoming inaccessible during the duration of the call

static void __cdecl Concurrency::details::_TaskCollection::_CancelViaToken ( _TaskCollection * _PCollection )

staticprivate

Called when the task collection is canceled via a cancellation token.

static bool __cdecl Concurrency::details::_TaskCollection::_CollectionMatchPredicate	(	_UnrealizedChore *	_PChore,
		void *	_PData
	)

staticprivate

A predicate function checking whether a given chore belongs to a given collection.

Parameters

_PChore	The chore to check
_PData	The data to check against

Returns: Whether or not the chore belongs to the collection

void Concurrency::details::_TaskCollection::_FullAliasWait ( _TaskCollection * _PSnapPoint )

private

Waits on the given task collection and every alias.

Parameters

_PSnapPoint A snapshot of the direct alias list which is what the call will effect

void* Concurrency::details::_TaskCollection::_GetStealTrackingList ( ) const

private

Returns the steal tracking list.

bool Concurrency::details::_TaskCollection::_HasDirectAlias ( ) const

private

Returns whether this task collection has a direct alias.

void Concurrency::details::_TaskCollection::_Initialize ( )

private

Internal initialization of the task collection

bool Concurrency::details::_TaskCollection::_IsAlias ( ) const

Returns whether the task collection is an alias.

_CONCRTIMP bool Concurrency::details::_TaskCollection::_IsCanceling ( )

Informs the caller whether or not the task collection is currently in the midst of a 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).

bool Concurrency::details::_TaskCollection::_IsDirectAlias ( ) const

private

Returns whether the task collection is a direct alias.

bool Concurrency::details::_TaskCollection::_IsIndirectAlias ( ) const

private

Returns whether the task collection is an indirect alias.

bool Concurrency::details::_TaskCollection::_IsMarkedForAbnormalExit ( ) const

Returns whether this task collection is marked for abnormal exit.

bool Concurrency::details::_TaskCollection::_IsStaleAlias ( ) const

private

Determines if the task collection is a stale alias (an object which was left over from a deferred delete of a direct alias but which happens to match the hash key for a newly allocated task collection)

void Concurrency::details::_TaskCollection::_NotifyCompletedChoreAndFree ( _UnrealizedChore * _PChore = NULL )

private

Called for every completed chore from the task collection. Assures appropriate synchronization with waiters.

Parameters

_PChore An _UnrealizedChore which will be freed if its lifetime is owned by the Runtime.

void Concurrency::details::_TaskCollection::_NotifyNewChore ( )

private

Called for every new chore put into the task collection. Assures appropriate synchronization with waiters.

_TaskCollection* Concurrency::details::_TaskCollection::_OriginalCollection ( ) const

Returns the object which this is an alias for.

void Concurrency::details::_TaskCollection::_RaisedCancel ( )

private

Called when a cancellation is raised on a chore on a given task collection. This makes a determination of what to do with the exception and saves it for potential transport back to the thread performing a join on a chore collection. Note that every other exception has precedence over a cancellation.

void Concurrency::details::_TaskCollection::_RaisedException ( )

private

Called when an exception is raised on a chore on an unstructured task collection, this makes a determination of what to do with the exception and saves it for potential transport back to the thread performing a join on a task collection. This specifically handles situations on for unstructured task collections before calling _TaskCollectionBase::_RaisedException.

void Concurrency::details::_TaskCollection::_RegisterCompletionHandler	(	TaskProc	_Func,
		void *	_PCompletionContext
	)

Registers a notification handler for completion of chores

Parameters

_Func	The callback function
_PCompletionContext	The completion context for the callback function

void Concurrency::details::_TaskCollection::_ReleaseAlias ( )

private

Releases an alias – this will free it if the release is the last man out.

void Concurrency::details::_TaskCollection::_Reset ( _TaskCollection * _PSnapPoint )

private

Resets the task collection for future usage.

Parameters

_PSnapPoint A snapshot of the direct alias list which is what the call will effect

_CONCRTIMP _TaskCollectionStatus __stdcall Concurrency::details::_TaskCollection::_RunAndWait ( _UnrealizedChore * _PChore = NULL )

A cancellation friendly wrapper with which to execute _PChore and then waits for all chores running in the _TaskCollection 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 _TaskCollection was created, and re-thrown). After this function returns, the _TaskCollection 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.

_CONCRTIMP void Concurrency::details::_TaskCollection::_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. The tasks scheduled into a _TaskCollection are scheduled into the current scheduler. 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 collections 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.

_CONCRTIMP void Concurrency::details::_TaskCollection::_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. The tasks scheduled into a _TaskCollection are scheduled into the current scheduler. 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 collections 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::_TaskCollection::_SetCancelState ( long _Status )

private

Called in order to set the cancellation status of the collection.

Parameters

_Status The cancellation status to set

Returns: An indication of whether the set succeeded. The set will fail if the task collection already has a cancellation status.

static bool __cdecl Concurrency::details::_TaskCollection::_SweepAbortedChore	(	_UnrealizedChore *	_PChore,
		void *	_PData
	)

staticprivate

Called to sweep an aborted chore in the case of inline stack overflow.

Parameters

_PChore	The chore to sweep
_PData	The data that was passed to the sweep predicate

Returns: An indication of whether the chore is now gone

bool Concurrency::details::_TaskCollection::_TaskCleanup ( bool _FExceptional )

private

Performs task cleanup normally done at destruction time.

Parameters

_FExceptional An indication if the cleanup is exceptional and the collection should be left in a canceled state.

_TaskCollectionStatus Concurrency::details::_TaskCollection::_Wait ( )

inline

Waits for all chores running in the _TaskCollection 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 _TaskCollection was created, and re-thrown). After this function returns, the _TaskCollection cannot be used for scheduling further work.

Returns: An indication of the status of the wait.

         {
             return _RunAndWait();
         }

_TaskCollection& Concurrency::details::_TaskCollection::operator= ( const _TaskCollection & )

delete

Friends And Related Function Documentation

friend class ::Concurrency::details::ContextBase

friend

friend class _UnrealizedChore

friend

Member Data Documentation

long Concurrency::details::_TaskCollection::_M_activeStealersForCancellation

private

A count of active stealers for CANCELLATION PURPOSES ONLY. This is non-interlocked and guarded by the same lock as the stealers list on this task collection.

DWORD Concurrency::details::_TaskCollection::_M_boundQueueId

private

volatile long Concurrency::details::_TaskCollection::_M_chaining

private

TaskProc Concurrency::details::_TaskCollection::_M_completionHandler

private

event Concurrency::details::_TaskCollection::_M_event

private

An event on which to wait for stolen chores to complete.

volatile long Concurrency::details::_TaskCollection::_M_executionStatus

private

The status of the task collection.

volatile long Concurrency::details::_TaskCollection::_M_exitCode

private

An indication of the exit code of the chore. Anything non-zero here indicates cancellation of one form or another.

volatile long Concurrency::details::_TaskCollection::_M_flags

private

void* Concurrency::details::_TaskCollection::_M_pCompletionContext

private

_TaskCollection* Concurrency::details::_TaskCollection::_M_pNextAlias

private

_TaskCollection* Concurrency::details::_TaskCollection::_M_pOriginalCollection

private

void* Concurrency::details::_TaskCollection::_M_pTaskExtension

private

int Concurrency::details::_TaskCollection::_M_stackPos

private

_CONCRT_BUFFER Concurrency::details::_TaskCollection::_M_stealTracker[_SAFERWLIST_SIZE]

private

Tracks contexts that have stolen chores from this collection. This is storage for an internal list and lock. Note that this list is only used for detached schedule groups.

int Concurrency::details::_TaskCollection::_M_taskCookies[2]

private

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

VS2015/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