tbb::task_group_context Class Reference
Task Scheduling

Used to form groups of tasks. More...

`#include <task.h>`

Inheritance diagram for tbb::task_group_context:
Collaboration diagram for tbb::task_group_context:

## Public Types

enum | kind_type { isolated, bound }
enum | traits_type { exact_exception = 0x0001ul << traits_offset, fp_settings = 0x0002ul << traits_offset, concurrent_wait = 0x0004ul << traits_offset, default_traits = exact_exception }

## Public Member Functions

| task_group_context (kind_type relation_with_parent=bound, uintptr_t t=default_traits)
| Default & binding constructor. More...
| task_group_context (internal::string_index name)
__TBB_EXPORTED_METHOD | ~task_group_context ()
void __TBB_EXPORTED_METHOD | reset ()
| Forcefully reinitializes the context after the task tree it was associated with is completed. More...
bool __TBB_EXPORTED_METHOD | cancel_group_execution ()
| Initiates cancellation of all tasks in this cancellation group and its subordinate groups. More...
bool __TBB_EXPORTED_METHOD | is_group_execution_cancelled () const
| Returns true if the context received cancellation request. More...
void __TBB_EXPORTED_METHOD | register_pending_exception ()
| Records the pending exception, and cancels the task group. More...
void __TBB_EXPORTED_METHOD | capture_fp_settings ()
| Captures the current FPU control settings to the context. More...
__TBB_DEPRECATED void | set_priority (priority_t)
| Changes priority of the task group. More...
__TBB_DEPRECATED priority_t | priority () const
| Retrieves current priority of the current task group. More...
uintptr_t | traits () const
| Returns the context's trait. More...

## Protected Member Functions

void __TBB_EXPORTED_METHOD | init ()
| Out-of-line part of the constructor. More...

## Private Types

enum | version_traits_word_layout { traits_offset = 16, version_mask = 0xFFFF, traits_mask = 0xFFFFul << traits_offset }
enum | state { may_have_children = 1, next_state_value, low_unused_state_bit = (next_state_value-1)*2 }
typedef internal::tbb_exception_ptr | exception_container_type

## Private Member Functions

template<typename T >
void | propagate_task_group_state (T task_group_context::*mptr_state, task_group_context &src, T new_state)
| Propagates any state change detected to *this, and as an optimisation possibly also upward along the heritage line. More...
void | bind_to (internal::generic_scheduler *local_sched)
| Registers this context with the local scheduler and binds it to its parent context. More...
void | register_with (internal::generic_scheduler *local_sched)
| Registers this context with the local scheduler. More...
void | copy_fp_settings (const task_group_context &src)
| Copies FPU control setting from another context. More...
Private Member Functions inherited from tbb::internal::no_copy
| no_copy (const no_copy &)=delete
| no_copy ()=default

## Private Attributes

union {
__TBB_atomic kind_type my_kind
| Flavor of this context: bound or isolated. More...
uintptr_t _my_kind_aligner
}; |
task_group_context * | my_parent
| Pointer to the context of the parent cancellation group. NULL for isolated contexts. More...
internal::context_list_node_t | my_node
| Used to form the thread specific list of contexts without additional memory allocation. More...
__itt_caller | itt_caller
| Used to set and maintain stack stitching point for Intel Performance Tools. More...
char | _leading_padding [internal::NFS_MaxLineSize - 2 *sizeof(uintptr_t) - sizeof(void *) - sizeof(internal::context_list_node_t) - sizeof(__itt_caller) - sizeof(internal::cpu_ctl_env_space)]
| Leading padding protecting accesses to frequently used members from false sharing. More...
internal::cpu_ctl_env_space | my_cpu_ctl_env
| Space for platform-specific FPU settings. More...
uintptr_t | my_cancellation_requested
| Specifies whether cancellation was requested for this task group. More...
uintptr_t | my_version_and_traits
| Version for run-time checks and behavioral traits of the context. More...
exception_container_type * | my_exception
| Pointer to the container storing exception being propagated across this task group. More...
internal::generic_scheduler * | my_owner
| Scheduler instance that registered this context in its thread specific list. More...
uintptr_t | my_state
| Internal state (combination of state flags, currently only may_have_children). More...
intptr_t | my_priority
| Priority level of the task group (in normalized representation) More...
internal::string_index | my_name
| Description of algorithm for scheduler based instrumentation. More...
char | _trailing_padding [internal::NFS_MaxLineSize - 2 *sizeof(uintptr_t) - 2 *sizeof(void *) - sizeof(intptr_t) - sizeof(internal::string_index)]
| Trailing padding protecting accesses to frequently used members from false sharing. More...

## Static Private Attributes

static const kind_type | binding_required = bound
static const kind_type | binding_completed = kind_type(bound+1)
static const kind_type | detached = kind_type(binding_completed+1)
static const kind_type | dying = kind_type(detached+1)

## Friends

class | internal::generic_scheduler
class | task_scheduler_init
class | task_arena
class | task
class | internal::allocate_root_with_context_proxy

## Detailed Description

Used to form groups of tasks.

The context services explicit cancellation requests from user code, and unhandled exceptions intercepted during tasks execution. Intercepting an exception results in generating internal cancellation requests (which is processed in exactly the same way as external ones).

The context is associated with one or more root tasks and defines the cancellation group that includes all the descendants of the corresponding root task(s). Association is established when a context object is passed as an argument to the task::allocate_root() method. See task_group_context::task_group_context for more details.

The context can be bound to another one, and other contexts can be bound to it, forming a tree-like structure: parent -> this -> children. Arrows here designate cancellation propagation direction. If a task in a cancellation group is cancelled all the other tasks in this group and groups bound to it (as children) get cancelled too.

IMPLEMENTATION NOTE: When adding new members to task_group_context or changing types of existing ones, update the size of both padding buffers (_leading_padding and _trailing_padding) appropriately. See also VERSIONING NOTE at the constructor definition below.

Definition at line 347 of file task.h.

## Member Typedef Documentation

## exception_container_type

typedef internal::tbb_exception_ptr tbb::task_group_context::exception_container_type

private

Definition at line 356 of file task.h.

## Member Enumeration Documentation

## kind_type

enum tbb::task_group_context::kind_type

Enumerator
isolated |
bound |

Definition at line 366 of file task.h.

{
isolated,
bound
};

## state

enum tbb::task_group_context::state

private

Enumerator
may_have_children |
next_state_value |
low_unused_state_bit |

Definition at line 385 of file task.h.

{
may_have_children = 1,
// the following enumerations must be the last, new 2^x values must go above
next_state_value, low_unused_state_bit = (next_state_value-1)*2
};

## traits_type

enum tbb::task_group_context::traits_type

Enumerator
exact_exception |
fp_settings |
concurrent_wait |
default_traits |

Definition at line 371 of file task.h.

{
exact_exception = 0x0001ul << traits_offset,
#if __TBB_FP_CONTEXT
fp_settings = 0x0002ul << traits_offset,
#endif
concurrent_wait = 0x0004ul << traits_offset,
#if TBB_USE_CAPTURED_EXCEPTION
default_traits = 0
#else
default_traits = exact_exception
#endif /* !TBB_USE_CAPTURED_EXCEPTION */
};

## version_traits_word_layout

enum tbb::task_group_context::version_traits_word_layout

private

Enumerator
traits_offset |
version_mask |
traits_mask |

Definition at line 359 of file task.h.

{
traits_offset = 16,
version_mask = 0xFFFF,
traits_mask = 0xFFFFul << traits_offset
};

## Constructor & Destructor Documentation

## task_group_context() [1/2]

tbb::task_group_context::task_group_context | ( | kind_type | relation_with_parent = `bound`,
|  | uintptr_t | t = `default_traits`
| ) |  |

inline

Default & binding constructor.

By default a bound context is created. That is this context will be bound (as child) to the context of the task calling task::allocate_root(this_context) method. Cancellation requests passed to the parent context are propagated to all the contexts bound to it. Similarly priority change is propagated from the parent context to its children.

If task_group_context::isolated is used as the argument, then the tasks associated with this context will never be affected by events in any other context.

Creating isolated contexts involve much less overhead, but they have limited utility. Normally when an exception occurs in an algorithm that has nested ones running, it is desirably to have all the nested algorithms cancelled as well. Such a behavior requires nested algorithms to use bound contexts.

There is one good place where using isolated algorithms is beneficial. It is a master thread. That is if a particular algorithm is invoked directly from the master thread (not from a TBB task), supplying it with explicitly created isolated context will result in a faster algorithm startup.

VERSIONING NOTE: Implementation(s) of task_group_context constructor(s) cannot be made entirely out-of-line because the run-time version must be set by the user code. This will become critically important for binary compatibility, if we ever have to change the size of the context object.

Boosting the runtime version will also be necessary if new data fields are introduced in the currently unused padding areas and these fields are updated by inline methods.

Definition at line 493 of file task.h.

: my_kind(relation_with_parent)
, my_version_and_traits(3 | t)
, my_name(internal::CUSTOM_CTX)
{
init();
}

References init().

Here is the call graph for this function:

## task_group_context() [2/2]

tbb::task_group_context::task_group_context | ( | internal::string_index | name | ) |

inline

Definition at line 503 of file task.h.

: my_kind(bound)
, my_version_and_traits(3 | default_traits)
, my_name(name)
{
init();
}

References init().

Here is the call graph for this function:

## ~task_group_context()

__TBB_EXPORTED_METHOD tbb::task_group_context::~task_group_context | ( |  | ) |

## Member Function Documentation

## bind_to()

void tbb::task_group_context::bind_to | ( | internal::generic_scheduler * | local_sched | ) |

private

Registers this context with the local scheduler and binds it to its parent context.

## cancel_group_execution()

bool __TBB_EXPORTED_METHOD tbb::task_group_context::cancel_group_execution | ( |  | ) |

Initiates cancellation of all tasks in this cancellation group and its subordinate groups.

Returns
  false if cancellation has already been requested, true otherwise.

Note that canceling never fails. When false is returned, it just means that another thread (or this one) has already sent cancellation request to this context or to one of its ancestors (if this context is bound). It is guaranteed that when this method is concurrently called on the same not yet cancelled context, true will be returned by one and only one invocation.

Referenced by tbb::internal::task_group_base::cancel(), and tbb::task::cancel_group_execution().

Here is the caller graph for this function:

## capture_fp_settings()

void __TBB_EXPORTED_METHOD tbb::task_group_context::capture_fp_settings | ( |  | ) |

Captures the current FPU control settings to the context.

Because the method assumes that all the tasks that used to be associated with this context have already finished, calling it while the context is still in use somewhere in the task hierarchy leads to undefined behavior.

IMPORTANT: This method is not thread safe!

The method does not change the FPU control settings of the context's parent.

## copy_fp_settings()

void tbb::task_group_context::copy_fp_settings | ( | const task_group_context & | src | ) |

private

Copies FPU control setting from another context.

## init()

void __TBB_EXPORTED_METHOD tbb::task_group_context::init | ( |  | ) |

protected

Out-of-line part of the constructor.

Singled out to ensure backward binary compatibility of the future versions.

Referenced by task_group_context().

Here is the caller graph for this function:

## is_group_execution_cancelled()

bool __TBB_EXPORTED_METHOD tbb::task_group_context::is_group_execution_cancelled | ( |  | ) | const

Returns true if the context received cancellation request.

Referenced by tbb::internal::task_group_base::internal_run_and_wait(), tbb::internal::task_group_base::is_canceling(), tbb::task::is_cancelled(), tbb::interface9::internal::parallel_quick_sort(), tbb::internal::task_group_base::wait(), and tbb::flow::interface10::graph::wait_for_all().

Here is the caller graph for this function:

## priority()

__TBB_DEPRECATED priority_t tbb::task_group_context::priority | ( |  | ) | const

Retrieves current priority of the current task group.

Referenced by tbb::task::group_priority().

Here is the caller graph for this function:

## propagate_task_group_state()

template<typename T >

void tbb::task_group_context::propagate_task_group_state | ( | T task_group_context::* | mptr_state,
|  | task_group_context & | src,
|  | T | new_state
| ) |  |

private

Propagates any state change detected to *this, and as an optimisation possibly also upward along the heritage line.

## register_pending_exception()

void __TBB_EXPORTED_METHOD tbb::task_group_context::register_pending_exception | ( |  | ) |

Records the pending exception, and cancels the task group.

May be called only from inside a catch-block. If the context is already cancelled, does nothing. The method brings the task group associated with this context exactly into the state it would be in, if one of its tasks threw the currently pending exception during its execution. In other words, it emulates the actions of the scheduler's dispatch loop exception handler.

Referenced by tbb::internal::task_group_base::internal_run_and_wait().

Here is the caller graph for this function:

## register_with()

void tbb::task_group_context::register_with | ( | internal::generic_scheduler * | local_sched | ) |

private

Registers this context with the local scheduler.

## reset()

void __TBB_EXPORTED_METHOD tbb::task_group_context::reset | ( |  | ) |

Forcefully reinitializes the context after the task tree it was associated with is completed.

Because the method assumes that all the tasks that used to be associated with this context have already finished, calling it while the context is still in use somewhere in the task hierarchy leads to undefined behavior.

IMPORTANT: This method is not thread safe!

The method does not change the context's parent if it is set.

Referenced by tbb::flow::interface10::graph::reset(), tbb::internal::task_group_base::wait(), and tbb::flow::interface10::graph::wait_for_all().

Here is the caller graph for this function:

## set_priority()

__TBB_DEPRECATED void tbb::task_group_context::set_priority | ( | priority_t |  | ) |

Changes priority of the task group.

## traits()

uintptr_t tbb::task_group_context::traits | ( |  | ) | const

inline

Returns the context's trait.

Definition at line 567 of file task.h.

{ return my_version_and_traits & traits_mask; }

References my_version_and_traits, and traits_mask.

Referenced by tbb::flow::interface10::graph::wait_for_all().

Here is the caller graph for this function:

## Friends And Related Function Documentation

## internal::allocate_root_with_context_proxy

friend class internal::allocate_root_with_context_proxy

friend

Definition at line 576 of file task.h.

## internal::generic_scheduler

friend class internal::generic_scheduler

friend

Definition at line 349 of file task.h.

## task

friend class task

friend

Definition at line 575 of file task.h.

## task_arena

friend class task_arena

friend

Definition at line 351 of file task.h.

## task_scheduler_init

friend class task_scheduler_init

friend

Definition at line 350 of file task.h.

## Member Data Documentation

## @38

union { ... }

## _leading_padding

char tbb::task_group_context::_leading_padding[internal::NFS_MaxLineSize - 2 *sizeof(uintptr_t) - sizeof(void *) - sizeof(internal::context_list_node_t) - sizeof(__itt_caller) - sizeof(internal::cpu_ctl_env_space)]

private

Leading padding protecting accesses to frequently used members from false sharing.

Read accesses to the field my_cancellation_requested are on the hot path inside the scheduler. This padding ensures that this field never shares the same cache line with a local variable that is frequently written to.

Definition at line 419 of file task.h.

## _my_kind_aligner

uintptr_t tbb::task_group_context::_my_kind_aligner

Definition at line 395 of file task.h.

## _trailing_padding

char tbb::task_group_context::_trailing_padding[internal::NFS_MaxLineSize - 2 *sizeof(uintptr_t) - 2 *sizeof(void *) - sizeof(intptr_t) - sizeof(internal::string_index)]

private

Trailing padding protecting accesses to frequently used members from false sharing.

See also
  _leading_padding

Definition at line 461 of file task.h.

## binding_completed

const kind_type tbb::task_group_context::binding_completed = kind_type(bound+1)

static private

Definition at line 579 of file task.h.

## binding_required

const kind_type tbb::task_group_context::binding_required = bound

static private

Definition at line 578 of file task.h.

## detached

const kind_type tbb::task_group_context::detached = kind_type(binding_completed+1)

static private

Definition at line 580 of file task.h.

## dying

const kind_type tbb::task_group_context::dying = kind_type(detached+1)

static private

Definition at line 581 of file task.h.

## itt_caller

__itt_caller tbb::task_group_context::itt_caller

private

Used to set and maintain stack stitching point for Intel Performance Tools.

Definition at line 407 of file task.h.

Referenced by tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop().

## my_cancellation_requested

uintptr_t tbb::task_group_context::my_cancellation_requested

private

Specifies whether cancellation was requested for this task group.

Definition at line 429 of file task.h.

Referenced by tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop().

## my_cpu_ctl_env

internal::cpu_ctl_env_space tbb::task_group_context::my_cpu_ctl_env

private

Space for platform-specific FPU settings.

Must only be accessed inside TBB binaries, and never directly in user code or inline methods.

Definition at line 425 of file task.h.

## my_exception

exception_container_type* tbb::task_group_context::my_exception

private

Pointer to the container storing exception being propagated across this task group.

Definition at line 438 of file task.h.

## my_kind

__TBB_atomic kind_type tbb::task_group_context::my_kind

Flavor of this context: bound or isolated.

Definition at line 394 of file task.h.

## my_name

internal::string_index tbb::task_group_context::my_name

private

Description of algorithm for scheduler based instrumentation.

Definition at line 452 of file task.h.

## my_node

internal::context_list_node_t tbb::task_group_context::my_node

private

Used to form the thread specific list of contexts without additional memory allocation.

A context is included into the list of the current thread when its binding to its parent happens. Any context can be present in the list of one thread only.

Definition at line 404 of file task.h.

## my_owner

internal::generic_scheduler* tbb::task_group_context::my_owner

private

Scheduler instance that registered this context in its thread specific list.

Definition at line 441 of file task.h.

## my_parent

task_group_context* tbb::task_group_context::my_parent

private

Pointer to the context of the parent cancellation group. NULL for isolated contexts.

Definition at line 399 of file task.h.

## my_priority

intptr_t tbb::task_group_context::my_priority

private

Priority level of the task group (in normalized representation)

Definition at line 448 of file task.h.

## my_state

uintptr_t tbb::task_group_context::my_state

private

Internal state (combination of state flags, currently only may_have_children).

Definition at line 444 of file task.h.

## my_version_and_traits

uintptr_t tbb::task_group_context::my_version_and_traits

private

Version for run-time checks and behavioral traits of the context.

Version occupies low 16 bits, and traits (zero or more ORed enumerators from the traits_type enumerations) take the next 16 bits. Original (zeroth) version of the context did not support any traits.

Definition at line 435 of file task.h.

Referenced by traits().

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

- task.h

tbb::task_group_context::traits_offset
Definition: task.h:360
tbb::task_group_context::my_kind
__TBB_atomic kind_type my_kind
Flavor of this context: bound or isolated.
Definition: task.h:394
tbb::task_group_context::bound
Definition: task.h:368
tbb::task_group_context::concurrent_wait
Definition: task.h:376
tbb::task_group_context::isolated
Definition: task.h:367
tbb::task_group_context::default_traits
Definition: task.h:380
tbb::task_group_context::version_mask
Definition: task.h:361
tbb::task_group_context::fp_settings
Definition: task.h:374
tbb::task_group_context::traits_mask
Definition: task.h:362
tbb::task_group_context::my_version_and_traits
uintptr_t my_version_and_traits
Version for run-time checks and behavioral traits of the context.
Definition: task.h:435
tbb::task_group_context::exact_exception
Definition: task.h:372
tbb::task_group_context::low_unused_state_bit
Definition: task.h:388
tbb::task_group_context::init
void __TBB_EXPORTED_METHOD init()
Out-of-line part of the constructor.
name
void const char const char int ITT_FORMAT __itt_group_sync x void const char * name
Definition: ittnotify_static.h:93
tbb::task_group_context::my_name
internal::string_index my_name
Description of algorithm for scheduler based instrumentation.
Definition: task.h:452
tbb::task_group_context::next_state_value
Definition: task.h:388
tbb::task_group_context::may_have_children
Definition: task.h:386

Copyright © 2005-2020 Intel Corporation. All Rights Reserved.

Intel, Pentium, Intel Xeon, Itanium, Intel XScale and VTune are registered trademarks or trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.