Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | Related Pages

tbb::task Class Reference

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

#include <task.h>

Inherits tbb::internal::no_copy.

Inherited by tbb::empty_task, tbb::internal::do_group_task_forward< Iterator, Body, Item >, tbb::internal::do_group_task_input< Body, Item >, tbb::internal::do_iteration_task< Body, Item >, tbb::internal::do_iteration_task_iter< Iterator, Body, Item >, tbb::internal::do_task_iter< Iterator, Body, Item >, tbb::internal::final_sum< Range, Body >, tbb::internal::finish_reduce< Body >, tbb::internal::finish_reduce_with_affinity< Body >, tbb::internal::finish_scan< Range, Body >, tbb::internal::start_for< Range, Body, Partitioner >, tbb::internal::start_reduce< Range, Body, Partitioner >, tbb::internal::start_reduce_with_affinity< Range, Body >, tbb::internal::start_scan< Range, Body, Partitioner >, tbb::internal::sum_node< Range, Body >, tbb::internal::while_group_task< Body >, tbb::internal::while_iteration_task< Body >, and tbb::internal::while_task< Stream, Body >.

Inheritance diagram for tbb::task:

[legend]
List of all members.

Public Types

typedef internal::intptr depth_type
 A scheduling depth.
typedef internal::affinity_id affinity_id
 An id as used for specifying affinity.
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 taskexecute ()=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.
internal::allocate_additional_child_of_proxy allocate_additional_child_of (task &t)
 Like allocate_child, except that task's parent becomes "t", not this.
void destroy (task &victim)
 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.
depth_type depth () const
 Scheduling depth.
void set_depth (depth_type new_depth)
 Set scheduling depth to given value.
void add_to_depth (int delta)
 Change scheduling depth by given amount.
void set_ref_count (int count)
 Set reference count.
void spawn (task &child)
 Schedule task for execution when a worker becomes available.
void spawn (task_list &list)
 Spawn multiple tasks and clear list.
void spawn_and_wait_for_all (task &child)
 Similar to spawn followed by wait_for_all, but more efficient.
void 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.
taskparent () const
 task on whose behalf this task is working, or NULL if this is a root.
bool is_stolen_task () const
 True if task is owned by different thread than thread that owns its parent.
state_type state () const
 Current execution state.
int ref_count () const
 The internal reference count.
bool is_owned_by_current_thread () const
 True if this task is owned by the calling thread; false otherwise.
void set_affinity (affinity_id id)
 Set affinity for this task.
affinity_id affinity () const
 Current affinity of this task.
virtual void note_affinity (affinity_id id)
 Invoked by scheduler to notify task that it ran on unexpected thread.

Static Public Member Functions

internal::allocate_root_proxy allocate_root ()
 Returns proxy for overloaded new that allocates a root task.
void spawn_root_and_wait (task &root)
 Spawn task allocated by allocate_root, wait for it to complete, and deallocate it.
void spawn_root_and_wait (task_list &root_list)
 Spawn root tasks on list and wait for all of them to finish.
taskself ()
 The task() currently being run by this thread.

Protected Member Functions

 task ()
 Default constructor.

Friends

class task_list
class internal::scheduler
class internal::allocate_root_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.

typedef internal::intptr tbb::task::depth_type
 

A scheduling depth.

Guaranteed to be a signed integral type.


Member Enumeration Documentation

enum tbb::task::state_type
 

Enumeration of task states that the scheduler considers.

Enumeration values:
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

void tbb::task::add_to_depth int  delta  )  [inline]
 

Change scheduling depth by given amount.

The resulting depth must be non-negative.

internal::allocate_additional_child_of_proxy tbb::task::allocate_additional_child_of task t  )  [inline]
 

Like allocate_child, except that task's parent becomes "t", not this.

Typically used in conjunction with schedule_to_reexecute to implement while loops. Atomically increments the reference count of t.parent()

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.

void tbb::task::destroy task victim  ) 
 

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.

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

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.

void tbb::task::recycle_to_reexecute  )  [inline]
 

Schedule this for reexecution after current execute() returns.

Requires that this.execute() be running.

void tbb::task::set_depth depth_type  new_depth  )  [inline]
 

Set scheduling depth to given value.

The depth must be non-negative

void tbb::task::spawn task_list list  )  [inline]
 

Spawn multiple tasks and clear list.

All of the tasks must be at the same depth.

void tbb::task::spawn task child  )  [inline]
 

Schedule task for execution when a worker becomes available.

After all children spawned so far finish their method task::execute, their parent's method task::execute may start running. Therefore, it is important to ensure that at least one child has not completed until the parent is ready to run.

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::spawn_root_and_wait task root  )  [inline, static]
 

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

The thread that calls spawn_root_and_wait must be the same thread that allocated the task.

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:

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