ACE/ace/Task_Ex_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Task_Ex_T.h
   6  *
   7  *  @author Kobi Cohen-Arazi <kobi-co@barak-online.net>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_TASK_EX_T_H
  12 #define ACE_TASK_EX_T_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Service_Object.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/Synch_Traits.h"
  22 #include "ace/Task.h"
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 // Forward decls...
  27 template <ACE_SYNCH_DECL, class TIME_POLICY> class ACE_Module;
  28
  29 /**
  30  * @class ACE_Task_Ex
  31  *
  32  * @brief Primary interface for application message processing, as well
  33  * as input and output message queueing.
  34  *
  35  * Unlike ACE_Task, these class doesn't have the ability to be a part of
  36  * a Stream chain. I.e. You cannot (yet) chain modules based on ACE_Task_Ex.
  37  *
  38  * @todo: We can merge ACE_Task and ACE_Task_Ex to be one class.
  39  * something like that:
  40  * template <ACE_SYNCH_DECL, ACE_MESSAGE_TYPE = ACE_Message_Block>
  41  * class ACE_Task : public ACE_Task_Base
  42  * {
  43  *  // use here the code from ACE_Task_Ex using ACE_Message_Queue_Ex
  44  * };
  45  *
  46  * Now specialized version of ACE_Task with ACE_Message_Block as its
  47  * ACE_MESSAGE_TYPE...
  48  *
  49  * template <ACE_SYNCH_DECL>
  50  * class ACE_Task <ACE_SYNCH_USE, ACE_Message_Block> : public ACE_Task_Base
  51  * {
  52  *   // put here the good old ACE_Task code
  53  * };
  54  *
  55  * When User (and legacy code) write ACE_Task<ACE_MT_SYNCH>, specialized ACE_Task
  56  * code is in action.
  57  */
  58 template <ACE_SYNCH_DECL, class ACE_MESSAGE_TYPE, class TIME_POLICY = ACE_System_Time_Policy>
  59 class ACE_Task_Ex : public ACE_Task_Base,
  60                     private ACE_Copy_Disabled
  61 {
  62 public:
  63   friend class ACE_Module<ACE_SYNCH_USE, TIME_POLICY>;
  64   friend class ACE_Module_Type;
  65   typedef ACE_Message_Queue_Ex<ACE_MESSAGE_TYPE, ACE_SYNCH_USE, TIME_POLICY> MESSAGE_QUEUE_EX;
  66
  67   // = Initialization/termination methods.
  68   /**
  69    * Initialize a Task, supplying a thread manager and a message
  70    * queue.  If the user doesn't supply a ACE_Message_Queue pointer
  71    * then we'll allocate one dynamically.  Otherwise, we'll use the
  72    * one passed as a parameter.
  73    */
  74   ACE_Task_Ex (ACE_Thread_Manager *thr_mgr = 0,
  75             MESSAGE_QUEUE_EX *mq = 0);
  76
  77   /// Destructor.
  78   virtual ~ACE_Task_Ex ();
  79
  80   /// Gets the message queue associated with this task.
  81   MESSAGE_QUEUE_EX *msg_queue ();
  82
  83   /// Sets the message queue associated with this task.
  84   void msg_queue (MESSAGE_QUEUE_EX *);
  85
  86 public: // Should be protected:
  87   // = Message queue manipulation methods.
  88
  89   // = Enqueue and dequeue methods.
  90
  91   // For the following five method if @a timeout == 0, the caller will
  92   // block until action is possible, else will wait until the
  93   // <{absolute}> time specified in *@a timeout elapses).  These calls
  94   // will return, however, when queue is closed, deactivated, when a
  95   // signal occurs, or if the time specified in timeout elapses, (in
  96   // which case errno = EWOULDBLOCK).
  97
  98   /// Insert message into the message queue.  Note that @a timeout uses
  99   /// <{absolute}> time rather than <{relative}> time.
 100   int putq (ACE_MESSAGE_TYPE *, ACE_Time_Value *timeout = 0);
 101
 102   /**
 103    * Extract the first message from the queue (blocking).  Note that
 104    * @a timeout uses <{absolute}> time rather than <{relative}> time.
 105    * Returns number of items in queue if the call succeeds or -1 otherwise.
 106    */
 107   int getq (ACE_MESSAGE_TYPE *&mb, ACE_Time_Value *timeout = 0);
 108
 109   /// Return a message to the queue.  Note that @a timeout uses
 110   /// <{absolute}> time rather than <{relative}> time.
 111   int ungetq (ACE_MESSAGE_TYPE *, ACE_Time_Value *timeout = 0);
 112
 113   /**
 114    * Turn the message around and send it back down the Stream.  Note
 115    * that @a timeout uses <{absolute}> time rather than <{relative}>
 116    * time.
 117    */
 118   int reply (ACE_MESSAGE_TYPE *, ACE_Time_Value *timeout = 0);
 119
 120   /**
 121    * Transfer message to the adjacent ACE_Task_Ex in a ACE_Stream.  Note
 122    * that @a timeout uses <{absolute}> time rather than <{relative}>
 123    * time.
 124    */
 125   int put_next (ACE_MESSAGE_TYPE *msg, ACE_Time_Value *timeout = 0);
 126
 127   // = ACE_Task utility routines to identify names et al.
 128   /// Return the name of the enclosing Module if there's one associated
 129   /// with the Task, else returns 0.
 130   const ACE_TCHAR *name () const;
 131
 132   // = Pointers to next ACE_Task_Base (if ACE is part of an ACE_Stream).
 133   /// Get next Task pointer.
 134   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *next ();
 135
 136   /// Set next Task pointer.
 137   void next (ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *);
 138
 139   /// Alwasy return 0. @todo FIXME
 140   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *sibling ();
 141
 142   /// Return the Task's Module if there is one, else returns 0.
 143   ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *module () const;
 144
 145   /**
 146    * Flush the task's queue, i.e., free all of the enqueued
 147    * message blocks and releases any threads blocked on the queue.
 148    * Note that if this conflicts with the C++ iostream <flush>
 149    * function, just rewrite the iostream function as ::<flush>.
 150    */
 151   int flush (u_long flag = ACE_Task_Flags::ACE_FLUSHALL);
 152
 153   // = Special routines corresponding to certain message types.
 154
 155   /// Manipulate watermarks.
 156   void water_marks (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds, size_t);
 157
 158   /// Queue of messages on the ACE_Task..
 159   MESSAGE_QUEUE_EX *msg_queue_;
 160
 161   /// true if should delete Message_Queue, false otherwise.
 162   bool delete_msg_queue_;
 163
 164   /// Back-pointer to the enclosing module.
 165   ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *mod_;
 166
 167   /// Pointer to adjacent ACE_Task.
 168   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *next_;
 169
 170   /// Dump the state of an object.
 171   void dump () const;
 172
 173   /// Declare the dynamic allocation hooks.
 174   ACE_ALLOC_HOOK_DECLARE;
 175 };
 176
 177 ACE_END_VERSIONED_NAMESPACE_DECL
 178
 179 #if defined (__ACE_INLINE__)
 180 #include "ace/Task_Ex_T.inl"
 181 #endif /* __ACE_INLINE__ */
 182
 183 #include "ace/Task_Ex_T.cpp"
 184
 185 #include /**/ "ace/post.h"
 186 #endif /* ACE_TASK_EX_H */