structured_task_group Class
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.
class structured_task_group;
Members
Public Constructors
Name |
Description |
|---|---|
Constructs a new structured_task_group object. |
|
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. |
Public Methods
Name |
Description |
|---|---|
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. |
|
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. |
|
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. |
|
Overloaded. 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. |
|
Waits until all work on the structured_task_group has completed or is canceled. |
Remarks
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. Once 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 (Concurrency Runtime).
Inheritance Hierarchy
Requirements
Header: ppl.h
Namespace: Concurrency