Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

ACE_Task_Base Class Reference

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

#include <Task.h>

Inheritance diagram for ACE_Task_Base:

Inheritance graph
[legend]
Collaboration diagram for ACE_Task_Base:

Collaboration graph
[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_Managerthr_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_Managerthr_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.

00018   : thr_count_ (0),
00019     thr_mgr_ (thr_man),
00020     flags_ (0),
00021     grp_id_ (-1)
00022 {
00023 }

ACE_Task_Base::~ACE_Task_Base void    [virtual]
 

Destructor.

Definition at line 13 of file Task.cpp.

00014 {
00015 }

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.

00075 {
00076   ACE_TRACE ("ACE_Task_Base::activate");
00077 
00078 #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0)
00079   ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, this->lock_, -1);
00080 
00081   // If the task passed in is zero, we will use <this>
00082   if (task == 0)
00083     task = this;
00084 
00085   if (this->thr_count_ > 0 && force_active == 0)
00086     return 1; // Already active.
00087   else
00088     {
00089       if (this->thr_count_ > 0 && grp_id != -1)
00090         // If we're joining an existing group of threads then make
00091         // sure to use its group id.
00092         grp_id = this->grp_id_;
00093       this->thr_count_ += n_threads;
00094     }
00095 
00096   // Use the ACE_Thread_Manager singleton if we're running as an
00097   // active object and the caller didn't supply us with a
00098   // Thread_Manager.
00099   if (this->thr_mgr_ == 0)
00100 # if defined (ACE_THREAD_MANAGER_LACKS_STATICS)
00101     this->thr_mgr_ = ACE_THREAD_MANAGER_SINGLETON::instance ();
00102 # else /* ! ACE_THREAD_MANAGER_LACKS_STATICS */
00103     this->thr_mgr_ = ACE_Thread_Manager::instance ();
00104 # endif /* ACE_THREAD_MANAGER_LACKS_STATICS */
00105 
00106   int grp_spawned = -1;
00107   if (thread_ids == 0)
00108     // Thread Ids were not specified
00109     grp_spawned =
00110       this->thr_mgr_->spawn_n (n_threads,
00111                                &ACE_Task_Base::svc_run,
00112                                (void *) this,
00113                                flags,
00114                                priority,
00115                                grp_id,
00116                                task,
00117                                thread_handles,
00118                                stack,
00119                                stack_size);
00120   else
00121     // thread names were specified
00122     grp_spawned =
00123       this->thr_mgr_->spawn_n (thread_ids,
00124                                n_threads,
00125                                &ACE_Task_Base::svc_run,
00126                                (void *) this,
00127                                flags,
00128                                priority,
00129                                grp_id,
00130                                stack,
00131                                stack_size,
00132                                thread_handles,
00133                                task);
00134   if (grp_spawned == -1)
00135     {
00136       // If spawn_n fails, restore original thread count.
00137       this->thr_count_ -= n_threads;
00138       return -1;
00139     }
00140 
00141   if (this->grp_id_ == -1)
00142     this->grp_id_ = grp_spawned;
00143 
00144   return 0;
00145 
00146 #else
00147   {
00148     // Keep the compiler from complaining.
00149     ACE_UNUSED_ARG (flags);
00150     ACE_UNUSED_ARG (n_threads);
00151     ACE_UNUSED_ARG (force_active);
00152     ACE_UNUSED_ARG (priority);
00153     ACE_UNUSED_ARG (grp_id);
00154     ACE_UNUSED_ARG (task);
00155     ACE_UNUSED_ARG (thread_handles);
00156     ACE_UNUSED_ARG (stack);
00157     ACE_UNUSED_ARG (stack_size);
00158     ACE_UNUSED_ARG (thread_ids);
00159     ACE_NOTSUP_RETURN (-1);
00160   }
00161 #endif /* ACE_MT_SAFE */
00162 }

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.

00166 {
00167   ACE_Task_Base *t = (ACE_Task_Base *) object;
00168 
00169   // The thread count must be decremented first in case the <close>
00170   // hook does something crazy like "delete this".
00171   t->thr_count_dec ();
00172 
00173   // @@ Is it possible to pass in the exit status somehow?
00174   t->close ();
00175 }

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.

00077 {
00078   ACE_TRACE ("ACE_Task_Base::close");
00079   return 0;
00080 }

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.

00104 {
00105   ACE_TRACE ("ACE_Task_Base::grp_id");
00106   ACE_MT (ACE_GUARD (ACE_Thread_Mutex, ace_mon, this->lock_));
00107 
00108   // Cache the group id in the task and then set it in the
00109   // Thread_Manager, if there is one.
00110   this->grp_id_ = id;
00111   if (this->thr_mgr ())
00112     this->thr_mgr ()->set_grp (this, id);
00113 }

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.

00094 {
00095   ACE_TRACE ("ACE_Task_Base::grp_id");
00096   ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, (ACE_Thread_Mutex &) this->lock_, -1));
00097   return this->grp_id_;
00098 }

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.

00043 {
00044   ACE_TRACE ("ACE_Task_Base::is_reader");
00045   return (ACE_BIT_ENABLED (this->flags_, ACE_Task_Flags::ACE_READER));
00046 }

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.

00050 {
00051   ACE_TRACE ("ACE_Task_Base::is_writer");
00052   return (ACE_BIT_DISABLED (this->flags_, ACE_Task_Flags::ACE_READER));
00053 }

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.

00233 {
00234   return this->close (1);
00235 }

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.

00068 {
00069   ACE_TRACE ("ACE_Task_Base::open");
00070   return 0;
00071 }

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.

00086 {
00087   ACE_TRACE ("ACE_Task_Base::put");
00088   return 0;
00089 }

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.

00055 {
00056   ACE_TRACE ("ACE_Task_Base::resume");
00057   ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, this->lock_, -1));
00058   if (this->thr_count_ > 0)
00059     return this->thr_mgr_->resume_task (this);
00060 
00061   return 0;
00062 }

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.

00043 {
00044   ACE_TRACE ("ACE_Task_Base::suspend");
00045   ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, this->lock_, -1));
00046   if (this->thr_count_ > 0)
00047     return this->thr_mgr_->suspend_task (this);
00048 
00049   return 0;
00050 }

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.

00059 {
00060   ACE_TRACE ("ACE_Task_Base::svc");
00061   return 0;
00062 }

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.

00188 {
00189   ACE_TRACE ("ACE_Task_Base::svc_run");
00190 
00191   ACE_Task_Base *t = (ACE_Task_Base *) args;
00192 
00193   // Register ourself with our <Thread_Manager>'s thread exit hook
00194   // mechanism so that our close() hook will be sure to get invoked
00195   // when this thread exits.
00196 
00197 #if defined ACE_HAS_SIG_C_FUNC
00198   t->thr_mgr ()->at_exit (t, ACE_Task_Base_cleanup, 0);
00199 #else
00200   t->thr_mgr ()->at_exit (t, ACE_Task_Base::cleanup, 0);
00201 #endif /* ACE_HAS_SIG_C_FUNC */
00202 
00203   // Call the Task's svc() hook method.
00204   int svc_status = t->svc ();
00205   ACE_THR_FUNC_RETURN status;
00206 #if (defined (__BORLANDC__) && (__BORLANDC__ < 0x570)) || defined (__MINGW32__) || (defined (_MSC_VER) && (_MSC_VER <= 1200))
00207   // Some compilers complain about reinterpret_cast from int to unsigned long...
00208   status = ACE_static_cast (ACE_THR_FUNC_RETURN, svc_status);
00209 #else
00210   status = ACE_reinterpret_cast (ACE_THR_FUNC_RETURN, svc_status);
00211 #endif /* (__BORLANDC__ < 0x570) || __MINGW32__ || _MSC_VER <= 1200 */
00212 
00213 // If we changed this zero change the other if in OS.cpp Thread_Adapter::invoke
00214 #if 1
00215   // Call the <Task->close> hook.
00216   ACE_Thread_Manager *thr_mgr_ptr = t->thr_mgr ();
00217 
00218   // This calls the Task->close () hook.
00219   t->cleanup (t, 0);
00220 
00221   // This prevents a second invocation of the cleanup code
00222   // (called later by <ACE_Thread_Manager::exit>.
00223   thr_mgr_ptr->at_exit (t, 0, 0);
00224 #endif
00225   return status;
00226 }

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.

00023 {
00024   ACE_TRACE ("ACE_Task_Base::thr_count");
00025   ACE_MT (ACE_GUARD_RETURN (ACE_Thread_Mutex, ace_mon, (ACE_Thread_Mutex &) this->lock_, 0));
00026 
00027   return this->thr_count_;
00028 }

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.

00034 {
00035   ACE_TRACE ("ACE_Task_Base::thr_count_dec");
00036   ACE_MT (ACE_GUARD (ACE_Thread_Mutex, ace_mon, this->lock_));
00037 
00038   this->thr_count_--;
00039 }

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

00015 {
00016   ACE_TRACE ("ACE_Task_Base::thr_mgr");
00017   this->thr_mgr_ = thr_mgr;
00018 }

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.

00008 {
00009   ACE_TRACE ("ACE_Task_Base::thr_mgr");
00010   return this->thr_mgr_;
00011 }

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.

00029 {
00030   ACE_TRACE ("ACE_Task_Base::wait");
00031 
00032   // If we don't have a thread manager, we probably were never
00033   // activated.
00034   if (this->thr_mgr () != 0)
00035     return this->thr_mgr ()->wait_task (this);
00036   else
00037     return 0;
00038 }


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:
Generated on Mon Jun 16 12:57:21 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002