The structured_task_group class represents a highly structured collection of parallel work. You can queue individual parallel tasks to a structured_task_group using task_handle objects, and wait for them to complete, or cancel the task group before they have finished executing, which will abort any tasks that have not begun execution. More...

#include <ppl.h>

Public Member Functions
	structured_task_group ()
	Constructs a new `structured_task_group` object. More...

	structured_task_group (cancellation_token _CancellationToken)
	Constructs a new `structured_task_group` object. More...

	~structured_task_group ()
	Destroys a `structured_task_group` object. You are expected to call either the `wait` or `run_and_wait` method on the object prior to the destructor executing, unless the destructor is executing as a result of stack unwinding due to an exception. More...

template<class _Function >
void	run (task_handle< _Function > &_Task_handle)
	Schedules a task on the `structured_task_group` object. The caller manages the lifetime of the `task_handle` object passed in the _Task_handle parameter. The version that takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter. More...

template<class _Function >
void	run (task_handle< _Function > &_Task_handle, location &_Placement)
	Schedules a task on the `structured_task_group` object. The caller manages the lifetime of the `task_handle` object passed in the _Task_handle parameter. The version that takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter. More...

task_group_status	wait ()
	Waits until all work on the `structured_task_group` has completed or is canceled. More...

template<class _Function >
task_group_status	run_and_wait (task_handle< _Function > &_Task_handle)
	Schedules a task to be run inline on the calling context with the assistance of the `structured_task_group` object for full cancellation support. If a `task_handle` object is passed as a parameter to `run_and_wait`, the caller is responsible for managing the lifetime of the `task_handle` object. The function then waits until all work on the `structured_task_group` object has either completed or been canceled. More...

template<class _Function >
task_group_status	run_and_wait (const _Function &_Func)
	Schedules a task to be run inline on the calling context with the assistance of the `structured_task_group` object for full cancellation support. If a `task_handle` object is passed as a parameter to `run_and_wait`, the caller is responsible for managing the lifetime of the `task_handle` object. The function then waits until all work on the `structured_task_group` object has either completed or been canceled. More...

void	cancel ()
	Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Every task scheduled on the task group will get canceled transitively if possible. More...

bool	is_canceling ()
	Informs the caller whether or not the task group is currently in the midst of a cancellation. This does not necessarily indicate that the `cancel` method was called on the `structured_task_group` object (although such certainly qualifies this method to return `true`). It may be the case that the `structured_task_group` object is executing inline and a task group further up in the work tree was canceled. In cases such as these where the runtime can determine ahead of time that cancellation will flow through this `structured_task_group` object, `true` will be returned as well. More...

Private Member Functions
template<class _Function >
void	run (task_handle< _Function > &&_Task_handle)

Private Attributes
::Concurrency::details::_StructuredTaskCollection	_M_task_collection

Detailed Description

The structured_task_group class represents a highly structured collection of parallel work. You can queue individual parallel tasks to a structured_task_group using task_handle objects, and wait for them to complete, or cancel the task group before they have finished executing, which will abort any tasks that have not begun execution.

There are a number of severe restrictions placed on usage of a structured_task_group object in order to gain performance:

A single structured_task_group object cannot be used by multiple threads. All operations on a structured_task_group object must be performed by the thread that created the object. The two exceptions to this rule are the member functions cancel and is_canceling. The object may not be in the capture list of a lambda expression and be used within a task, unless the task is using one of the cancellation operations.
All tasks scheduled to a structured_task_group object are scheduled through the use of task_handle objects which you must explicitly manage the lifetime of.
Multiple groups may only be used in absolutely nested order. If two structured_task_group objects are declared, the second one being declared (the inner one) must destruct before any method except cancel or is_canceling is called on the first one (the outer one). This condition holds true in both the case of simply declaring multiple structured_task_group objects within the same or functionally nested scopes as well as the case of a task that was queued to the structured_task_group via the run or run_and_wait methods.
Unlike the general task_group class, all states in the structured_task_group class are final. After you have queued tasks to the group and waited for them to complete, you may not use the same group again.

For more information, see Task Parallelism.

See also: task_group Class, task_handle Class

Constructor & Destructor Documentation

Concurrency::structured_task_group::structured_task_group ( )

inline

Constructs a new structured_task_group object.

The constructor that takes a cancellation token creates a structured_task_group that will be canceled when the source associated with the token is canceled. Providing an explicit cancellation token also isolates this structured task group from participating in an implicit cancellation from a parent group with a different token or no token.

See also: Task Parallelism

219 {

220 }

Concurrency::structured_task_group::structured_task_group ( cancellation_token _CancellationToken )

inline

Constructs a new structured_task_group object.

Parameters

_CancellationToken A cancellation token to associate with this structured task group. The structured task group will be canceled when the token is canceled.

The constructor that takes a cancellation token creates a structured_task_group that will be canceled when the source associated with the token is canceled. Providing an explicit cancellation token also isolates this structured task group from participating in an implicit cancellation from a parent group with a different token or no token.

See also: Task Parallelism

                                                                  :
         _M_task_collection(_CancellationToken._GetImpl() != NULL ? _CancellationToken._GetImpl() : Concurrency::details::_CancellationTokenState::_None())
     {
     }

Concurrency::structured_task_group::~structured_task_group ( )

inline

Destroys a structured_task_group object. You are expected to call either the wait or run_and_wait method on the object prior to the destructor executing, unless the destructor is executing as a result of stack unwinding due to an exception.

If the destructor runs as the result of normal execution (for example, not stack unwinding due to an exception) and neither the wait nor run_and_wait methods have been called, the destructor may throw a missing_wait exception.

See also: structured_task_group::wait Method, structured_task_group::run_and_wait Method

252 {

253 }

Member Function Documentation

void Concurrency::structured_task_group::cancel ( )

inline

Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Every task scheduled on the task group will get canceled transitively if possible.

For more information, see Cancellation in the PPL.

     {
         _M_task_collection._Cancel();
     }

bool Concurrency::structured_task_group::is_canceling ( )

inline

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

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

For more information, see Cancellation in the PPL.

     {
         return _M_task_collection._IsCanceling();
     }

template<class _Function >

void Concurrency::structured_task_group::run ( task_handle< _Function > & _Task_handle )

inline

Schedules a task on the structured_task_group object. The caller manages the lifetime of the task_handle object passed in the _Task_handle parameter. The version that takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter.

Template Parameters

_Function The type of the function object that will be invoked to execute the body of the task handle.

Parameters

_Task_handle A handle to the work being scheduled. Note that the caller has responsibility for the lifetime of this object. The runtime will continue to expect it to live until either the wait or run_and_wait method has been called on this structured_task_group object.

The runtime creates a copy of the work function that you pass to this method. Any state changes that occur in a function object that you pass to this method will not appear in your copy of that function object.

If the structured_task_group destructs as the result of stack unwinding from an exception, you do not need to guarantee that a call has been made to either the wait or run_and_wait method. In this case, the destructor will appropriately cancel and wait for the task represented by the _Task_handle parameter to complete.

Throws an invalid_multiple_scheduling exception if the task handle given by the _Task_handle parameter has already been scheduled onto a task group object via the run method and there has been no intervening call to either the wait or run_and_wait method on that task group.

See also: structured_task_group::wait Method, structured_task_group::run_and_wait Method, Task Parallelism, location class

     {
         _Task_handle._SetRuntimeOwnsLifetime(false);
         _M_task_collection._Schedule(&_Task_handle);
     }

template<class _Function >

void Concurrency::structured_task_group::run	(	task_handle< _Function > &	_Task_handle,
		location &	_Placement
	)

inline

Schedules a task on the structured_task_group object. The caller manages the lifetime of the task_handle object passed in the _Task_handle parameter. The version that takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter.

Template Parameters

_Function The type of the function object that will be invoked to execute the body of the task handle.

Parameters

_Task_handle	A handle to the work being scheduled. Note that the caller has responsibility for the lifetime of this object. The runtime will continue to expect it to live until either the `wait` or `run_and_wait` method has been called on this `structured_task_group` object.
_Placement	A reference to the location where the task represented by the _Task_handle parameter should execute.

The runtime creates a copy of the work function that you pass to this method. Any state changes that occur in a function object that you pass to this method will not appear in your copy of that function object.

If the structured_task_group destructs as the result of stack unwinding from an exception, you do not need to guarantee that a call has been made to either the wait or run_and_wait method. In this case, the destructor will appropriately cancel and wait for the task represented by the _Task_handle parameter to complete.

Throws an invalid_multiple_scheduling exception if the task handle given by the _Task_handle parameter has already been scheduled onto a task group object via the run method and there has been no intervening call to either the wait or run_and_wait method on that task group.

See also: structured_task_group::wait Method, structured_task_group::run_and_wait Method, Task Parallelism, location class

     {
         _Task_handle._SetRuntimeOwnsLifetime(false);
         _M_task_collection._Schedule(&_Task_handle, &_Placement);
     }

template<class _Function >

void Concurrency::structured_task_group::run ( task_handle< _Function > && _Task_handle )

private

template<class _Function >

task_group_status Concurrency::structured_task_group::run_and_wait ( task_handle< _Function > & _Task_handle )

inline

Schedules a task to be run inline on the calling context with the assistance of the structured_task_group object for full cancellation support. If a task_handle object is passed as a parameter to run_and_wait, the caller is responsible for managing the lifetime of the task_handle object. The function then waits until all work on the structured_task_group object has either completed or been canceled.

Template Parameters

_Function The type of the function object that will be invoked to execute the body of the task handle.

Parameters

_Task_handle A handle to the task which will be run inline on the calling context. Note that the caller has responsibility for the lifetime of this object. The runtime will continue to expect it to live until the run_and_wait method finishes execution.

Returns: An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. For more information, see task_group_status

Note that one or more of the tasks scheduled to this structured_task_group object may execute inline on the calling context.

If one or more of the tasks scheduled to this structured_task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the run_and_wait method.

After this function returns, the structured_task_group object is considered in a final state and should not be used. Note that utilization after the run_and_wait method returns will result in undefined behavior.

In the non-exceptional path of execution, you have a mandate to call either this method or the wait method before the destructor of the structured_task_group executes.

See also: structured_task_group::run Method, structured_task_group::wait Method, Task Parallelism

     {
         //
         // The underlying scheduler's definitions map exactly to the PPL's. No translation beyond the cast is necessary.
         //
         return (task_group_status)_M_task_collection._RunAndWait(&_Task_handle);
     }

template<class _Function >

task_group_status Concurrency::structured_task_group::run_and_wait ( const _Function & _Func )

inline

Schedules a task to be run inline on the calling context with the assistance of the structured_task_group object for full cancellation support. If a task_handle object is passed as a parameter to run_and_wait, the caller is responsible for managing the lifetime of the task_handle object. The function then waits until all work on the structured_task_group object has either completed or been canceled.

Template Parameters

_Function The type of the function object that will be invoked to execute the task.

Parameters

_Func A function which will be called to invoke the body of the work. This may be a lambda or other object which supports a version of the function call operator with the signature void operator()().

Returns: An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. For more information, see task_group_status

Note that one or more of the tasks scheduled to this structured_task_group object may execute inline on the calling context.

If one or more of the tasks scheduled to this structured_task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the run_and_wait method.

After this function returns, the structured_task_group object is considered in a final state and should not be used. Note that utilization after the run_and_wait method returns will result in undefined behavior.

In the non-exceptional path of execution, you have a mandate to call either this method or the wait method before the destructor of the structured_task_group executes.

See also: structured_task_group::run Method, structured_task_group::wait Method, Task Parallelism

     {
         //
         // The underlying scheduler's definitions map exactly to the PPL's. No translation beyond the cast is necessary.
         //
         task_handle<_Function> _Task(_Func);
         return (task_group_status)_M_task_collection._RunAndWait(&_Task);
     }

task_group_status Concurrency::structured_task_group::wait ( )

inline

Waits until all work on the structured_task_group has completed or is canceled.

Returns: An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. For more information, see task_group_status

Note that one or more of the tasks scheduled to this structured_task_group object may execute inline on the calling context.

If one or more of the tasks scheduled to this structured_task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the wait method.

After this function returns, the structured_task_group object is considered in a final state and should not be used. Note that utilization after the wait method returns will result in undefined behavior.

In the non-exceptional path of execution, you have a mandate to call either this method or the run_and_wait method before the destructor of the structured_task_group executes.

See also: structured_task_group::wait Method, structured_task_group::run_and_wait Method, Task Parallelism

     {
         //
         // The underlying scheduler's definitions map exactly to the PPL's. No translation beyond the cast is necessary.
         //
         return (task_group_status)_M_task_collection._Wait();
     }

Member Data Documentation

::Concurrency::details::_StructuredTaskCollection Concurrency::structured_task_group::_M_task_collection

private

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

VS2013/inc/ppl.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation