- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Class List
- Class Hierarchy
- Class Members

# tbb::task Class Reference
[Task Scheduling]

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

`#include <task.h>`

Inheritance diagram for tbb::task:

List of all members.

## Public Types
typedef internal::affinity_id | affinity_id
| An id as used for specifying affinity.
| 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
enum | state_type { executing, reexecute, ready, allocated, freed, recycle }
| Enumeration of task states that the scheduler considers. More...
## Public Member Functions
virtual | ~task ()
| Destructor.
virtual task * | execute ()=0
| Should be overridden by derived classes.
internal::allocate_continuation_proxy & | allocate_continuation ()
| Returns proxy for overloaded new that allocates a continuation task of *this.
internal::allocate_child_proxy & | allocate_child ()
| Returns proxy for overloaded new that allocates a child task of *this.
void __TBB_EXPORTED_METHOD | destroy (task &t)
| Destroy a task.
void | recycle_as_continuation ()
| Change this to be a continuation of its former self.
void | recycle_as_safe_continuation ()
| Recommended to use, safe variant of recycle_as_continuation.
void | recycle_as_child_of (task &new_parent)
| Change this to be a child of new_parent.
void | recycle_to_reexecute ()
| Schedule this for reexecution after current execute() returns.
intptr_t | depth () const
void | set_depth (intptr_t)
void | add_to_depth (int)
void | set_ref_count (int count)
| Set reference count.
void | increment_ref_count ()
| Atomically increment reference count and returns its old value.
int | decrement_ref_count ()
| Atomically decrement reference count and returns its new value.
void | spawn_and_wait_for_all (task &child)
| Similar to spawn followed by wait_for_all, but more efficient.
void __TBB_EXPORTED_METHOD | spawn_and_wait_for_all (task_list &list)
| Similar to spawn followed by wait_for_all, but more efficient.
void | wait_for_all ()
| Wait for reference count to become one, and set reference count to zero.
task * | parent () const
| task on whose behalf this task is working, or NULL if this is a root.
task_group_context * | context ()
| Shared context that is used to communicate asynchronous state changes.
bool | is_stolen_task () const
| True if task was stolen from the task pool of another thread.
state_type | state () const
| Current execution state.
int | ref_count () const
| The internal reference count.
bool __TBB_EXPORTED_METHOD | is_owned_by_current_thread () const
| Obsolete, and only retained for the sake of backward compatibility. Always returns true.
void | set_affinity (affinity_id id)
| Set affinity for this task.
affinity_id | affinity () const
| Current affinity of this task.
virtual void __TBB_EXPORTED_METHOD | note_affinity (affinity_id id)
| Invoked by scheduler to notify task that it ran on unexpected thread.
bool | cancel_group_execution ()
| Initiates cancellation of all tasks in this cancellation group and its subordinate groups.
bool | is_cancelled () const
| Returns true if the context received cancellation request.
## Static Public Member Functions
static internal::allocate_root_proxy | allocate_root ()
| Returns proxy for overloaded new that allocates a root task.
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.
static void | spawn_root_and_wait (task &root)
| Spawn task allocated by allocate_root, wait for it to complete, and deallocate it.
static void | spawn_root_and_wait (task_list &root_list)
| Spawn root tasks on list and wait for all of them to finish.
static void | enqueue (task &t)
| Enqueue task for starvation-resistant execution.
static task &__TBB_EXPORTED_FUNC | self ()
| The innermost task being executed or destroyed by the current thread at the moment.
## Protected Member Functions
| task ()
| Default constructor.
## 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

## Detailed Description

Base class for user-defined tasks.

## Member Typedef Documentation

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.

## Member Enumeration Documentation

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

## Member Function Documentation

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.

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.

int tbb::task::decrement_ref_count | ( |  | ) | `[inline]`

Atomically decrement reference count and returns its new value.

Has release semantics.

void __TBB_EXPORTED_METHOD tbb::task::destroy | ( | task & | t | ) |

Destroy a task.

Usually, calling this method is unnecessary, because a task is implicitly deleted after its execute() method runs. However, sometimes a task needs to be explicitly deallocated, such as when a root task is used as the parent in spawn_and_wait_for_all.

void tbb::task::increment_ref_count | ( |  | ) | `[inline]`

Atomically increment reference count and returns its old value.

Has acquire semantics

virtual void __TBB_EXPORTED_METHOD 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.

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.

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 decendants and ref_count of 1, it has the semantics of 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.

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.

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.

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

- task.h

Copyright © 2005-2010 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.