tbb::task Class Referenceabstract
Task Scheduling

Base class for user-defined tasks. More...

`#include <task.h>`

Inheritance diagram for tbb::task:
Collaboration diagram for tbb::task:

## Public Types

enum | state_type { executing , reexecute , ready , allocated , freed , recycle }
| Enumeration of task states that the scheduler considers. More...
typedef internal::affinity_id | affinity_id
| An id as used for specifying affinity. More...

## Public Member Functions

virtual | ~task ()
| Destructor. More...
virtual task * | execute ()=0
| Should be overridden by derived classes. More...
internal::allocate_continuation_proxy & | allocate_continuation ()
| Returns proxy for overloaded new that allocates a continuation task of *this. More...
internal::allocate_child_proxy & | allocate_child ()
| Returns proxy for overloaded new that allocates a child task of *this. More...
void | recycle_as_continuation ()
| Change this to be a continuation of its former self. More...
void | recycle_as_safe_continuation ()
| Recommended to use, safe variant of recycle_as_continuation. More...
void | recycle_as_child_of (task &new_parent)
| Change this to be a child of new_parent. More...
void | recycle_to_reexecute ()
| Schedule this for reexecution after current execute() returns. More...
void | set_ref_count (int count)
| Set reference count. More...
void | increment_ref_count ()
| Atomically increment reference count. More...
int | add_ref_count (int count)
| Atomically adds to reference count and returns its new value. More...
int | decrement_ref_count ()
| Atomically decrement reference count and returns its new value. More...
void | spawn_and_wait_for_all (task &child)
| Similar to spawn followed by wait_for_all, but more efficient. More...
void __TBB_EXPORTED_METHOD | spawn_and_wait_for_all (task_list &list)
| Similar to spawn followed by wait_for_all, but more efficient. More...
void | wait_for_all ()
| Wait for reference count to become one, and set reference count to zero. More...
task * | parent () const
| task on whose behalf this task is working, or NULL if this is a root. More...
void | set_parent (task *p)
| sets parent task pointer to specified value More...
task_group_context * | context ()
| This method is deprecated and will be removed in the future. More...
task_group_context * | group ()
| Pointer to the task group descriptor. More...
bool | is_stolen_task () const
| True if task was stolen from the task pool of another thread. More...
bool | is_enqueued_task () const
| True if the task was enqueued. More...
state_type | state () const
| Current execution state. More...
int | ref_count () const
| The internal reference count. More...
bool __TBB_EXPORTED_METHOD | is_owned_by_current_thread () const
| Obsolete, and only retained for the sake of backward compatibility. Always returns true. More...
void | set_affinity (affinity_id id)
| Set affinity for this task. More...
affinity_id | affinity () const
| Current affinity of this task. More...
virtual void __TBB_EXPORTED_METHOD | note_affinity (affinity_id id)
| Invoked by scheduler to notify task that it ran on unexpected thread. More...
void __TBB_EXPORTED_METHOD | change_group (task_group_context &ctx)
| Moves this task from its current group into another one. More...
bool | cancel_group_execution ()
| Initiates cancellation of all tasks in this cancellation group and its subordinate groups. More...
bool | is_cancelled () const
| Returns true if the context has received cancellation request. More...
__TBB_DEPRECATED void | set_group_priority (priority_t p)
| Changes priority of the task group this task belongs to. More...
__TBB_DEPRECATED priority_t | group_priority () const
| Retrieves current priority of the task group this task belongs to. More...

## Static Public Member Functions

static internal::allocate_root_proxy | allocate_root ()
| Returns proxy for overloaded new that allocates a root task. More...
static internal::allocate_root_with_context_proxy | allocate_root (task_group_context &ctx)
| Returns proxy for overloaded new that allocates a root task associated with user supplied context. More...
static void | spawn_root_and_wait (task &root)
| Spawn task allocated by allocate_root, wait for it to complete, and deallocate it. More...
static void | spawn_root_and_wait (task_list &root_list)
| Spawn root tasks on list and wait for all of them to finish. More...
static void | enqueue (task &t)
| Enqueue task for starvation-resistant execution. More...
static void | enqueue (task &t, priority_t p)
| Enqueue task for starvation-resistant execution on the specified priority level. More...
static void | enqueue (task &t, task_arena &arena, priority_t p=priority_t(0))
| Enqueue task in task_arena. More...
static task &__TBB_EXPORTED_FUNC | self ()
| The innermost task being executed or destroyed by the current thread at the moment. More...

## Protected Member Functions

| task ()
| Default constructor. More...

## Private Member Functions

void __TBB_EXPORTED_METHOD | internal_set_ref_count (int count)
| Set reference count. More...
internal::reference_count __TBB_EXPORTED_METHOD | internal_decrement_ref_count ()
| Decrement reference count and return its new value. More...
internal::task_prefix & | prefix (internal::version_tag *=NULL) const
| Get reference to corresponding task_prefix. More...

## Friends

class | interface5::internal::task_base
class | task_list
class | internal::scheduler
class | internal::allocate_root_proxy
class | internal::allocate_root_with_context_proxy
class | internal::allocate_continuation_proxy
class | internal::allocate_child_proxy
class | internal::allocate_additional_child_of_proxy
void | internal::make_critical (task &)
bool | internal::is_critical (task &)

## Detailed Description

Base class for user-defined tasks.

Definition at line 615 of file task.h.

## Member Typedef Documentation

## affinity_id

typedef internal::affinity_id tbb::task::affinity_id

An id as used for specifying affinity.

Guaranteed to be integral type. Value of 0 means no affinity.

Definition at line 940 of file task.h.

## Member Enumeration Documentation

## state_type

enum tbb::task::state_type

Enumeration of task states that the scheduler considers.

Enumerator
executing | task is running, and will be destroyed after method execute() completes.
reexecute | task to be rescheduled.
ready | task is in ready pool, or is going to be put there, or was just taken off.
allocated | task object is freshly allocated or recycled.
freed | task object is on free list, or is going to be put there, or was just taken off.
recycle | task to be recycled as continuation

Definition at line 635 of file task.h.

{
executing,
reexecute,
ready,
allocated,
freed,
recycle
#if __TBB_RECYCLE_TO_ENQUEUE
,to_enqueue
#endif
#if __TBB_PREVIEW_RESUMABLE_TASKS
,to_resume
#endif
};
tbb::task::recycle
@ recycle
task to be recycled as continuation
Definition: task.h:647
tbb::task::allocated
@ allocated
task object is freshly allocated or recycled.
Definition: task.h:643
tbb::task::reexecute
@ reexecute
task to be rescheduled.
Definition: task.h:639
tbb::task::ready
@ ready
task is in ready pool, or is going to be put there, or was just taken off.
Definition: task.h:641
tbb::task::freed
@ freed
task object is on free list, or is going to be put there, or was just taken off.
Definition: task.h:645
tbb::task::executing
@ executing
task is running, and will be destroyed after method execute() completes.
Definition: task.h:637

## Constructor & Destructor Documentation

## task()

tbb::task::task | ( |  | ) |

inline protected

Default constructor.

Definition at line 625 of file task.h.

{prefix().extra_state=1;}
tbb::internal::task_prefix::extra_state
unsigned char extra_state
Miscellaneous state that is not directly visible to users, stored as a byte for compactness.
Definition: task.h:292
tbb::task::prefix
internal::task_prefix & prefix(internal::version_tag *=NULL) const
Get reference to corresponding task_prefix.
Definition: task.h:1002

## ~task()

virtual tbb::task::~task | ( |  | ) |

inline virtual

Destructor.

Definition at line 629 of file task.h.

{}

Referenced by tbb::interface5::internal::task_base::destroy(), and tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop().

Here is the caller graph for this function:

## Member Function Documentation

## add_ref_count()

int tbb::task::add_ref_count | ( | int | count | ) |

inline

Atomically adds to reference count and returns its new value.

Has release-acquire semantics

Definition at line 777 of file task.h.

{
internal::call_itt_notify( internal::releasing, &prefix().ref_count );
internal::reference_count k = count+__TBB_FetchAndAddW( &prefix().ref_count, count );
__TBB_ASSERT( k>=0, "task's reference count underflowed" );
if( k==0 )
internal::call_itt_notify( internal::acquired, &prefix().ref_count );
return int(k);
}
__TBB_ASSERT
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
count
void const char const char int ITT_FORMAT __itt_group_sync x void const char ITT_FORMAT __itt_group_sync s void ITT_FORMAT __itt_group_sync p void ITT_FORMAT p void ITT_FORMAT p no args __itt_suppress_mode_t unsigned int void size_t ITT_FORMAT d void ITT_FORMAT p void ITT_FORMAT p __itt_model_site __itt_model_site_instance ITT_FORMAT p __itt_model_task __itt_model_task_instance ITT_FORMAT p void ITT_FORMAT p void ITT_FORMAT p void size_t ITT_FORMAT d void ITT_FORMAT p const wchar_t ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s no args void ITT_FORMAT p size_t count
Definition: ittnotify_static.h:145
int
void const char const char int ITT_FORMAT __itt_group_sync x void const char ITT_FORMAT __itt_group_sync s void ITT_FORMAT __itt_group_sync p void ITT_FORMAT p void ITT_FORMAT p no args __itt_suppress_mode_t unsigned int void size_t ITT_FORMAT d void ITT_FORMAT p void ITT_FORMAT p __itt_model_site __itt_model_site_instance ITT_FORMAT p __itt_model_task __itt_model_task_instance ITT_FORMAT p void ITT_FORMAT p void ITT_FORMAT p void size_t ITT_FORMAT d void ITT_FORMAT p const wchar_t ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s no args void ITT_FORMAT p size_t ITT_FORMAT d no args const wchar_t const wchar_t ITT_FORMAT s __itt_heap_function void size_t int ITT_FORMAT d __itt_heap_function void ITT_FORMAT p __itt_heap_function void void size_t int ITT_FORMAT d no args no args unsigned int ITT_FORMAT u const __itt_domain __itt_id ITT_FORMAT lu const __itt_domain __itt_id __itt_id __itt_string_handle ITT_FORMAT p const __itt_domain __itt_id ITT_FORMAT p const __itt_domain __itt_id __itt_timestamp __itt_timestamp ITT_FORMAT lu const __itt_domain __itt_id __itt_id __itt_string_handle ITT_FORMAT p const __itt_domain ITT_FORMAT p const __itt_domain __itt_string_handle unsigned long long ITT_FORMAT lu const __itt_domain __itt_string_handle unsigned long long ITT_FORMAT lu const __itt_domain __itt_id __itt_string_handle __itt_metadata_type size_t void ITT_FORMAT p const __itt_domain __itt_id __itt_string_handle const wchar_t size_t ITT_FORMAT lu const __itt_domain __itt_id __itt_relation __itt_id ITT_FORMAT p const wchar_t int ITT_FORMAT __itt_group_mark d int
Definition: ittnotify_static.h:217
tbb::internal::acquired
@ acquired
Definition: tbb_profiling.h:129
tbb::internal::releasing
@ releasing
Definition: tbb_profiling.h:129
tbb::internal::reference_count
intptr_t reference_count
A reference count.
Definition: task.h:131
tbb::internal::call_itt_notify
void call_itt_notify(notify_type, void *)
Definition: tbb_profiling.h:276
tbb::task::ref_count
int ref_count() const
The internal reference count.
Definition: task.h:915

References __TBB_ASSERT, tbb::internal::acquired, tbb::internal::call_itt_notify(), count, int, and tbb::internal::releasing.

Here is the call graph for this function:

## affinity()

affinity_id tbb::task::affinity | ( |  | ) | const

inline

Current affinity of this task.

Definition at line 946 of file task.h.

{return prefix().affinity;}
tbb::internal::task_prefix::affinity
affinity_id affinity
Definition: task.h:294

## allocate_child()

internal::allocate_child_proxy& tbb::task::allocate_child | ( |  | ) |

inline

Returns proxy for overloaded new that allocates a child task of *this.

Definition at line 681 of file task.h.

{
return *reinterpret_cast<internal::allocate_child_proxy*>(this);
}
tbb::task::allocate_child_proxy
friend class internal::allocate_child_proxy
Definition: task.h:997

Referenced by tbb::internal::parallel_invoke_helper::add_children(), tbb::interface9::internal::allocate_sibling(), tbb::interface9::internal::do_group_task_forward< Iterator, Body, Item >::execute(), tbb::interface9::internal::do_group_task_input< Body, Item >::execute(), tbb::internal::spawner< N, function1, function2, function3 >::execute(), tbb::internal::while_group_task< Body >::execute(), tbb::internal::pipeline_root_task::execute(), tbb::internal::parallel_invoke_helper::run_and_finish(), tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_random_access_iterator(), and tbb::interface9::internal::run_parallel_do().

Here is the caller graph for this function:

## allocate_continuation()

internal::allocate_continuation_proxy& tbb::task::allocate_continuation | ( |  | ) |

inline

Returns proxy for overloaded new that allocates a continuation task of *this.

The continuation's parent becomes the parent of *this.

Definition at line 676 of file task.h.

{
return *reinterpret_cast<internal::allocate_continuation_proxy*>(this);
}
tbb::task::allocate_continuation_proxy
friend class internal::allocate_continuation_proxy
Definition: task.h:996

Referenced by tbb::interface9::internal::allocate_sibling(), tbb::flow::interface11::internal::prioritize_task(), and tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_random_access_iterator().

Here is the caller graph for this function:

## allocate_root() [1/2]

static internal::allocate_root_proxy tbb::task::allocate_root | ( |  | ) |

inline static

Returns proxy for overloaded new that allocates a root task.

Definition at line 663 of file task.h.

{
return internal::allocate_root_proxy();
}
tbb::task::allocate_root_proxy
friend class internal::allocate_root_proxy
Definition: task.h:992

Referenced by tbb::interface7::task_arena::enqueue_impl(), tbb::internal::start_scan< Range, Body, Partitioner >::execute(), tbb::flow::interface10::graph::graph(), tbb::interface9::internal::parallel_do_feeder_impl< Body, Item >::parallel_do_feeder_impl(), tbb::interface9::internal::start_reduce< Range, Body, Partitioner >::run(), tbb::interface9::internal::start_deterministic_reduce< Range, Body, Partitioner >::run(), tbb::interface9::internal::start_for< Range, Body, Partitioner >::run(), tbb::internal::start_scan< Range, Body, Partitioner >::run(), tbb::parallel_while< Body >::run(), and tbb::internal::task_group_base::task_group_base().

Here is the caller graph for this function:

## allocate_root() [2/2]

static internal::allocate_root_with_context_proxy tbb::task::allocate_root | ( | task_group_context & | ctx | ) |

inline static

Returns proxy for overloaded new that allocates a root task associated with user supplied context.

Definition at line 669 of file task.h.

{
return internal::allocate_root_with_context_proxy(ctx);
}
tbb::task::allocate_root_with_context_proxy
friend class internal::allocate_root_with_context_proxy
Definition: task.h:994

## cancel_group_execution()

bool tbb::task::cancel_group_execution | ( |  | ) |

inline

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

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

Definition at line 971 of file task.h.

{ return prefix().context->cancel_group_execution(); }
tbb::internal::task_prefix::context
task_group_context * context
Shared context that is used to communicate asynchronous state changes.
Definition: task.h:230
tbb::task_group_context::cancel_group_execution
bool __TBB_EXPORTED_METHOD cancel_group_execution()
Initiates cancellation of all tasks in this cancellation group and its subordinate groups.

Referenced by tbb::interface9::internal::quick_sort_pretest_body< RandomAccessIterator, Compare >::operator()().

Here is the caller graph for this function:

## change_group()

void __TBB_EXPORTED_METHOD tbb::task::change_group | ( | task_group_context & | ctx | ) |

Moves this task from its current group into another one.

Argument ctx specifies the new group.

The primary purpose of this method is to associate unique task group context with a task allocated for subsequent enqueuing. In contrast to spawned tasks enqueued ones normally outlive the scope where they were created. This makes traditional usage model where task group context are allocated locally on the stack inapplicable. Dynamic allocation of context objects is performance inefficient. Method change_group() allows to make task group context object a member of the task class, and then associate it with its containing task object in the latter's constructor.

## context()

task_group_context* tbb::task::context | ( |  | ) |

inline

This method is deprecated and will be removed in the future.

Use method group() instead.

Definition at line 878 of file task.h.

{return prefix().context;}

Referenced by tbb::interface9::internal::start_for< Range, Body, Partitioner >::run().

Here is the caller graph for this function:

## decrement_ref_count()

int tbb::task::decrement_ref_count | ( |  | ) |

inline

Atomically decrement reference count and returns its new value.

Has release semantics.

Definition at line 788 of file task.h.

{
#if TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT
return int(internal_decrement_ref_count());
#else
return int(__TBB_FetchAndDecrementWrelease( &prefix().ref_count ))-1;
#endif /* TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT */
}
__TBB_FetchAndDecrementWrelease
#define __TBB_FetchAndDecrementWrelease(P)
Definition: tbb_machine.h:314
tbb::task::internal_decrement_ref_count
internal::reference_count __TBB_EXPORTED_METHOD internal_decrement_ref_count()
Decrement reference count and return its new value.
Definition: task.cpp:192

References __TBB_FetchAndDecrementWrelease, and int.

Referenced by tbb::flow::interface10::graph::release_wait(), and tbb::internal::task_group_base::ref_count_guard::~ref_count_guard().

Here is the caller graph for this function:

## enqueue() [1/3]

static void tbb::task::enqueue | ( | task & | t | ) |

inline static

Enqueue task for starvation-resistant execution.

The task will be enqueued on the normal priority level disregarding the priority of its task group.

The rationale of such semantics is that priority of an enqueued task is statically fixed at the moment of its enqueuing, while task group priority is dynamic. Thus automatic priority inheritance would be generally a subject to the race, which may result in unexpected behavior.

Use enqueue() overload with explicit priority value and task::group_priority() method to implement such priority inheritance when it is really necessary.

Definition at line 836 of file task.h.

{
t.prefix().owner->enqueue( t, NULL );
}

References tbb::internal::scheduler::enqueue(), tbb::internal::task_prefix::owner, and prefix().

Referenced by enqueue(), and tbb::flow::interface11::internal::enqueue_in_graph_arena().

Here is the call graph for this function:
Here is the caller graph for this function:

## enqueue() [2/3]

static void tbb::task::enqueue | ( | task & | t,
|  | priority_t | p
| ) |  |

inline static

Enqueue task for starvation-resistant execution on the specified priority level.

Definition at line 842 of file task.h.

{
#if __TBB_PREVIEW_CRITICAL_TASKS
__TBB_ASSERT(p == priority_low || p == priority_normal || p == priority_high
|| p == internal::priority_critical, "Invalid priority level value");
#else
__TBB_ASSERT(p == priority_low || p == priority_normal || p == priority_high, "Invalid priority level value");
#endif
t.prefix().owner->enqueue( t, (void*)p );
}
p
void const char const char int ITT_FORMAT __itt_group_sync p
Definition: ittnotify_static.h:91
tbb::priority_normal
@ priority_normal
Definition: task.h:318
tbb::priority_high
@ priority_high
Definition: task.h:320
tbb::priority_low
@ priority_low
Definition: task.h:319
tbb::internal::priority_critical
static const int priority_critical
Definition: task.h:313

References __TBB_ASSERT, tbb::internal::scheduler::enqueue(), tbb::internal::task_prefix::owner, p, prefix(), tbb::internal::priority_critical, tbb::priority_high, tbb::priority_low, and tbb::priority_normal.

Here is the call graph for this function:

## enqueue() [3/3]

void tbb::task::enqueue | ( | task & | t,
|  | task_arena & | arena,
|  | priority_t | p = `priority_t(0)`
| ) |  |

inline static

Enqueue task in task_arena.

Enqueue task in task_arena The implementation is in task_arena.h

Note: the context of the task may differ from the context instantiated by task_arena

Definition at line 497 of file task_arena.h.

{
#else
void task::enqueue( task& t, task_arena& arena ) {
intptr_t p = 0;
#endif
arena.initialize();
arena.internal_enqueue(t, p);
}
tbb::task::enqueue
static void enqueue(task &t)
Enqueue task for starvation-resistant execution.
Definition: task.h:836
tbb::task::task
task()
Default constructor.
Definition: task.h:625
tbb::internal::arena
Definition: arena.h:277

References enqueue(), and p.

Here is the call graph for this function:

## execute()

virtual task* tbb::task::execute | ( |  | ) |

pure virtual

Should be overridden by derived classes.

Implemented in tbb::internal::pipeline_root_task, tbb::internal::stage_task, tbb::internal::task_handle_task< F >, tbb::internal::function_task< F >, tbb::empty_task, tbb::interface9::internal::flag_task, tbb::internal::while_task< Stream, Body >, tbb::internal::while_group_task< Body >, tbb::internal::while_iteration_task< Body >, tbb::internal::start_scan< Range, Body, Partitioner >, tbb::internal::finish_scan< Range, Body >, tbb::internal::sum_node< Range, Body >, tbb::internal::final_sum< Range, Body >, tbb::interface9::internal::start_deterministic_reduce< Range, Body, Partitioner >, tbb::interface9::internal::finish_deterministic_reduce< Body >, tbb::interface9::internal::start_reduce< Range, Body, Partitioner >, tbb::interface9::internal::finish_reduce< Body >, tbb::internal::spawner< N, function1, function2, function3 >, tbb::internal::function_invoker< function >, tbb::interface9::internal::start_for< Range, Body, Partitioner >, tbb::interface9::internal::do_task_iter< Iterator, Body, Item >, tbb::interface9::internal::do_group_task_input< Body, Item >, tbb::interface9::internal::do_group_task_forward< Iterator, Body, Item >, tbb::interface9::internal::do_iteration_task_iter< Iterator, Body, Item >, tbb::interface9::internal::do_iteration_task< Body, Item >, tbb::flow::interface10::graph::run_and_put_task< Receiver, Body >, tbb::flow::interface10::graph::run_task< Body >, tbb::flow::interface11::internal::priority_task_selector, and tbb::flow::interface11::overwrite_node< T >::register_predecessor_task.

Referenced by tbb::flow::interface11::internal::priority_task_selector::execute(), tbb::interface9::internal::start_for< Range, Body, Partitioner >::execute(), tbb::interface9::internal::start_deterministic_reduce< Range, Body, Partitioner >::execute(), and tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop().

Here is the caller graph for this function:

## group()

task_group_context* tbb::task::group | ( |  | ) |

inline

Pointer to the task group descriptor.

Definition at line 881 of file task.h.

{ return prefix().context; }

## group_priority()

__TBB_DEPRECATED priority_t tbb::task::group_priority | ( |  | ) | const

inline

Retrieves current priority of the task group this task belongs to.

Definition at line 984 of file task.h.

{ return prefix().context->priority(); }
tbb::task_group_context::priority
__TBB_DEPRECATED_IN_VERBOSE_MODE priority_t priority() const
Retrieves current priority of the current task group.

## increment_ref_count()

void tbb::task::increment_ref_count | ( |  | ) |

inline

Atomically increment reference count.

Has acquire semantics

Definition at line 771 of file task.h.

{
__TBB_FetchAndIncrementWacquire( &prefix().ref_count );
}
__TBB_FetchAndIncrementWacquire
#define __TBB_FetchAndIncrementWacquire(P)
Definition: tbb_machine.h:313

References __TBB_FetchAndIncrementWacquire.

Referenced by tbb::internal::allocate_additional_child_of_proxy::allocate(), tbb::internal::task_group_base::ref_count_guard::ref_count_guard(), and tbb::flow::interface10::graph::reserve_wait().

Here is the caller graph for this function:

## internal_decrement_ref_count()

internal::reference_count tbb::task::internal_decrement_ref_count | ( |  | ) |

private

Decrement reference count and return its new value.

Definition at line 192 of file task.cpp.

{
ITT_NOTIFY( sync_releasing, &prefix().ref_count );
internal::reference_count k = __TBB_FetchAndDecrementWrelease( &prefix().ref_count );
__TBB_ASSERT( k>=1, "task's reference count underflowed" );
if( k==1 )
ITT_NOTIFY( sync_acquired, &prefix().ref_count );
return k-1;
}
ITT_NOTIFY
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:112
sync_releasing
void const char const char int ITT_FORMAT __itt_group_sync x void const char ITT_FORMAT __itt_group_sync s void ITT_FORMAT __itt_group_sync p void ITT_FORMAT p sync_releasing
Definition: ittnotify_static.h:104

References __TBB_ASSERT, __TBB_FetchAndDecrementWrelease, ITT_NOTIFY, and sync_releasing.

Referenced by tbb::internal::allocate_additional_child_of_proxy::free().

Here is the caller graph for this function:

## internal_set_ref_count()

void tbb::task::internal_set_ref_count | ( | int | count | ) |

private

Set reference count.

Definition at line 183 of file task.cpp.

{
__TBB_ASSERT( count>=0, "count must not be negative" );
task_prefix &p = prefix();
__TBB_ASSERT(p.ref_count==1 && p.state==allocated && self().parent()==this
|| !(p.extra_state & es_ref_count_active), "ref_count race detected");
ITT_NOTIFY(sync_releasing, &p.ref_count);
p.ref_count = count;
}
tbb::internal::es_ref_count_active
@ es_ref_count_active
Set if ref_count might be changed by another thread. Used for debugging.
Definition: scheduler_common.h:176
tbb::internal::task_prefix
Memory prefix to a task object.
Definition: task.h:203

References __TBB_ASSERT, count, tbb::internal::es_ref_count_active, ITT_NOTIFY, p, and sync_releasing.

## is_cancelled()

bool tbb::task::is_cancelled | ( |  | ) | const

inline

Returns true if the context has received cancellation request.

Definition at line 974 of file task.h.

{ return prefix().context->is_group_execution_cancelled(); }
tbb::task_group_context::is_group_execution_cancelled
bool __TBB_EXPORTED_METHOD is_group_execution_cancelled() const
Returns true if the context received cancellation request.

Referenced by tbb::is_current_task_group_canceling(), and tbb::interface9::internal::quick_sort_pretest_body< RandomAccessIterator, Compare >::operator()().

Here is the caller graph for this function:

## is_enqueued_task()

bool tbb::task::is_enqueued_task | ( |  | ) | const

inline

True if the task was enqueued.

Definition at line 890 of file task.h.

{
// es_task_enqueued = 0x10
return (prefix().extra_state & 0x10)!=0;
}

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

Here is the caller graph for this function:

## is_owned_by_current_thread()

bool tbb::task::is_owned_by_current_thread | ( |  | ) | const

Obsolete, and only retained for the sake of backward compatibility. Always returns true.

Definition at line 208 of file task.cpp.

{
return true;
}

## is_stolen_task()

bool tbb::task::is_stolen_task | ( |  | ) | const

inline

True if task was stolen from the task pool of another thread.

Definition at line 885 of file task.h.

{
return (prefix().extra_state & 0x80)!=0;
}

Referenced by tbb::interface9::internal::dynamic_grainsize_mode< Mode >::check_being_stolen(), and tbb::interface9::internal::old_auto_partition_type::should_execute_range().

Here is the caller graph for this function:

## note_affinity()

void tbb::task::note_affinity | ( | affinity_id | id | ) |

virtual

Invoked by scheduler to notify task that it ran on unexpected thread.

Invoked before method execute() runs, if task is stolen, or task has affinity but will be executed on another thread.

The default action does nothing.

Defined out of line so that compiler does not replicate task's vtable. It's pointless to define it inline anyway, because all call sites to it are virtual calls that the compiler is unlikely to optimize.

Reimplemented in tbb::interface9::internal::start_reduce< Range, Body, Partitioner >, and tbb::interface9::internal::start_for< Range, Body, Partitioner >.

Definition at line 245 of file task.cpp.

{
}

Referenced by tbb::internal::generic_scheduler::get_task(), and tbb::internal::generic_scheduler::steal_task().

Here is the caller graph for this function:

## parent()

task* tbb::task::parent | ( |  | ) | const

inline

task on whose behalf this task is working, or NULL if this is a root.

Definition at line 865 of file task.h.

{return prefix().parent;}
tbb::internal::task_prefix::parent
tbb::task * parent
The task whose reference count includes me.
Definition: task.h:267

References parent().

Referenced by tbb::internal::allocate_continuation_proxy::allocate(), tbb::interface9::internal::dynamic_grainsize_mode< Mode >::check_being_stolen(), tbb::interface5::internal::task_base::destroy(), tbb::internal::arena::enqueue_task(), tbb::internal::stage_task::execute(), tbb::internal::allocate_continuation_proxy::free(), tbb::interface9::internal::flag_task::is_peer_stolen(), tbb::internal::custom_scheduler< SchedulerTraits >::local_wait_for_all(), tbb::interface9::internal::flag_task::mark_task_stolen(), parent(), tbb::internal::generic_scheduler::prepare_for_spawning(), tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop(), and tbb::internal::stage_task::spawn_stage_task().

Here is the call graph for this function:
Here is the caller graph for this function:

## prefix()

internal::task_prefix& tbb::task::prefix | ( | internal::version_tag * | = `NULL` | ) | const

inline private

Get reference to corresponding task_prefix.

Version tag prevents loader on Linux from using the wrong symbol in debug builds.

Definition at line 1002 of file task.h.

{
return reinterpret_cast<internal::task_prefix*>(const_cast<task*>(this))[-1];
}

Referenced by tbb::internal::allocate_root_proxy::allocate(), tbb::internal::allocate_additional_child_of_proxy::allocate(), tbb::internal::allocate_continuation_proxy::allocate(), tbb::internal::allocate_child_proxy::allocate(), tbb::internal::generic_scheduler::allocate_task(), tbb::internal::generic_scheduler::attach_arena(), tbb::internal::generic_scheduler::cleanup_scheduler(), tbb::internal::generic_scheduler::create_master(), tbb::internal::generic_scheduler::deallocate_task(), tbb::interface5::internal::task_base::destroy(), enqueue(), tbb::internal::arena::enqueue_task(), tbb::internal::task_proxy::extract_task(), tbb::internal::generic_scheduler::free_nonlocal_small_task(), tbb::internal::generic_scheduler::free_task(), tbb::internal::generic_scheduler::generic_scheduler(), tbb::internal::generic_scheduler::get_task(), tbb::internal::mail_outbox::internal_pop(), tbb::internal::generic_scheduler::is_proxy(), tbb::internal::generic_scheduler::is_version_3_task(), tbb::internal::generic_scheduler::local_spawn(), tbb::internal::generic_scheduler::local_spawn_root_and_wait(), tbb::internal::custom_scheduler< SchedulerTraits >::local_wait_for_all(), tbb::internal::task_stream< Levels >::look_specific(), tbb::internal::nested_arena_context::mimic_outermost_level(), tbb::task_list::pop_front(), tbb::internal::auto_empty_task::prefix(), tbb::internal::generic_scheduler::prepare_for_spawning(), tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop(), tbb::task_list::push_back(), recycle_as_child_of(), tbb::internal::reset_extra_state(), tbb::interface5::internal::task_base::spawn(), spawn_and_wait_for_all(), spawn_root_and_wait(), tbb::internal::generic_scheduler::steal_task(), tbb::internal::generic_scheduler::steal_task_from(), tbb::internal::custom_scheduler< SchedulerTraits >::tally_completion_of_predecessor(), tbb::internal::generic_scheduler::wait_until_empty(), and tbb::internal::nested_arena_context::~nested_arena_context().

Here is the caller graph for this function:

## recycle_as_child_of()

void tbb::task::recycle_as_child_of | ( | task & | new_parent | ) |

inline

Change this to be a child of new_parent.

Definition at line 725 of file task.h.

{
internal::task_prefix& p = prefix();
__TBB_ASSERT( prefix().state==executing||prefix().state==allocated, "execute not running, or already recycled" );
__TBB_ASSERT( prefix().ref_count==0, "no child tasks allowed when recycled as a child" );
__TBB_ASSERT( p.parent==NULL, "parent must be null" );
__TBB_ASSERT( new_parent.prefix().state<=recycle, "corrupt parent's state" );
__TBB_ASSERT( new_parent.prefix().state!=freed, "parent already freed" );
p.state = allocated;
p.parent = &new_parent;
#if __TBB_TASK_GROUP_CONTEXT
p.context = new_parent.prefix().context;
#endif /* __TBB_TASK_GROUP_CONTEXT */
}
tbb::task::state
state_type state() const
Current execution state.
Definition: task.h:912

References __TBB_ASSERT, tbb::internal::task_prefix::context, p, prefix(), and tbb::internal::task_prefix::state.

Referenced by tbb::internal::sum_node< Range, Body >::create_child(), and tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_random_access_iterator().

Here is the call graph for this function:
Here is the caller graph for this function:

## recycle_as_continuation()

void tbb::task::recycle_as_continuation | ( |  | ) |

inline

Change this to be a continuation of its former self.

The caller must guarantee that the task's refcount does not become zero until after the method execute() returns. Typically, this is done by having method execute() return a pointer to a child of the task. If the guarantee cannot be made, use method recycle_as_safe_continuation instead.

Because of the hazard, this method may be deprecated in the future.

Definition at line 711 of file task.h.

{
__TBB_ASSERT( prefix().state==executing, "execute not running?" );
prefix().state = allocated;
}
tbb::internal::task_prefix::state
unsigned char state
A task::state_type, stored as a byte for compactness.
Definition: task.h:283

References __TBB_ASSERT.

Referenced by tbb::internal::sum_node< Range, Body >::execute(), tbb::internal::stage_task::execute(), and tbb::internal::pipeline_root_task::execute().

Here is the caller graph for this function:

## recycle_as_safe_continuation()

void tbb::task::recycle_as_safe_continuation | ( |  | ) |

inline

Recommended to use, safe variant of recycle_as_continuation.

For safety, it requires additional increment of ref_count. With no descendants and ref_count of 1, it has the semantics of recycle_to_reexecute.

Definition at line 719 of file task.h.

{
__TBB_ASSERT( prefix().state==executing, "execute not running?" );
prefix().state = recycle;
}

References __TBB_ASSERT.

Referenced by tbb::internal::spawner< N, function1, function2, function3 >::execute().

Here is the caller graph for this function:

## recycle_to_reexecute()

void tbb::task::recycle_to_reexecute | ( |  | ) |

inline

Schedule this for reexecution after current execute() returns.

Made obsolete by recycle_as_safe_continuation; may become deprecated.

Definition at line 741 of file task.h.

{
__TBB_ASSERT( prefix().state==executing, "execute not running, or already recycled" );
__TBB_ASSERT( prefix().ref_count==0, "no child tasks allowed when recycled for reexecution" );
prefix().state = reexecute;
}

References __TBB_ASSERT.

Referenced by tbb::internal::while_task< Stream, Body >::execute(), tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_forward_iterator(), and tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_input_iterator().

Here is the caller graph for this function:

## ref_count()

int tbb::task::ref_count | ( |  | ) | const

inline

The internal reference count.

Definition at line 915 of file task.h.

{
#if TBB_USE_ASSERT
#if __TBB_PREVIEW_RESUMABLE_TASKS
internal::reference_count ref_count_ = prefix().ref_count & ~internal::abandon_flag;
#else
internal::reference_count ref_count_ = prefix().ref_count;
#endif
__TBB_ASSERT( ref_count_==int(ref_count_), "integer overflow error");
#endif
#if __TBB_PREVIEW_RESUMABLE_TASKS
return int(prefix().ref_count & ~internal::abandon_flag);
#else
return int(prefix().ref_count);
#endif
}
internal
Definition: _flow_graph_async_msg_impl.h:24
tbb::internal::task_prefix::ref_count
__TBB_atomic reference_count ref_count
Reference count used for synchronization.
Definition: task.h:274

References __TBB_ASSERT, and int.

Referenced by tbb::interface9::internal::dynamic_grainsize_mode< Mode >::check_being_stolen(), tbb::internal::finish_scan< Range, Body >::execute(), and tbb::internal::task_group_base::~task_group_base().

Here is the caller graph for this function:

## self()

task & tbb::task::self | ( |  | ) |

static

The innermost task being executed or destroyed by the current thread at the moment.

Definition at line 201 of file task.cpp.

{
generic_scheduler *v = governor::local_scheduler_weak();
v->assert_task_pool_valid();
__TBB_ASSERT( v->my_innermost_running_task, NULL );
return *v->my_innermost_running_task;
}
tbb::internal::governor::local_scheduler_weak
static generic_scheduler * local_scheduler_weak()
Definition: governor.h:134
tbb::internal::scheduler_state::my_innermost_running_task
task * my_innermost_running_task
Innermost task whose task::execute() is running. A dummy task on the outermost level.
Definition: scheduler.h:88
tbb::internal::generic_scheduler
Work stealing task scheduler.
Definition: scheduler.h:140
tbb::internal::generic_scheduler::assert_task_pool_valid
void assert_task_pool_valid() const
Definition: scheduler.h:398

References __TBB_ASSERT, tbb::internal::generic_scheduler::assert_task_pool_valid(), tbb::internal::governor::local_scheduler_weak(), and tbb::internal::scheduler_state::my_innermost_running_task.

Referenced by tbb::parallel_while< Body >::add(), tbb::is_current_task_group_canceling(), and tbb::interface9::internal::quick_sort_pretest_body< RandomAccessIterator, Compare >::operator()().

Here is the call graph for this function:
Here is the caller graph for this function:

## set_affinity()

void tbb::task::set_affinity | ( | affinity_id | id | ) |

inline

Set affinity for this task.

Definition at line 943 of file task.h.

{prefix().affinity = id;}
id
void const char const char int ITT_FORMAT __itt_group_sync x void const char ITT_FORMAT __itt_group_sync s void ITT_FORMAT __itt_group_sync p void ITT_FORMAT p void ITT_FORMAT p no args __itt_suppress_mode_t unsigned int void size_t ITT_FORMAT d void ITT_FORMAT p void ITT_FORMAT p __itt_model_site __itt_model_site_instance ITT_FORMAT p __itt_model_task __itt_model_task_instance ITT_FORMAT p void ITT_FORMAT p void ITT_FORMAT p void size_t ITT_FORMAT d void ITT_FORMAT p const wchar_t ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s no args void ITT_FORMAT p size_t ITT_FORMAT d no args const wchar_t const wchar_t ITT_FORMAT s __itt_heap_function void size_t int ITT_FORMAT d __itt_heap_function void ITT_FORMAT p __itt_heap_function void void size_t int ITT_FORMAT d no args no args unsigned int ITT_FORMAT u const __itt_domain __itt_id id
Definition: ittnotify_static.h:172

References id.

Referenced by tbb::interface9::internal::linear_affinity_mode< Partition >::set_affinity(), and tbb::interface9::internal::affinity_partition_type::set_affinity().

Here is the caller graph for this function:

## set_group_priority()

__TBB_DEPRECATED void tbb::task::set_group_priority | ( | priority_t | p | ) |

inline

Changes priority of the task group this task belongs to.

Definition at line 981 of file task.h.

{ prefix().context->set_priority(p); }
tbb::task_group_context::set_priority
__TBB_DEPRECATED_IN_VERBOSE_MODE void set_priority(priority_t)
Changes priority of the task group.

References p.

## set_parent()

void tbb::task::set_parent | ( | task * | p | ) |

inline

sets parent task pointer to specified value

Definition at line 868 of file task.h.

{
#if __TBB_TASK_GROUP_CONTEXT
__TBB_ASSERT(!p || prefix().context == p->prefix().context, "The tasks must be in the same context");
#endif
prefix().parent = p;
}
tbb::task::context
task_group_context * context()
This method is deprecated and will be removed in the future.
Definition: task.h:878

References __TBB_ASSERT, and p.

Referenced by tbb::interface9::internal::allocate_sibling().

Here is the caller graph for this function:

## set_ref_count()

void tbb::task::set_ref_count | ( | int | count | ) |

inline

Set reference count.

Definition at line 761 of file task.h.

{
#if TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT
internal_set_ref_count(count);
#else
prefix().ref_count = count;
#endif /* TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT */
}
tbb::task::internal_set_ref_count
void __TBB_EXPORTED_METHOD internal_set_ref_count(int count)
Set reference count.
Definition: task.cpp:183

References count.

Referenced by tbb::interface9::internal::allocate_sibling(), tbb::internal::generic_scheduler::cleanup_master(), tbb::interface9::internal::do_group_task_forward< Iterator, Body, Item >::execute(), tbb::interface9::internal::do_group_task_input< Body, Item >::execute(), tbb::internal::spawner< N, function1, function2, function3 >::execute(), tbb::internal::sum_node< Range, Body >::execute(), tbb::internal::while_group_task< Body >::execute(), tbb::internal::pipeline_root_task::execute(), tbb::flow::interface10::graph::graph(), tbb::internal::parallel_invoke_helper::parallel_invoke_helper(), tbb::parallel_while< Body >::run(), tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_random_access_iterator(), tbb::interface9::internal::run_parallel_do(), tbb::internal::task_group_base::task_group_base(), tbb::flow::interface10::graph::wait_for_all(), and tbb::flow::interface10::graph::~graph().

Here is the caller graph for this function:

## spawn_and_wait_for_all() [1/2]

void tbb::task::spawn_and_wait_for_all | ( | task & | child | ) |

inline

Similar to spawn followed by wait_for_all, but more efficient.

Definition at line 800 of file task.h.

{
prefix().owner->wait_for_all( *this, &child );
}
tbb::internal::scheduler::wait_for_all
virtual void wait_for_all(task &parent, task *child)=0
For internal use only.
tbb::internal::task_prefix::owner
scheduler * owner
Obsolete. The scheduler that owns the task.
Definition: task.h:247

Referenced by tbb::interface9::internal::do_group_task_forward< Iterator, Body, Item >::execute(), tbb::interface9::internal::do_group_task_input< Body, Item >::execute(), tbb::internal::while_group_task< Body >::execute(), tbb::parallel_while< Body >::run(), tbb::internal::parallel_invoke_helper::run_and_finish(), tbb::interface9::internal::do_task_iter< Iterator, Body, Item >::run_for_random_access_iterator(), and tbb::interface9::internal::run_parallel_do().

Here is the caller graph for this function:

## spawn_and_wait_for_all() [2/2]

void tbb::task::spawn_and_wait_for_all | ( | task_list & | list | ) |

Similar to spawn followed by wait_for_all, but more efficient.

Definition at line 231 of file task.cpp.

{
generic_scheduler* s = governor::local_scheduler();
task* t = list.first;
if( t ) {
if( &t->prefix().next!=list.next_ptr )
s->local_spawn( t->prefix().next, *list.next_ptr );
list.clear();
}
s->local_wait_for_all( *this, t );
}
s
void const char const char int ITT_FORMAT __itt_group_sync s
Definition: ittnotify_static.h:91
tbb::internal::governor::local_scheduler
static generic_scheduler * local_scheduler()
Obtain the thread-local instance of the TBB scheduler.
Definition: governor.h:129

References tbb::task_list::clear(), tbb::task_list::first, tbb::internal::governor::local_scheduler(), tbb::internal::task_prefix::next, tbb::task_list::next_ptr, prefix(), and s.

Here is the call graph for this function:

## spawn_root_and_wait() [1/2]

static void tbb::task::spawn_root_and_wait | ( | task & | root | ) |

inline static

Spawn task allocated by allocate_root, wait for it to complete, and deallocate it.

Definition at line 808 of file task.h.

{
root.prefix().owner->spawn_root_and_wait( root, root.prefix().next );
}

References tbb::internal::task_prefix::next, tbb::internal::task_prefix::owner, prefix(), and tbb::internal::scheduler::spawn_root_and_wait().

Referenced by tbb::interface9::internal::start_reduce< Range, Body, Partitioner >::run(), tbb::interface9::internal::start_deterministic_reduce< Range, Body, Partitioner >::run(), tbb::interface9::internal::start_for< Range, Body, Partitioner >::run(), and tbb::internal::start_scan< Range, Body, Partitioner >::run().

Here is the call graph for this function:
Here is the caller graph for this function:

## spawn_root_and_wait() [2/2]

void tbb::task::spawn_root_and_wait | ( | task_list & | root_list | ) |

inline static

Spawn root tasks on list and wait for all of them to finish.

If there are more tasks than worker threads, the tasks are spawned in order of front to back.

Definition at line 1135 of file task.h.

{
if( task* t = root_list.first ) {
t->prefix().owner->spawn_root_and_wait( *t, *root_list.next_ptr );
root_list.clear();
}
}

References tbb::task_list::clear(), tbb::task_list::first, and tbb::task_list::next_ptr.

Here is the call graph for this function:

## state()

state_type tbb::task::state | ( |  | ) | const

inline

Current execution state.

Definition at line 912 of file task.h.

{return state_type(prefix().state);}
tbb::task::state_type
state_type
Enumeration of task states that the scheduler considers.
Definition: task.h:635

Referenced by tbb::internal::generic_scheduler::allocate_task(), tbb::interface5::internal::task_base::destroy(), tbb::internal::arena::enqueue_task(), tbb::internal::generic_scheduler::free_nonlocal_small_task(), tbb::internal::generic_scheduler::free_task(), tbb::internal::custom_scheduler< SchedulerTraits >::local_wait_for_all(), tbb::internal::generic_scheduler::prepare_for_spawning(), and tbb::internal::custom_scheduler< SchedulerTraits >::process_bypass_loop().

Here is the caller graph for this function:

## wait_for_all()

void tbb::task::wait_for_all | ( |  | ) |

inline

Wait for reference count to become one, and set reference count to zero.

Works on tasks while waiting.

Definition at line 819 of file task.h.

{
prefix().owner->wait_for_all( *this, NULL );
}

Referenced by tbb::flow::interface10::graph::wait_functor::operator()(), tbb::internal::task_group_base::wait(), and tbb::internal::task_group_base::~task_group_base().

Here is the caller graph for this function:

## Friends And Related Function Documentation

## interface5::internal::task_base

friend class interface5::internal::task_base

friend

Definition at line 989 of file task.h.

## internal::allocate_additional_child_of_proxy

friend class internal::allocate_additional_child_of_proxy

friend

Definition at line 998 of file task.h.

## internal::allocate_child_proxy

friend class internal::allocate_child_proxy

friend

Definition at line 997 of file task.h.

## internal::allocate_continuation_proxy

friend class internal::allocate_continuation_proxy

friend

Definition at line 996 of file task.h.

## internal::allocate_root_proxy

friend class internal::allocate_root_proxy

friend

Definition at line 992 of file task.h.

## internal::allocate_root_with_context_proxy

friend class internal::allocate_root_with_context_proxy

friend

Definition at line 994 of file task.h.

## internal::is_critical

bool internal::is_critical | ( | task & |  | ) |

friend

## internal::make_critical

void internal::make_critical | ( | task & |  | ) |

friend

## internal::scheduler

friend class internal::scheduler

friend

Definition at line 991 of file task.h.

## task_list

friend class task_list

friend

Definition at line 990 of file task.h.

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

- task.h
- task_arena.h
- task.cpp

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.