ACE/ace/Task_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Task_T.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_TASK_T_H
  12 #define ACE_TASK_T_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Message_Queue.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 #include "ace/IO_Cntl_Msg.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 // Forward decls...
  28 template <ACE_SYNCH_DECL, class TIME_POLICY> class ACE_Module;
  29
  30 /**
  31  * @class ACE_Task
  32  *
  33  * @brief Primary interface for application message processing, as well
  34  * as input and output message queueing.
  35  *
  36  * This class serves as the basis for passive and active objects
  37  * in ACE.
  38  */
  39 template <ACE_SYNCH_DECL, class TIME_POLICY = ACE_System_Time_Policy>
  40 class ACE_Task : public ACE_Task_Base
  41 {
  42 public:
  43   friend class ACE_Module<ACE_SYNCH_USE, TIME_POLICY>;
  44   friend class ACE_Module_Type;
  45
  46   // = Initialization/termination methods.
  47   /**
  48    * Initialize a Task, supplying a thread manager and a message
  49    * queue.  If the user doesn't supply a ACE_Message_Queue pointer
  50    * then we'll allocate one dynamically.  Otherwise, we'll use the
  51    * one passed as a parameter.
  52    */
  53   ACE_Task (ACE_Thread_Manager *thr_mgr = 0,
  54             ACE_Message_Queue<ACE_SYNCH_USE, TIME_POLICY> *mq = 0);
  55
  56   /// Destructor.
  57   virtual ~ACE_Task ();
  58
  59   /// Gets the message queue associated with this task.
  60   ACE_Message_Queue<ACE_SYNCH_USE, TIME_POLICY> *msg_queue ();
  61
  62   /// Sets the message queue associated with this task.
  63   void msg_queue (ACE_Message_Queue<ACE_SYNCH_USE, TIME_POLICY> *);
  64
  65   /// Get the current time of day according to the queue's TIME_POLICY.
  66   /// Allows users to initialize timeout values using correct time policy.
  67   ACE_Time_Value_T<TIME_POLICY> gettimeofday () const;
  68
  69   /// Allows applications to control how the timer queue gets the time
  70   /// of day.
  71   void set_time_policy (TIME_POLICY const & time_policy);
  72
  73 public: // Should be protected:
  74   // = Message queue manipulation methods.
  75
  76   // = Enqueue and dequeue methods.
  77
  78   // For the following five method if @a timeout == 0, the caller will
  79   // block until action is possible, else will wait until the
  80   // <{absolute}> time specified in *@a timeout elapses).  These calls
  81   // will return, however, when queue is closed, deactivated, when a
  82   // signal occurs, or if the time specified in timeout elapses, (in
  83   // which case errno = EWOULDBLOCK).
  84
  85   /// Insert message into the message queue.  Note that @a timeout uses
  86   /// <{absolute}> time rather than <{relative}> time.
  87   int putq (ACE_Message_Block *, ACE_Time_Value *timeout = 0);
  88
  89   /**
  90    * Extract the first message from the queue (blocking).  Note that
  91    * @a timeout uses <{absolute}> time rather than <{relative}> time.
  92    * Returns number of items in queue if the call succeeds or -1 otherwise.
  93    */
  94   int getq (ACE_Message_Block *&mb, ACE_Time_Value *timeout = 0);
  95
  96   /// Return a message to the queue.  Note that @a timeout uses
  97   /// <{absolute}> time rather than <{relative}> time.
  98   int ungetq (ACE_Message_Block *, ACE_Time_Value *timeout = 0);
  99
 100   /**
 101    * Turn the message around, sending it in the opposite direction in
 102    * the stream. To do this, the message is put onto the task next in
 103    * the stream after this task's sibling.
 104    *
 105    * @param mb Pointer to the block that is used in the reply.
 106    * @param tv The absolute time at which the put operation used to
 107    *           send the message block to the next module in the stream
 108    *           will time out. If 0, this call blocks until it can be
 109    *           completed.
 110    */
 111   int reply (ACE_Message_Block *mb, ACE_Time_Value *tv = 0);
 112
 113   /**
 114    * Transfer message to the adjacent ACE_Task in a ACE_Stream.  Note
 115    * that @a timeout uses <{absolute}> time rather than <{relative}>
 116    * time.
 117    */
 118   int put_next (ACE_Message_Block *msg, ACE_Time_Value *timeout = 0);
 119
 120   // = ACE_Task utility routines to identify names et al.
 121   /// Return the name of the enclosing Module if there's one associated
 122   /// with the Task, else returns 0.
 123   const ACE_TCHAR *name () const;
 124
 125   // = Pointers to next ACE_Task_Base (if ACE is part of an ACE_Stream).
 126   /// Get next Task pointer.
 127   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *next ();
 128
 129   /// Set next Task pointer.
 130   void next (ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *);
 131
 132   /// Return the Task's sibling if there's one associated with the
 133   /// Task's Module, else returns 0.
 134   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *sibling ();
 135
 136   /// Return the Task's Module if there is one, else returns 0.
 137   ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *module () const;
 138
 139   /**
 140    * Flush the task's queue, i.e., free all of the enqueued
 141    * message blocks and unblocks any threads waiting on the queue.
 142    * Note that if this conflicts with the C++ iostream <flush>
 143    * function, just rewrite the iostream function as ::<flush>.
 144    */
 145   int flush (u_long flag = ACE_Task_Flags::ACE_FLUSHALL);
 146
 147   // = Special routines corresponding to certain message types.
 148
 149   /// Manipulate watermarks.
 150   void water_marks (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds, size_t);
 151
 152   /// Queue of messages on the ACE_Task..
 153   ACE_Message_Queue<ACE_SYNCH_USE, TIME_POLICY> *msg_queue_;
 154
 155   /// true if should delete Message_Queue, false otherwise.
 156   bool delete_msg_queue_;
 157
 158   /// Back-pointer to the enclosing module.
 159   ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *mod_;
 160
 161   /// Pointer to adjacent ACE_Task.
 162   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *next_;
 163
 164   /// Dump the state of an object.
 165   void dump () const;
 166
 167   /// Declare the dynamic allocation hooks.
 168   ACE_ALLOC_HOOK_DECLARE;
 169
 170 private:
 171
 172   // = Disallow these operations.
 173   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Task<ACE_SYNCH_USE, TIME_POLICY> &))
 174   ACE_UNIMPLEMENTED_FUNC (ACE_Task (const ACE_Task<ACE_SYNCH_USE, TIME_POLICY> &))
 175 };
 176
 177 #if defined ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT
 178 template class ACE_Export ACE_Task<ACE_MT_SYNCH>;
 179 template class ACE_Export ACE_Task<ACE_NULL_SYNCH>;
 180 #endif /* ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT */
 181
 182 ACE_END_VERSIONED_NAMESPACE_DECL
 183
 184 #if defined (__ACE_INLINE__)
 185 #include "ace/Task_T.inl"
 186 #endif /* __ACE_INLINE__ */
 187
 188 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 189 #include "ace/Task_T.cpp"
 190 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 191
 192 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 193 #pragma implementation ("Task_T.cpp")
 194 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 195
 196 #include /**/ "ace/post.h"
 197 #endif /* ACE_TASK_T_H */