task_group_context

[scheduler.task_group_context]

The task_group_context represents a set of properties used by task scheduler for excution of the associated tasks. Each task is associated with the 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.

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

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

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

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;

Member types and constants

enum kind_t::isolated

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

enum kind_t::bound

When passed to the specific constructor, created task_group_context object will become 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 will become 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 funcitons

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.

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.