ACE/ace/Message_Queue.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Message_Queue.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_MESSAGE_QUEUE_H
  12 #define ACE_MESSAGE_QUEUE_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Message_Block.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/IO_Cntl_Msg.h"
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 // Forward decls.
  26 class ACE_Notification_Strategy;
  27 template <ACE_SYNCH_DECL, class TIME_POLICY> class ACE_Message_Queue_Iterator;
  28 template <ACE_SYNCH_DECL, class TIME_POLICY> class ACE_Message_Queue_Reverse_Iterator;
  29
  30 /**
  31  * @class ACE_Message_Queue_Base
  32  *
  33  * @brief Base class for ACE_Message_Queue, which is the central
  34  * queuing facility for messages in the ACE framework.
  35  *
  36  * For all the ACE_Time_Value pointer parameters the caller will
  37  * block until action is possible if @a timeout == 0.  Otherwise, it
  38  * will wait until the absolute time specified in *@a timeout
  39  * elapses.
  40  *
  41  * A queue is always in one of three states:
  42  * . ACTIVATED
  43  * . DEACTIVATED
  44  * . PULSED
  45  */
  46 class ACE_Export ACE_Message_Queue_Base
  47 {
  48 public:
  49   enum
  50   {
  51     // Default high and low watermarks.
  52
  53     /// Default high watermark (16 K).
  54     DEFAULT_HWM = 16 * 1024,
  55     /// Default low watermark (same as high water mark).
  56     DEFAULT_LWM = 16 * 1024,
  57
  58     // Queue states.  Before PULSED state was added, the activate()
  59     // and deactivate() methods returned WAS_INACTIVE or WAS_ACTIVE
  60     // to indicate the previous condition.  Now those methods
  61     // return the state the queue was previously in.  WAS_ACTIVE
  62     // and WAS_INACTIVE are defined to match previous semantics for
  63     // applications that don't use the PULSED state.
  64
  65     /// Message queue is active and processing normally
  66     ACTIVATED = 1,
  67
  68     /// Queue is deactivated; no enqueue or dequeue operations allowed.
  69     DEACTIVATED = 2,
  70
  71     /// Message queue was pulsed; enqueue and dequeue may proceed normally.
  72     PULSED = 3
  73
  74   };
  75
  76   ACE_Message_Queue_Base (void);
  77
  78   /// Close down the message queue and release all resources.
  79   virtual int close (void) = 0;
  80
  81   /// Close down the message queue and release all resources.
  82   virtual ~ACE_Message_Queue_Base (void);
  83
  84   // = Enqueue and dequeue methods.
  85
  86   /**
  87    * Retrieve the first ACE_Message_Block without removing it.  Note
  88    * that @a timeout uses <{absolute}> time rather than <{relative}>
  89    * time.  If the @a timeout elapses without receiving a message -1 is
  90    * returned and @c errno is set to @c EWOULDBLOCK.  If the queue is
  91    * deactivated -1 is returned and @c errno is set to @c ESHUTDOWN.
  92    * Otherwise, returns -1 on failure, else the number of items still
  93    * on the queue.
  94    */
  95   virtual int peek_dequeue_head (ACE_Message_Block *&first_item,
  96                                  ACE_Time_Value *timeout = 0) = 0;
  97
  98   /**
  99    * Enqueue a <ACE_Message_Block *> into the tail of the queue.
 100    * Returns number of items in queue if the call succeeds or -1
 101    * otherwise.  These calls return -1 when queue is closed,
 102    * deactivated (in which case @c errno == @c ESHUTDOWN), when a signal
 103    * occurs (in which case @c errno == @c EINTR, or if the time
 104    * specified in timeout elapses (in which case @c errno ==
 105    * @c EWOULDBLOCK).
 106    */
 107   virtual int enqueue_tail (ACE_Message_Block *new_item,
 108                             ACE_Time_Value *timeout = 0) = 0;
 109   virtual int enqueue (ACE_Message_Block *new_item,
 110                        ACE_Time_Value *timeout = 0) = 0;
 111
 112   /**
 113    * Dequeue and return the <ACE_Message_Block *> at the head of the
 114    * queue.  Returns number of items in queue if the call succeeds or
 115    * -1 otherwise.  These calls return -1 when queue is closed,
 116    * deactivated (in which case @c errno == @c ESHUTDOWN), when a signal
 117    * occurs (in which case @c errno == @c EINTR, or if the time
 118    * specified in timeout elapses (in which case @c errno ==
 119    * @c EWOULDBLOCK).
 120    */
 121   virtual int dequeue_head (ACE_Message_Block *&first_item,
 122                             ACE_Time_Value *timeout = 0) = 0;
 123   virtual int dequeue (ACE_Message_Block *&first_item,
 124                        ACE_Time_Value *timeout = 0) = 0;
 125
 126   // = Check if queue is full/empty.
 127   /// True if queue is full, else false.
 128   virtual bool is_full (void) = 0;
 129
 130   /// True if queue is empty, else false.
 131   virtual bool is_empty (void) = 0;
 132
 133   // = Queue statistic methods.
 134
 135   /// Number of total bytes on the queue, i.e., sum of the message
 136   /// block sizes.
 137   virtual size_t message_bytes (void) = 0;
 138
 139   /// Number of total length on the queue, i.e., sum of the message
 140   /// block lengths.
 141   virtual size_t message_length (void) = 0;
 142
 143   /// Number of total messages on the queue.
 144   virtual size_t message_count (void) = 0;
 145
 146   /// New value of the number of total bytes on the queue, i.e.,
 147   /// sum of the message block sizes.
 148   virtual void message_bytes (size_t new_size) = 0;
 149
 150   /// New value of the number of total length on the queue, i.e.,
 151   /// sum of the message block lengths.
 152   virtual void message_length (size_t new_length) = 0;
 153
 154   // = Activation control methods.
 155
 156   /**
 157    * Deactivate the queue and wake up all threads waiting on the queue
 158    * so they can continue.  No messages are removed from the queue,
 159    * however.  Any other operations called until the queue is
 160    * activated again will immediately return -1 with @c errno
 161    * ESHUTDOWN.
 162    *
 163    * @retval  The queue's state before this call.
 164    */
 165   virtual int deactivate (void) = 0;
 166
 167   /**
 168    * Reactivate the queue so that threads can enqueue and dequeue
 169    * messages again.
 170    *
 171    * @retval  The queue's state before this call.
 172    */
 173   virtual int activate (void) = 0;
 174
 175   /**
 176    * Pulse the queue to wake up any waiting threads.  Changes the
 177    * queue state to PULSED; future enqueue/dequeue operations proceed
 178    * as in ACTIVATED state.
 179    *
 180    * @retval  The queue's state before this call.
 181    */
 182   virtual int pulse (void) = 0;
 183
 184   /// Returns the current state of the queue.
 185   virtual int state (void);
 186
 187   /// Returns 1 if the state of the queue is DEACTIVATED,
 188   /// and 0 if the queue's state is ACTIVATED or PULSED.
 189   virtual int deactivated (void) = 0;
 190
 191   /// Get the notification strategy for the Message_Queue
 192   virtual ACE_Notification_Strategy *notification_strategy (void) = 0;
 193
 194   /// Set the notification strategy for the Message_Queue
 195   virtual void notification_strategy (ACE_Notification_Strategy *s) = 0;
 196
 197   // = Notification hook.
 198
 199   /// Dump the state of an object.
 200   virtual void dump (void) const = 0;
 201
 202 private:
 203   // = Disallow copying and assignment.
 204   ACE_Message_Queue_Base (const ACE_Message_Queue_Base &);
 205   void operator= (const ACE_Message_Queue_Base &);
 206
 207 protected:
 208   /// Indicates the state of the queue, which can be
 209   /// <ACTIVATED>, <DEACTIVATED>, or <PULSED>.
 210   int state_;
 211 };
 212
 213 ACE_END_VERSIONED_NAMESPACE_DECL
 214
 215 // Include the templates here.
 216 #include "ace/Message_Queue_T.h"
 217
 218 #if defined (__ACE_INLINE__)
 219 #include "ace/Message_Queue.inl"
 220 #endif /* __ACE_INLINE__ */
 221
 222 #include /**/ "ace/post.h"
 223 #endif /* ACE_MESSAGE_QUEUE_H */