dep/ACE_wrappers/ace/Task.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Task.h
   6  *
   7  *  $Id: Task.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  10  */
  11 //=============================================================================
  12
  13 #ifndef ACE_TASK_H
  14 #define ACE_TASK_H
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/Service_Object.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/Thread_Manager.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 /**
  28  * @class ACE_Task_Flags
  29  *
  30  * @brief These flags are used within the ACE_Task.
  31  *
  32  *    These flags should be hidden within ACE_Task.  Unfortunately, the
  33  *    HP/UX C++ compiler can't grok this...  Fortunately, there's no
  34  *    code defined here, so we don't have to worry about multiple
  35  *    definitions.
  36  */
  37 namespace ACE_Task_Flags
  38 {
  39   enum
  40   {
  41     /// Identifies a Task as being the "reader" in a Module.
  42     ACE_READER     = 01,
  43     /// Just flush data messages in the queue.
  44     ACE_FLUSHDATA  = 02,
  45     /// Flush all messages in the Queue.
  46     ACE_FLUSHALL   = 04,
  47     /// Flush read queue
  48     ACE_FLUSHR     = 010,
  49     /// Flush write queue
  50     ACE_FLUSHW     = 020,
  51     /// Flush both queues
  52     ACE_FLUSHRW    = 030
  53   };
  54 }
  55
  56 /**
  57  * @class ACE_Task_Base
  58  *
  59  * @brief Direct base class for the ACE_Task template.
  60  *
  61  * This class factors out the non-template code in order to
  62  * reduce template bloat, as well as to make it possible for the
  63  * ACE_Thread_Manager to store ACE_Task_Base *'s
  64  * polymorphically.
  65  */
  66 class ACE_Export ACE_Task_Base : public ACE_Service_Object
  67 {
  68 public:
  69   // = Initialization and termination methods.
  70   /// Constructor.
  71   ACE_Task_Base (ACE_Thread_Manager * = 0);
  72
  73   /// Destructor.
  74   virtual ~ACE_Task_Base (void);
  75
  76   // = Initialization and termination hooks.
  77
  78   // These methods should be overridden by subclasses if you'd like to
  79   // provide <Task>-specific initialization and termination behavior.
  80
  81   /// Hook called to initialize a task and prepare it for execution.
  82   /// @a args can be used to pass arbitrary information into <open>.
  83   virtual int open (void *args = 0);
  84
  85   /**
  86    * Hook called from ACE_Thread_Exit when during thread exit and from
  87    * the default implementation of <module_closed>.  In general, this
  88    * method shouldn't be called directly by an application,
  89    * particularly if the <Task> is running as an Active Object.
  90    * Instead, a special message should be passed into the <Task> via
  91    * the <put> method defined below, and the <svc> method should
  92    * interpret this as a flag to shut down the <Task>.
  93    */
  94   virtual int close (u_long flags = 0);
  95
  96   /**
  97    * Hook called during <ACE_Module::close>.  The default
  98    * implementation calls forwards the call to close(1).  Please
  99    * notice the changed value of the default argument of <close>.
 100    * This allows tasks to differ between the call has been originated
 101    * from <ACE_Thread_Exit> or from <module_closed>.  Be aware that
 102    * close(0) will be also called when a thread associated with the
 103    * ACE_Task instance exits.
 104    */
 105   virtual int module_closed (void);
 106
 107   // = Immediate and deferred processing methods, respectively.
 108
 109   // These methods should be overridden by subclasses if you'd like to
 110   // provide <Task>-specific message processing behavior.
 111
 112   /// A hook method that can be used to pass a message to a
 113   /// task, where it can be processed immediately or queued for subsequent
 114   /// processing in the <svc> hook method.
 115   virtual int put (ACE_Message_Block *, ACE_Time_Value * = 0);
 116
 117   /// Run by a daemon thread to handle deferred processing.
 118   virtual int svc (void);
 119
 120   // = Active object activation method.
 121   /**
 122    * Turn the task into an active object, i.e., having @a n_threads of
 123    * control, all running at the @a priority level (see below) with the
 124    * same @a grp_id, all of which invoke <Task::svc>.  Returns -1 if
 125    * failure occurs, returns 1 if Task is already an active object and
 126    * @a force_active is false (i.e., do *not* create a new thread in
 127    * this case), and returns 0 if Task was not already an active
 128    * object and a thread is created successfully or thread is an
 129    * active object and @a force_active is true.  Note that if
 130    * @a force_active is true and there are already threads spawned in
 131    * this <Task>, the @a grp_id parameter is ignored and the @a grp_id
 132    * of any newly activated thread(s) will inherit the existing
 133    * @a grp_id of the existing thread(s) in the <Task>.
 134    *
 135    * The <{flags}> are a bitwise-OR of the following:
 136    * = BEGIN<INDENT>
 137    * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED,
 138    * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED,
 139    * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO,
 140    * THR_SCHED_RR, THR_SCHED_DEFAULT, THR_EXPLICIT_SCHED,
 141    * THR_SCOPE_SYSTEM, THR_SCOPE_PROCESS
 142    * = END<INDENT>
 143    * If THR_SCHED_INHERIT is not desirable, applications should
 144    * specifically pass in THR_EXPLICIT_SCHED.
 145    *
 146    *
 147    * By default, or if <{priority}> is set to
 148    * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for
 149    * the given scheduling policy (specified in <{flags}>, e.g.,
 150    * <THR_SCHED_DEFAULT>) is used.  This value is calculated
 151    * dynamically, and is the median value between the minimum and
 152    * maximum priority values for the given policy.  If an explicit
 153    * value is given, it is used.  Note that actual priority values are
 154    * EXTREMEMLY implementation-dependent, and are probably best
 155    * avoided.
 156    *
 157    * If @a thread_handles != 0 it is assumed to be an array of @a n
 158    * thread_handles that will be assigned the values of the thread
 159    * handles being spawned.  Returns -1 on failure (@c errno will
 160    * explain...), otherwise returns the group id of the threads.
 161    *
 162    * Assigning @a task allows you to associate the newly spawned
 163    * threads with an instance of ACE_Task_Base.  If @a task == 0, then
 164    * the new threads are associated automatically with @c this
 165    * ACE_Task_Base.  Setting the @a task argument to value other than
 166    * @c this makes the thread manipulating methods, such as wait(),
 167    * suspend(), resume(), useless.  Threads spawned with user
 168    * specified @a task value must therefore be manipulated thru
 169    * ACE_Thread_Manager directly.
 170    *
 171    * If @a stack != 0 it is assumed to be an array of @a n pointers to
 172    * the base of the stacks to use for the threads being spawned.
 173    * Likewise, if @a stack_size != 0 it is assumed to be an array of
 174    * @a n values indicating how big each of the corresponding @a stacks
 175    * are.
 176    *
 177    *
 178    */
 179   virtual int activate (long flags = THR_NEW_LWP | THR_JOINABLE | THR_INHERIT_SCHED,
 180                         int n_threads = 1,
 181                         int force_active = 0,
 182                         long priority = ACE_DEFAULT_THREAD_PRIORITY,
 183                         int grp_id = -1,
 184                         ACE_Task_Base *task = 0,
 185                         ACE_hthread_t thread_handles[] = 0,
 186                         void *stack[] = 0,
 187                         size_t stack_size[] = 0,
 188                         ACE_thread_t thread_ids[] = 0,
 189                         const char* thr_name[] = 0);
 190
 191   /**
 192    * Block until there are no more threads running in this task.
 193    * This method will not wait for either detached or daemon threads;
 194    * the threads must have been spawned with the @c THR_JOINABLE flag.
 195    * Upon successful completion, the threads have been joined, so further
 196    * attempts to join with any of the waited-for threads will fail.
 197    *
 198    * @retval 0  Success.
 199    * @retval -1 Failure (consult errno for further information).
 200    */
 201   virtual int wait (void);
 202
 203   // = Suspend/resume a Task.
 204
 205   // Note that these methods are not portable and should be avoided
 206   // since they are inherently error-prone to use.  They are only here
 207   // for (the rare) applications that know how to use them correctly.
 208   /// Suspend a task.
 209   virtual int suspend (void);
 210   /// Resume a suspended task.
 211   virtual int resume (void);
 212
 213   /// Get the current group id.
 214   int grp_id (void) const;
 215
 216   /// Set the current group id.
 217   void grp_id (int);
 218
 219   /// Get the thread manager associated with this Task.
 220   ACE_Thread_Manager *thr_mgr (void) const;
 221
 222   /// Set the thread manager associated with this Task.
 223   void thr_mgr (ACE_Thread_Manager *);
 224
 225   /// True if queue is a reader, else false.
 226   int is_reader (void) const;
 227
 228   /// True if queue is a writer, else false.
 229   int is_writer (void) const;
 230
 231   /**
 232    * Returns the number of threads currently running within a task.
 233    * If we're a passive object this value is 0, else it's greater than
 234    * 0.
 235    */
 236   size_t thr_count (void) const;
 237
 238   /**
 239    * Returns the thread ID of the thread whose exit caused this object's
 240    * thread count to be decremented to 0.
 241    *
 242    * When a thread spawned in the context of this object (using activate())
 243    * returns from its svc() method ACE calls the close() hook. Before it does
 244    * so, it decrements the number of active threads. If the number of threads
 245    * is decremented to 0, the thread ID of the current thread is stored for
 246    * access by this method. If the returned thread ID matches the calling
 247    * thread's ID, the calling thread knows that there are no other threads
 248    * still active in the ACE_Task.
 249    *
 250    * @retval  ACE_thread_t of the last thread to close. 0 if the last thread
 251    *          is not yet known; for example, if no threads are active, or if
 252    *          multiple threads are active.
 253    */
 254   ACE_thread_t last_thread (void) const;
 255
 256   /// Routine that runs the service routine as a daemon thread.
 257   static ACE_THR_FUNC_RETURN svc_run (void *);
 258
 259   /// Cleanup hook that is called when a thread exits to gracefully
 260   /// shutdown an ACE_Task.
 261   static void cleanup (void *object, void *params);
 262
 263 protected:
 264   /**
 265    * Count of the number of threads running within the task.  If this
 266    * value is greater than 0 then we're an active object and the value
 267    * of <thr_count_> is the number of active threads at this instant.
 268    * If the value == 0, then we're a passive object.
 269    */
 270   size_t thr_count_;
 271
 272   /// Multi-threading manager.
 273   ACE_Thread_Manager *thr_mgr_;
 274
 275   /// ACE_Task flags.
 276   u_long flags_;
 277
 278   /// This maintains the group id of the Task.
 279   int grp_id_;
 280
 281 #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0)
 282   /// Protect the state of a Task during concurrent operations, but
 283   /// only if we're configured as MT safe...
 284   ACE_Thread_Mutex lock_;
 285 #endif /* ACE_MT_SAFE */
 286
 287   /// Holds the thread ID of the last thread to exit svc() in this object.
 288   ACE_thread_t  last_thread_id_;
 289
 290 private:
 291
 292   // = Disallow these operations.
 293   ACE_Task_Base &operator= (const ACE_Task_Base &);
 294   ACE_Task_Base (const ACE_Task_Base &);
 295 };
 296
 297 ACE_END_VERSIONED_NAMESPACE_DECL
 298
 299 #if defined (__ACE_INLINE__)
 300 #include "ace/Task.inl"
 301 #endif /* __ACE_INLINE__ */
 302
 303 // Include the ACE_Task templates classes at this point.
 304 #include "ace/Task_T.h"
 305
 306 #include /**/ "ace/post.h"
 307 #endif /* ACE_TASK_H */