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

#include <task.h>

Inheritance diagram for tbb::task:

[legend]

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

Detailed Description

Definition at line 456 of file task.h.

Member Typedef Documentation

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

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

Definition at line 691 of file task.h.

Member Enumeration Documentation

enum tbb::task::state_type

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 476 of file task.h.

                    {
        executing,
        reexecute,
        ready,
        allocated,
        freed,
        recycle 
    };

Constructor & Destructor Documentation

tbb::task::task ( ) [inline, protected]

Definition at line 466 of file task.h.

{prefix().extra_state=1;}

virtual tbb::task::~task ( ) [inline, virtual]

Definition at line 470 of file task.h.

{}

Member Function Documentation

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

Definition at line 584 of file task.h.

{}

affinity_id tbb::task::affinity ( ) const [inline]

Definition at line 697 of file task.h.

{return prefix().affinity;}

internal::allocate_child_proxy& tbb::task::allocate_child ( ) [inline]

Definition at line 514 of file task.h.

References internal::allocate_child_proxy.

Referenced by SimpleSumTask::execute(), and OptimizedSumTask::execute().

                                                   {
        return *reinterpret_cast<internal::allocate_child_proxy*>(this);
    }

internal::allocate_continuation_proxy& tbb::task::allocate_continuation ( ) [inline]

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

Definition at line 509 of file task.h.

References internal::allocate_continuation_proxy.

                                                                 {
        return *reinterpret_cast<internal::allocate_continuation_proxy*>(this);
    }

static internal::allocate_root_proxy tbb::task::allocate_root ( ) [inline, static]

Definition at line 496 of file task.h.

References internal::allocate_root_proxy.

Referenced by TreeMaker< use_tbbmalloc >::do_in_parallel(), OptimizedParallelSumTree(), tbb::parallel_while< Body >::run(), SimpleParallelSumTree(), and tbb::internal::task_group_base::task_group_base().

                                                       {
        return internal::allocate_root_proxy();
    }

static internal::allocate_root_with_context_proxy tbb::task::allocate_root ( task_group_context & ctx ) [inline, static]

Definition at line 502 of file task.h.

References internal::allocate_root_with_context_proxy.

                                                                                             {
        return internal::allocate_root_with_context_proxy(ctx);
    }

bool tbb::task::cancel_group_execution ( ) [inline]

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

Definition at line 709 of file task.h.

{ return prefix().context->cancel_group_execution(); }

task_group_context* tbb::task::context ( ) [inline]

Definition at line 658 of file task.h.

Referenced by recycle_as_child_of().

{return prefix().context;}

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

Has release semantics.

Definition at line 608 of file task.h.

References ref_count().

                              {
#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 */
    }

intptr_t tbb::task::depth ( ) const [inline]

Definition at line 582 of file task.h.

{return 0;}

static void tbb::task::enqueue ( task & t ) [inline, static]

Definition at line 645 of file task.h.

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

virtual task* tbb::task::execute ( ) [pure virtual]

Implemented in OptimizedSumTask, SimpleSumTask, ConcurrentHashSerialFibTask, QueueInsertTask, QueueProcessTask, and FibTask.

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

Has acquire semantics

Definition at line 602 of file task.h.

References ref_count().

                               {
        __TBB_FetchAndIncrementWacquire( &prefix().ref_count );
    }

bool tbb::task::is_cancelled ( ) const [inline]

Definition at line 712 of file task.h.

Referenced by tbb::is_current_task_group_canceling().

{ return prefix().context->is_group_execution_cancelled(); }

bool tbb::task::is_owned_by_current_thread ( ) const

bool tbb::task::is_stolen_task ( ) const [inline]

Definition at line 662 of file task.h.

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

virtual void tbb::task::note_affinity ( affinity_id id ) [virtual]

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.

task* tbb::task::parent ( ) const [inline]

Definition at line 654 of file task.h.

{return prefix().parent;}

void tbb::task::recycle_as_child_of ( task & new_parent ) [inline]

Definition at line 558 of file task.h.

References allocated, context(), executing, ref_count(), and state().

                                                 {
        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 */
    }

void tbb::task::recycle_as_continuation ( ) [inline]

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 544 of file task.h.

References executing, and state().

Referenced by OptimizedSumTask::execute().

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

void tbb::task::recycle_as_safe_continuation ( ) [inline]

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.

Definition at line 552 of file task.h.

References executing, and state().

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

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

Made obsolete by recycle_as_safe_continuation; may become deprecated.

Definition at line 574 of file task.h.

References executing, ref_count(), and state().

                                {
        __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;
    }

int tbb::task::ref_count ( ) const [inline]

Definition at line 674 of file task.h.

Referenced by decrement_ref_count(), increment_ref_count(), recycle_as_child_of(), recycle_to_reexecute(), tbb::structured_task_group::~structured_task_group(), and tbb::task_group::~task_group().

                          {
#if TBB_USE_ASSERT
        internal::reference_count ref_count_ = prefix().ref_count;
        __TBB_ASSERT( ref_count_==int(ref_count_), "integer overflow error");
#endif
        return int(prefix().ref_count);
    }

static task& tbb::task::self ( ) [static]

Referenced by tbb::parallel_while< Body >::add(), and tbb::is_current_task_group_canceling().

void tbb::task::set_affinity ( affinity_id id ) [inline]

Definition at line 694 of file task.h.

{prefix().affinity = id;}

void tbb::task::set_depth ( intptr_t ) [inline]

Definition at line 583 of file task.h.

{}

void tbb::task::set_ref_count ( int count ) [inline]

Definition at line 592 of file task.h.

Referenced by SimpleSumTask::execute(), OptimizedSumTask::execute(), tbb::internal::task_group_base::task_group_base(), tbb::structured_task_group::wait(), and tbb::structured_task_group::~structured_task_group().

                                    {
#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 */
    }

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

void tbb::task::spawn_and_wait_for_all ( task & child ) [inline]

Definition at line 620 of file task.h.

Referenced by SimpleSumTask::execute().

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

static void tbb::task::spawn_root_and_wait ( task & root ) [inline, static]

Definition at line 628 of file task.h.

Referenced by TreeMaker< use_tbbmalloc >::do_in_parallel(), OptimizedParallelSumTree(), and SimpleParallelSumTree().

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

void tbb::task::spawn_root_and_wait ( task_list & root_list ) [inline, static]

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

Definition at line 795 of file task.h.

References tbb::task_list::clear().

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

state_type tbb::task::state ( ) const [inline]

Definition at line 671 of file task.h.

Referenced by recycle_as_child_of(), recycle_as_continuation(), recycle_as_safe_continuation(), and recycle_to_reexecute().

{return state_type(prefix().state);}

void tbb::task::wait_for_all ( ) [inline]

Works on tasks while waiting.

Definition at line 639 of file task.h.

Referenced by tbb::internal::task_group_base::wait(), tbb::structured_task_group::~structured_task_group(), and tbb::task_group::~task_group().

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

Friends And Related Function Documentation

friend class interface5::internal::task_base [friend]

Definition at line 716 of file task.h.

friend class internal::allocate_additional_child_of_proxy [friend]

Definition at line 725 of file task.h.

friend class internal::allocate_child_proxy [friend]

Definition at line 724 of file task.h.

Referenced by allocate_child().

friend class internal::allocate_continuation_proxy [friend]

Definition at line 723 of file task.h.

Referenced by allocate_continuation().

friend class internal::allocate_root_proxy [friend]

Definition at line 719 of file task.h.

Referenced by allocate_root().

friend class internal::allocate_root_with_context_proxy [friend]

Definition at line 721 of file task.h.

Referenced by allocate_root().

friend class internal::scheduler [friend]

Definition at line 718 of file task.h.

friend class task_list [friend]

Definition at line 717 of file task.h.

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

task.h

tbb::task Class Reference [Task Scheduling]

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions