00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Message_Queue.h 00006 * 00007 * $Id: Message_Queue.h 88560 2010-01-15 05:02:05Z schmidt $ 00008 * 00009 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_MESSAGE_QUEUE_H 00014 #define ACE_MESSAGE_QUEUE_H 00015 #include /**/ "ace/pre.h" 00016 00017 #include "ace/Message_Block.h" 00018 00019 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00020 # pragma once 00021 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00022 00023 #include "ace/IO_Cntl_Msg.h" 00024 00025 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00026 00027 // Forward decls. 00028 class ACE_Notification_Strategy; 00029 template <ACE_SYNCH_DECL> class ACE_Message_Queue_Iterator; 00030 template <ACE_SYNCH_DECL> class ACE_Message_Queue_Reverse_Iterator; 00031 00032 /** 00033 * @class ACE_Message_Queue_Base 00034 * 00035 * @brief Base class for ACE_Message_Queue, which is the central 00036 * queueing facility for messages in the ACE framework. 00037 * 00038 * For all the ACE_Time_Value pointer parameters the caller will 00039 * block until action is possible if @a timeout == 0. Otherwise, it 00040 * will wait until the absolute time specified in *@a timeout 00041 * elapses. 00042 * 00043 * A queue is always in one of three states: 00044 * . ACTIVATED 00045 * . DEACTIVATED 00046 * . PULSED 00047 */ 00048 class ACE_Export ACE_Message_Queue_Base 00049 { 00050 public: 00051 enum 00052 { 00053 // Default high and low watermarks. 00054 00055 /// Default high watermark (16 K). 00056 DEFAULT_HWM = 16 * 1024, 00057 /// Default low watermark (same as high water mark). 00058 DEFAULT_LWM = 16 * 1024, 00059 00060 // Queue states. Before PULSED state was added, the activate() 00061 // and deactivate() methods returned WAS_INACTIVE or WAS_ACTIVE 00062 // to indicate the previous condition. Now those methods 00063 // return the state the queue was previously in. WAS_ACTIVE 00064 // and WAS_INACTIVE are defined to match previous semantics for 00065 // applications that don't use the PULSED state. 00066 00067 /// @deprecated Use ACTIVATED instead. 00068 WAS_ACTIVE = 1, 00069 /// Message queue is active and processing normally 00070 ACTIVATED = 1, 00071 00072 /// @deprecated Use DEACTIVATED instead. 00073 WAS_INACTIVE = 2, 00074 /// Queue is deactivated; no enqueue or dequeue operations allowed. 00075 DEACTIVATED = 2, 00076 00077 /// Message queue was pulsed; enqueue and dequeue may proceed normally. 00078 PULSED = 3 00079 00080 }; 00081 00082 ACE_Message_Queue_Base (void); 00083 00084 /// Close down the message queue and release all resources. 00085 virtual int close (void) = 0; 00086 00087 /// Close down the message queue and release all resources. 00088 virtual ~ACE_Message_Queue_Base (void); 00089 00090 // = Enqueue and dequeue methods. 00091 00092 /** 00093 * Retrieve the first ACE_Message_Block without removing it. Note 00094 * that @a timeout uses <{absolute}> time rather than <{relative}> 00095 * time. If the @a timeout elapses without receiving a message -1 is 00096 * returned and @c errno is set to @c EWOULDBLOCK. If the queue is 00097 * deactivated -1 is returned and @c errno is set to <ESHUTDOWN>. 00098 * Otherwise, returns -1 on failure, else the number of items still 00099 * on the queue. 00100 */ 00101 virtual int peek_dequeue_head (ACE_Message_Block *&first_item, 00102 ACE_Time_Value *timeout = 0) = 0; 00103 00104 /** 00105 * Enqueue a <ACE_Message_Block *> into the tail of the queue. 00106 * Returns number of items in queue if the call succeeds or -1 00107 * otherwise. These calls return -1 when queue is closed, 00108 * deactivated (in which case @c errno == <ESHUTDOWN>), when a signal 00109 * occurs (in which case @c errno == <EINTR>, or if the time 00110 * specified in timeout elapses (in which case @c errno == 00111 * @c EWOULDBLOCK). 00112 */ 00113 virtual int enqueue_tail (ACE_Message_Block *new_item, 00114 ACE_Time_Value *timeout = 0) = 0; 00115 virtual int enqueue (ACE_Message_Block *new_item, 00116 ACE_Time_Value *timeout = 0) = 0; 00117 00118 /** 00119 * Dequeue and return the <ACE_Message_Block *> at the head of the 00120 * queue. Returns number of items in queue if the call succeeds or 00121 * -1 otherwise. These calls return -1 when queue is closed, 00122 * deactivated (in which case @c errno == <ESHUTDOWN>), when a signal 00123 * occurs (in which case @c errno == <EINTR>, or if the time 00124 * specified in timeout elapses (in which case @c errno == 00125 * @c EWOULDBLOCK). 00126 */ 00127 virtual int dequeue_head (ACE_Message_Block *&first_item, 00128 ACE_Time_Value *timeout = 0) = 0; 00129 virtual int dequeue (ACE_Message_Block *&first_item, 00130 ACE_Time_Value *timeout = 0) = 0; 00131 00132 // = Check if queue is full/empty. 00133 /// True if queue is full, else false. 00134 virtual bool is_full (void) = 0; 00135 00136 /// True if queue is empty, else false. 00137 virtual bool is_empty (void) = 0; 00138 00139 // = Queue statistic methods. 00140 00141 /// Number of total bytes on the queue, i.e., sum of the message 00142 /// block sizes. 00143 virtual size_t message_bytes (void) = 0; 00144 00145 /// Number of total length on the queue, i.e., sum of the message 00146 /// block lengths. 00147 virtual size_t message_length (void) = 0; 00148 00149 /// Number of total messages on the queue. 00150 virtual size_t message_count (void) = 0; 00151 00152 /// New value of the number of total bytes on the queue, i.e., 00153 /// sum of the message block sizes. 00154 virtual void message_bytes (size_t new_size) = 0; 00155 00156 /// New value of the number of total length on the queue, i.e., 00157 /// sum of the message block lengths. 00158 virtual void message_length (size_t new_length) = 0; 00159 00160 // = Activation control methods. 00161 00162 /** 00163 * Deactivate the queue and wake up all threads waiting on the queue 00164 * so they can continue. No messages are removed from the queue, 00165 * however. Any other operations called until the queue is 00166 * activated again will immediately return -1 with @c errno 00167 * ESHUTDOWN. 00168 * 00169 * @retval The queue's state before this call. 00170 */ 00171 virtual int deactivate (void) = 0; 00172 00173 /** 00174 * Reactivate the queue so that threads can enqueue and dequeue 00175 * messages again. 00176 * 00177 * @retval The queue's state before this call. 00178 */ 00179 virtual int activate (void) = 0; 00180 00181 /** 00182 * Pulse the queue to wake up any waiting threads. Changes the 00183 * queue state to PULSED; future enqueue/dequeue operations proceed 00184 * as in ACTIVATED state. 00185 * 00186 * @retval The queue's state before this call. 00187 */ 00188 virtual int pulse (void) = 0; 00189 00190 /// Returns the current state of the queue. 00191 virtual int state (void); 00192 00193 /// Returns 1 if the state of the queue is DEACTIVATED, 00194 /// and 0 if the queue's state is ACTIVATED or PULSED. 00195 virtual int deactivated (void) = 0; 00196 00197 /// Get the notification strategy for the <Message_Queue> 00198 virtual ACE_Notification_Strategy *notification_strategy (void) = 0; 00199 00200 /// Set the notification strategy for the <Message_Queue> 00201 virtual void notification_strategy (ACE_Notification_Strategy *s) = 0; 00202 00203 // = Notification hook. 00204 00205 /// Dump the state of an object. 00206 virtual void dump (void) const = 0; 00207 00208 /// Declare the dynamic allocation hooks. 00209 ACE_ALLOC_HOOK_DECLARE; 00210 00211 private: 00212 // = Disallow copying and assignment. 00213 ACE_Message_Queue_Base (const ACE_Message_Queue_Base &); 00214 void operator= (const ACE_Message_Queue_Base &); 00215 00216 protected: 00217 /// Indicates the state of the queue, which can be 00218 /// <ACTIVATED>, <DEACTIVATED>, or <PULSED>. 00219 int state_; 00220 00221 }; 00222 00223 ACE_END_VERSIONED_NAMESPACE_DECL 00224 00225 // Include the templates here. 00226 #include "ace/Message_Queue_T.h" 00227 00228 #if defined (__ACE_INLINE__) 00229 #include "ace/Message_Queue.inl" 00230 #endif /* __ACE_INLINE__ */ 00231 00232 #include /**/ "ace/post.h" 00233 #endif /* ACE_MESSAGE_QUEUE_H */