task_group_context

[scheduler.task_group_context]

task_group_context represents a set of properties used by task scheduler for execution of the associated tasks. Each task is associated with only one task_group_context object.

The task_group_context objects form a forest of trees. Each tree’s root is a task_group_context constructed as isolated.

task_group_context is cancelled explicitly by the user request, or implicitly when an exception is thrown out of an associated task. Canceling task_group_context causes the entire subtree rooted at it to be cancelled.

The task_group_context carries floating point settings inherited from the parent task_group_context object or captured with a dedicated interface.

// Defined in header <oneapi/tbb/task_group.h>

namespace oneapi {
namespace tbb {

    class task_group_context {
    public:
        enum kind_t {
            isolated = /* implementation-defined */,
            bound = /* implementation-defined */
        };
        enum traits_type {
            fp_settings = /* implementation-defined */,
            default_traits = 0
        };

        task_group_context( kind_t relation_with_parent = bound,
                            uintptr_t traits = default_traits );
        ~task_group_context();

        void reset();
        bool cancel_group_execution();
        bool is_group_execution_cancelled() const;
        void capture_fp_settings();
        uintptr_t traits() const;
    };

} // namespace tbb;
} // namespace oneapi

Member types and constants

enum kind_t::isolated

When passed to the specific constructor, the created task_group_context object has no parent.

enum kind_t::bound

When passed to the specific constructor, the created task_group_context object becomes a child of the innermost running task’s group when the first task associated to the task_group_context is passed to the task scheduler. If there is no innermost running task on the current thread, the task_group_context becomes isolated.

enum traits_type::fp_settings

When passed to the specific constructor, the flag forces the context to capture floating-point settings from the current thread.

Member functions

task_group_context(kind_t relation_to_parent = bound, uintptr_t traits = default_traits)

Constructs an empty task_group_context.

~task_group_context()

Destroys an empty task_group_context. The behavior is undefined if there are still extant tasks associated with this task_group_context.

bool cancel_group_execution()

Requests that tasks associated with this task_group_context are not executed.

Returns false if this task_group_context is already cancelled; true, otherwise. If concurrently called by multiple threads, exactly one call returns true and the rest return false.

bool is_group_execution_cancelled() const

Returns true if this task_group_context has received the cancellation request.

void reset()

Reinitializes this task_group_context to the uncancelled state.

Caution

This method is only safe to call once all tasks associated with the group’s subordinate groups have completed. This method must not be invoked concurrently by multiple threads.

void capture_fp_settings()

Captures floating-point settings from the current thread.

Caution

This method is only safe to call once all tasks associated with the group’s subordinate groups have completed. This method must not be invoked concurrently by multiple threads.

uintptr_t traits() const

Returns traits of this task_group_context.