dep/ACE_wrappers/ace/Message_Queue.h

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