---

ACE_Task_Base Class Reference

Direct base class for the ACE_Task template. More...

#include <Task.h>

Inheritance diagram for ACE_Task_Base:

[legend]Collaboration diagram for ACE_Task_Base:

[legend]List of all members.

Public Methods
	ACE_Task_Base (ACE_Thread_Manager *=0)
	Constructor. More...
virtual	~ACE_Task_Base (void)
	Destructor. More...
virtual int	open (void *args=0)
	Hook called to open a Task. <args> can be used to pass arbitrary information into <open>. More...
virtual int	close (u_long flags=0)
virtual int	module_closed (void)
virtual int	put (ACE_Message_Block *, ACE_Time_Value *=0)
	A hook method that can be used to pass a message to a task, where it can be processed immediately or queued for subsequent processing in the <svc> hook method. More...
virtual int	svc (void)
	Run by a daemon thread to handle deferred processing. More...
virtual int	activate (long flags=THR_NEW_LWP|THR_JOINABLE, int n_threads=1, int force_active=0, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, ACE_Task_Base *task=0, ACE_hthread_t thread_handles[]=0, void *stack[]=0, size_t stack_size[]=0, ACE_thread_t thread_ids[]=0)
virtual int	wait (void)
virtual int	suspend (void)
	Suspend a task. More...
virtual int	resume (void)
	Resume a suspended task. More...
int	grp_id (void) const
	Get the current group id. More...
void	grp_id (int)
	Set the current group id. More...
ACE_Thread_Manager *	thr_mgr (void) const
	Get the thread manager associated with this Task. More...
void	thr_mgr (ACE_Thread_Manager *)
	Set the thread manager associated with this Task. More...
int	is_reader (void) const
	True if queue is a reader, else false. More...
int	is_writer (void) const
	True if queue is a writer, else false. More...
size_t	thr_count (void) const
void	thr_count_dec (void)
	Atomically decrement the thread count by 1. This should only be called by the <ACE_Thread_Exit> class destructor. More...
Static Public Methods
ACE_THR_FUNC_RETURN	svc_run (void *)
	Routine that runs the service routine as a daemon thread. More...
void	cleanup (void *object, void *params)
	Cleanup hook that is called when a thread exits to gracefully shutdown an <ACE_Task>. More...
Public Attributes
size_t	thr_count_
ACE_Thread_Manager *	thr_mgr_
	Multi-threading manager. More...
u_long	flags_
	ACE_Task flags. More...
int	grp_id_
	This maintains the group id of the Task. More...
Private Methods
ACE_Task_Base &	operator= (const ACE_Task_Base &)
	ACE_Task_Base (const ACE_Task_Base &)

---

Detailed Description

Direct base class for the ACE_Task template.

This class factors out the non-template code in order to reduce template bloat, as well as to make it possible for the <ACE_Thread_Manager> to store <ACE_Task_Base> *'s polymorphically.

Definition at line 65 of file Task.h.

---

Constructor & Destructor Documentation

ACE_Task_Base::ACE_Task_Base (  ACE_Thread_Manager *    = 0 )

Constructor. Definition at line 17 of file Task.cpp. : thr_count_ (0), thr_mgr_ (thr_man), flags_ (0), grp_id_ (-1) { }

ACE_Task_Base::~ACE_Task_Base (  void    )  [virtual]

Destructor. Definition at line 13 of file Task.cpp. { }

ACE_Task_Base::ACE_Task_Base (  const ACE_Task_Base &    )  [private]

---

Member Function Documentation

int ACE_Task_Base::activate (  long    flags = THR_NEW_LWP|THR_JOINABLE, int    n_threads = 1, int    force_active = 0, long    priority = ACE_DEFAULT_THREAD_PRIORITY, int    grp_id = -1, ACE_Task_Base *    task = 0, ACE_hthread_t    thread_handles[] = 0, void *    stack[] = 0, size_t    stack_size[] = 0, ACE_thread_t    thread_ids[] = 0 )  [virtual]

Turn the task into an active object, i.e., having <n_threads> of control, all running at the <priority> level (see below) with the same <grp_id>, all of which invoke <Task::svc>. Returns -1 if failure occurs, returns 1 if Task is already an active object and <force_active> is false (i.e., do *not* create a new thread in this case), and returns 0 if Task was not already an active object and a thread is created successfully or thread is an active object and <force_active> is true. Note that if <force_active> is true and there are already threads spawned in this <Task>, the <grp_id> parameter is ignored and the <grp_id> of any newly activated thread(s) will inherit the existing <grp_id> of the existing thread(s) in the <Task>. The <{flags}> are a bitwise-OR of the following: = BEGIN<INDENT> THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, THR_SCHED_RR, THR_SCHED_DEFAULT, THR_EXPLICIT_SCHED, THR_SCOPE_SYSTEM, THR_SCOPE_PROCESS = END<INDENT> By default, or if <{priority}> is set to ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for the given scheduling policy (specified in <{flags}>, e.g., <THR_SCHED_DEFAULT>) is used. This value is calculated dynamically, and is the median value between the minimum and maximum priority values for the given policy. If an explicit value is given, it is used. Note that actual priority values are EXTREMEMLY implementation-dependent, and are probably best avoided. If <thread_handles> != 0 it is assumed to be an array of <n> thread_handles that will be assigned the values of the thread handles being spawned. Returns -1 on failure (<errno> will explain...), otherwise returns the group id of the threads. Assigning <task> allows you to associate the newly spawned threads with an instance of ACE_Task_Base. If <task> == 0, then the new threads are associated automatically with <this> ACE_Task_Base. Setting the <task> argument to value other than <this> makes the thread manipulating methods, such as wait(), suspend(), resume(), useless. Threads spawned with user specified <task> value must therefore be manipulated thru ACE_Thread_Manager directly. If <stack> != 0 it is assumed to be an array of <n> pointers to the base of the stacks to use for the threads being spawned. Likewise, if <stack_size> != 0 it is assumed to be an array of <n> values indicating how big each of the corresponding <stack>s are. Reimplemented in ACE_Thread_Timer_Queue_Adapter. Definition at line 65 of file Task.cpp. References ACE_GUARD_RETURN, ACE_hthread_t, ACE_thread_t, ACE_TRACE, grp_id, grp_id_, ACE_Thread_Manager::instance, ACE_Event_Handler::priority, ACE_Thread_Manager::spawn_n, svc_run, thr_count_, and thr_mgr_. Referenced by ACE_Proactor::ACE_Proactor, ACE_Thread_Timer_Queue_Adapter::activate, and ACE_Asynch_Pseudo_Task::start. { ACE_TRACE ("ACE_Task_Base::activate"); #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, this->lock_, -1); // If the task passed in is zero, we will use <this> if (task == 0) task = this; if (this->thr_count_ > 0 && force_active == 0) return 1; // Already active. else { if (this->thr_count_ > 0 && grp_id != -1) // If we're joining an existing group of threads then make // sure to use its group id. grp_id = this->grp_id_; this->thr_count_ += n_threads; } // Use the ACE_Thread_Manager singleton if we're running as an // active object and the caller didn't supply us with a // Thread_Manager. if (this->thr_mgr_ == 0) # if defined (ACE_THREAD_MANAGER_LACKS_STATICS) this->thr_mgr_ = ACE_THREAD_MANAGER_SINGLETON::instance (); # else /* ! ACE_THREAD_MANAGER_LACKS_STATICS */ this->thr_mgr_ = ACE_Thread_Manager::instance (); # endif /* ACE_THREAD_MANAGER_LACKS_STATICS */ int grp_spawned = -1; if (thread_ids == 0) // Thread Ids were not specified grp_spawned = this->thr_mgr_->spawn_n (n_threads, &ACE_Task_Base::svc_run, (void *) this, flags, priority, grp_id, task, thread_handles, stack, stack_size); else // thread names were specified grp_spawned = this->thr_mgr_->spawn_n (thread_ids, n_threads, &ACE_Task_Base::svc_run, (void *) this, flags, priority, grp_id, stack, stack_size, thread_handles, task); if (grp_spawned == -1) { // If spawn_n fails, restore original thread count. this->thr_count_ -= n_threads; return -1; } if (this->grp_id_ == -1) this->grp_id_ = grp_spawned; return 0; #else { // Keep the compiler from complaining. ACE_UNUSED_ARG (flags); ACE_UNUSED_ARG (n_threads); ACE_UNUSED_ARG (force_active); ACE_UNUSED_ARG (priority); ACE_UNUSED_ARG (grp_id); ACE_UNUSED_ARG (task); ACE_UNUSED_ARG (thread_handles); ACE_UNUSED_ARG (stack); ACE_UNUSED_ARG (stack_size); ACE_UNUSED_ARG (thread_ids); ACE_NOTSUP_RETURN (-1); } #endif /* ACE_MT_SAFE */ }

void ACE_Task_Base::cleanup (  void *    object, void *    params )  [static]

Cleanup hook that is called when a thread exits to gracefully shutdown an <ACE_Task>. Definition at line 165 of file Task.cpp. References close, and thr_count_dec. Referenced by ACE_OS_Thread_Adapter::invoke, ACE_Thread_Adapter::invoke_i, and svc_run. { ACE_Task_Base *t = (ACE_Task_Base *) object; // The thread count must be decremented first in case the <close> // hook does something crazy like "delete this". t->thr_count_dec (); // @@ Is it possible to pass in the exit status somehow? t->close (); }

ACE_INLINE int ACE_Task_Base::close (  u_long    flags = 0 )  [virtual]

Hook called from <ACE_Thread_Exit> when during thread exit and from the default implementation of <module_closed>. In general, this method shouldn't be called directly by an application, particularly if the <Task> is running as an Active Object. Instead, a special message should be passed into the <Task> via the <put> method defined below, and the <svc> method should interpret this as a flag to shut down the <Task>. Reimplemented in ACE_Stream_Head. Definition at line 76 of file Task.i. References ACE_TRACE. Referenced by cleanup, and module_closed. { ACE_TRACE ("ACE_Task_Base::close"); return 0; }

ACE_INLINE void ACE_Task_Base::grp_id (  int    )

Set the current group id. Definition at line 103 of file Task.i. References ACE_GUARD, ACE_MT, ACE_TRACE, grp_id_, ACE_Thread_Manager::set_grp, and thr_mgr. { ACE_TRACE ("ACE_Task_Base::grp_id"); ACE_MT (ACE_GUARD (ACE_Thread_Mutex, ace_mon, this->lock_)); // Cache the group id in the task and then set it in the // Thread_Manager, if there is one. this->grp_id_ = id; if (this->thr_mgr ()) this->thr_mgr ()->set_grp (this, id); }

ACE_INLINE int ACE_Task_Base::grp_id (  void    )  const

Get the current group id. Definition at line 93 of file Task.i. References ACE_GUARD_RETURN, ACE_MT, ACE_TRACE, and grp_id_. Referenced by ACE_Thread_Timer_Queue_Adapter::activate, and activate. { ACE_TRACE ("ACE_Task_Base::grp_id"); ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, (ACE_Thread_Mutex &) this->lock_, -1)); return this->grp_id_; }

ACE_INLINE int ACE_Task_Base::is_reader (  void    )  const

True if queue is a reader, else false. Definition at line 42 of file Task.i. References ACE_BIT_ENABLED, ACE_Task_Flags::ACE_READER, and ACE_TRACE. { ACE_TRACE ("ACE_Task_Base::is_reader"); return (ACE_BIT_ENABLED (this->flags_, ACE_Task_Flags::ACE_READER)); }

ACE_INLINE int ACE_Task_Base::is_writer (  void    )  const

True if queue is a writer, else false. Definition at line 49 of file Task.i. References ACE_BIT_DISABLED, ACE_Task_Flags::ACE_READER, and ACE_TRACE. Referenced by ACE_Stream_Tail::put, and ACE_Stream_Head::put. { ACE_TRACE ("ACE_Task_Base::is_writer"); return (ACE_BIT_DISABLED (this->flags_, ACE_Task_Flags::ACE_READER)); }

int ACE_Task_Base::module_closed (  void    )  [virtual]

Hook called during <ACE_Module::close>. The default implementation calls forwards the call to close(1). Please notice the changed value of the default argument of <close>. This allows tasks to differ between the call has been originated from <ACE_Thread_Exit> or from <module_closed>. Be aware that close(0) will be also called when a thread associated with the ACE_Task instance exits. Definition at line 232 of file Task.cpp. References close. Referenced by ACE_Module< ACE_SYNCH_USE >::close_i. { return this->close (1); }

ACE_INLINE int ACE_Task_Base::open (  void *    args = 0 )  [virtual]

Hook called to open a Task. <args> can be used to pass arbitrary information into <open>. Reimplemented in ACE_NT_Service. Definition at line 67 of file Task.i. References ACE_TRACE. Referenced by ACE_Stream::insert, ACE_Stream::push_module, and ACE_Stream::replace. { ACE_TRACE ("ACE_Task_Base::open"); return 0; }

ACE_Task_Base& ACE_Task_Base::operator= (  const ACE_Task_Base &    )  [private]

ACE_INLINE int ACE_Task_Base::put (  ACE_Message_Block *   , ACE_Time_Value *    = 0 )  [virtual]

A hook method that can be used to pass a message to a task, where it can be processed immediately or queued for subsequent processing in the <svc> hook method. Reimplemented in ACE_Stream_Head. Definition at line 85 of file Task.i. References ACE_TRACE. Referenced by ACE_Stream::control, ACE_Stream::put, and ACE_Task< ACE_SYNCH_USE >::put_next. { ACE_TRACE ("ACE_Task_Base::put"); return 0; }

int ACE_Task_Base::resume (  void    )  [virtual]

Resume a suspended task. Reimplemented from ACE_Service_Object. Definition at line 54 of file Task.cpp. References ACE_GUARD_RETURN, ACE_MT, ACE_TRACE, ACE_Thread_Manager::resume_task, thr_count_, and thr_mgr_. Referenced by ACE_NT_Service::continue_requested, and ACE_Module_Type::resume. { ACE_TRACE ("ACE_Task_Base::resume"); ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, this->lock_, -1)); if (this->thr_count_ > 0) return this->thr_mgr_->resume_task (this); return 0; }

int ACE_Task_Base::suspend (  void    )  [virtual]

Suspend a task. Reimplemented from ACE_Service_Object. Definition at line 42 of file Task.cpp. References ACE_GUARD_RETURN, ACE_MT, ACE_TRACE, ACE_Thread_Manager::suspend_task, thr_count_, and thr_mgr_. Referenced by ACE_NT_Service::pause_requested, and ACE_Module_Type::suspend. { ACE_TRACE ("ACE_Task_Base::suspend"); ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, this->lock_, -1)); if (this->thr_count_ > 0) return this->thr_mgr_->suspend_task (this); return 0; }

ACE_INLINE int ACE_Task_Base::svc (  void    )  [virtual]

Run by a daemon thread to handle deferred processing. Reimplemented in ACE_Asynch_Pseudo_Task. Definition at line 58 of file Task.i. References ACE_TRACE. Referenced by svc_run. { ACE_TRACE ("ACE_Task_Base::svc"); return 0; }

ACE_THR_FUNC_RETURN ACE_Task_Base::svc_run (  void *    )  [static]

Routine that runs the service routine as a daemon thread. Definition at line 187 of file Task.cpp. References ACE_TRACE, ACE_Thread_Manager::at_exit, cleanup, svc, and thr_mgr. Referenced by activate, ACE_OS_Thread_Adapter::invoke, and ACE_Thread_Adapter::invoke_i. { ACE_TRACE ("ACE_Task_Base::svc_run"); ACE_Task_Base *t = (ACE_Task_Base *) args; // Register ourself with our <Thread_Manager>'s thread exit hook // mechanism so that our close() hook will be sure to get invoked // when this thread exits. #if defined ACE_HAS_SIG_C_FUNC t->thr_mgr ()->at_exit (t, ACE_Task_Base_cleanup, 0); #else t->thr_mgr ()->at_exit (t, ACE_Task_Base::cleanup, 0); #endif /* ACE_HAS_SIG_C_FUNC */ // Call the Task's svc() hook method. int svc_status = t->svc (); ACE_THR_FUNC_RETURN status; #if (defined (__BORLANDC__) && (__BORLANDC__ < 0x570)) || defined (__MINGW32__) || (defined (_MSC_VER) && (_MSC_VER <= 1200)) // Some compilers complain about reinterpret_cast from int to unsigned long... status = ACE_static_cast (ACE_THR_FUNC_RETURN, svc_status); #else status = ACE_reinterpret_cast (ACE_THR_FUNC_RETURN, svc_status); #endif /* (__BORLANDC__ < 0x570) || __MINGW32__ || _MSC_VER <= 1200 */ // If we changed this zero change the other if in OS.cpp Thread_Adapter::invoke #if 1 // Call the <Task->close> hook. ACE_Thread_Manager *thr_mgr_ptr = t->thr_mgr (); // This calls the Task->close () hook. t->cleanup (t, 0); // This prevents a second invocation of the cleanup code // (called later by <ACE_Thread_Manager::exit>. thr_mgr_ptr->at_exit (t, 0, 0); #endif return status; }

ACE_INLINE size_t ACE_Task_Base::thr_count (  void    )  const

Returns the number of threads currently running within a task. If we're a passive object this value is 0, else it's greater than 0. Definition at line 22 of file Task.i. References ACE_GUARD_RETURN, ACE_MT, ACE_TRACE, and thr_count_. Referenced by ACE_Module< ACE_SYNCH_USE >::close_i. { ACE_TRACE ("ACE_Task_Base::thr_count"); ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, (ACE_Thread_Mutex &) this->lock_, 0)); return this->thr_count_; }

ACE_INLINE void ACE_Task_Base::thr_count_dec (  void    )

Atomically decrement the thread count by 1. This should only be called by the <ACE_Thread_Exit> class destructor. Definition at line 33 of file Task.i. References ACE_GUARD, ACE_MT, ACE_TRACE, and thr_count_. Referenced by cleanup. { ACE_TRACE ("ACE_Task_Base::thr_count_dec"); ACE_MT (ACE_GUARD (ACE_Thread_Mutex, ace_mon, this->lock_)); this->thr_count_--; }

ACE_INLINE void ACE_Task_Base::thr_mgr (  ACE_Thread_Manager *    )

Set the thread manager associated with this Task. Definition at line 14 of file Task.i. References ACE_TRACE, and thr_mgr_. { ACE_TRACE ("ACE_Task_Base::thr_mgr"); this->thr_mgr_ = thr_mgr; }

ACE_INLINE ACE_Thread_Manager * ACE_Task_Base::thr_mgr (  void    )  const

Get the thread manager associated with this Task. Definition at line 7 of file Task.i. References ACE_TRACE, and thr_mgr_. Referenced by grp_id, ACE_OS_Thread_Adapter::invoke, ACE_Thread_Adapter::invoke_i, svc_run, wait, and ACE_Proactor_Timer_Handler::~ACE_Proactor_Timer_Handler. { ACE_TRACE ("ACE_Task_Base::thr_mgr"); return this->thr_mgr_; }

int ACE_Task_Base::wait (  void    )  [virtual]

Block until there are no more threads running in this task. This method will not wait for either detached or daemon threads; the threads must have been spawned with the THR_JOINABLE flag. Upon successful completion, the threads have been joined, so further attempts to join with any of the waited-for threads will fail. Return values: 0  Success. -1  Failure (consult errno for further information). Definition at line 28 of file Task.cpp. References ACE_TRACE, thr_mgr, and ACE_Thread_Manager::wait_task. Referenced by ACE_Module< ACE_SYNCH_USE >::close_i, and ACE_Asynch_Pseudo_Task::stop. { ACE_TRACE ("ACE_Task_Base::wait"); // If we don't have a thread manager, we probably were never // activated. if (this->thr_mgr () != 0) return this->thr_mgr ()->wait_task (this); else return 0; }

---

Member Data Documentation

u_long ACE_Task_Base::flags_

ACE_Task flags. Definition at line 256 of file Task.h. Referenced by ACE_Module< ACE_SYNCH_USE >::reader, and ACE_Module< ACE_SYNCH_USE >::writer.

int ACE_Task_Base::grp_id_

This maintains the group id of the Task. Definition at line 259 of file Task.h. Referenced by activate, and grp_id.

size_t ACE_Task_Base::thr_count_

Count of the number of threads running within the task. If this value is greater than 0 then we're an active object and the value of <thr_count_> is the number of active threads at this instant. If the value == 0, then we're a passive object. Definition at line 250 of file Task.h. Referenced by activate, resume, suspend, thr_count, and thr_count_dec.

ACE_Thread_Manager* ACE_Task_Base::thr_mgr_

Multi-threading manager. Definition at line 253 of file Task.h. Referenced by activate, resume, suspend, and thr_mgr.

---

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

• Task.h
• Task.cpp
• Task.i

---