00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Activation_Queue.h 00006 * 00007 * $Id: Activation_Queue.h 91066 2010-07-12 11:05:04Z johnnyw $ 00008 * 00009 * @author Andres Kruse <Andres.Kruse@cern.ch> 00010 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> 00011 */ 00012 //============================================================================= 00013 00014 #ifndef ACE_ACTIVATION_QUEUE_H 00015 #define ACE_ACTIVATION_QUEUE_H 00016 00017 #include /**/ "ace/pre.h" 00018 00019 #include /**/ "ace/ACE_export.h" 00020 00021 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00022 # pragma once 00023 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00024 00025 #include "ace/Message_Queue.h" 00026 #include "ace/Copy_Disabled.h" 00027 #include "ace/Condition_Thread_Mutex.h" 00028 00029 /// Define to be compatible with the terminology in the POSA2 book! 00030 #define ACE_Activation_List ACE_Activation_Queue 00031 00032 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00033 00034 class ACE_Method_Request; 00035 00036 /** 00037 * @class ACE_Activation_Queue 00038 * 00039 * @brief 00040 * Reifies a method into a request. Subclasses typically 00041 * represent necessary state and behavior. 00042 * 00043 * Maintains a priority-ordered queue of ACE_Method_Request objects. 00044 * A scheduler class (often derived from ACE_Task) subsequently removes 00045 * each method request and invokes its @c call() method. 00046 * 00047 * This class is discussed in depth in the Active Object chapter 00048 * of POSA2. In that book, it is referred to as an Activation List. 00049 * 00050 * @sa ACE_Method_Request 00051 */ 00052 class ACE_Export ACE_Activation_Queue : private ACE_Copy_Disabled 00053 { 00054 public: 00055 /// Constructor. 00056 /** 00057 * Initializes a new activation queue. 00058 * 00059 * @param new_queue The activation queue uses an ACE_Message_Queue to 00060 * queue and order the method requests. If this argument 00061 * is 0, a new ACE_Message_Queue is created for this 00062 * object's use and will be deleted when this object is 00063 * destroyed. If a non-zero pointer is supplied, the 00064 * passed object will be used and will not be deleted when 00065 * this object is destroyed. If an ACE_Task is being created 00066 * to act as the scheduler, for instance, its 00067 * ACE_Message_Queue pointer can be passed to this object. 00068 * @param alloc Optional, the allocator to use when allocating 00069 * ACE_Message_Block instances that wrap the method requests 00070 * queued to this activation queue. Defaults to 00071 * ACE_Allocator::instance(). 00072 * @param db_alloc Optional, the allocator to use when allocating 00073 * data blocks for the ACE_Message_Block instances that 00074 * wrap the method requests queued to this activation queue. 00075 * Defaults to ACE_Allocator::instance(). 00076 */ 00077 ACE_Activation_Queue (ACE_Message_Queue<ACE_SYNCH> *new_queue = 0, 00078 ACE_Allocator *alloc = 0, 00079 ACE_Allocator *db_alloc = 0); 00080 00081 /// Destructor. 00082 virtual ~ACE_Activation_Queue (void); 00083 00084 // = Activate Queue operations. 00085 00086 /// Dequeue the next available ACE_Method_Request. 00087 /** 00088 * @param tv If 0, the method will block until a method request is 00089 * available, else will wait until the absolute time specified 00090 * in the referenced ACE_Time_Value. This method will return, 00091 * earlier, however, if queue is closed, deactivated, or when 00092 * a signal occurs. 00093 * 00094 * @retval Pointer to the dequeued ACE_Method_Request object. 00095 * @retval 0 an error occurs; errno contains further information. If 00096 * the specified timeout elapses, errno will be @c EWOULDBLOCK. 00097 */ 00098 ACE_Method_Request *dequeue (ACE_Time_Value *tv = 0); 00099 00100 /// Enqueue the ACE_Method_Request in priority order. 00101 /** 00102 * The priority of the method request is obtained via the @c priority() 00103 * method of the queued method request. Priority ordering is determined 00104 * by the ACE_Message_Queue class; 0 is the lowest priority. 00105 * 00106 * @param new_method_request Pointer to the ACE_Method_Request object to 00107 * queue. This object's @c priority() method is called to obtain 00108 * the priority. 00109 * @param tv If 0, the method will block until the method request can 00110 * be queued, else will wait until the absolute time specified 00111 * in the referenced ACE_Time_Value. This method will return, 00112 * earlier, however, if queue is closed, deactivated, or when 00113 * a signal occurs. 00114 * 00115 * @retval >0 The number of method requests on the queue after adding 00116 * the specified request. 00117 * @retval -1 if an error occurs; errno contains further information. If 00118 * the specified timeout elapses, errno will be @c EWOULDBLOCK. 00119 */ 00120 int enqueue (ACE_Method_Request *new_method_request, ACE_Time_Value *tv = 0); 00121 00122 /// Get the current number of method objects in the queue. 00123 size_t method_count (void) const; 00124 00125 /// Returns 1 if the queue is empty, 0 otherwise. 00126 int is_empty (void) const; 00127 00128 /// Returns 1 if the queue is full, 0 otherwise. 00129 int is_full (void) const; 00130 00131 /// Dump the state of an request. 00132 void dump (void) const; 00133 00134 /// Get a pointer to the underlying queue. 00135 ACE_Message_Queue<ACE_SYNCH> *queue (void) const; 00136 00137 /// Set the pointer to the underlying queue. 00138 void queue (ACE_Message_Queue<ACE_SYNCH> *q); 00139 00140 /// Declare the dynamic allocation hooks. 00141 ACE_ALLOC_HOOK_DECLARE; 00142 00143 protected: 00144 00145 /// Stores the Method_Requests. 00146 ACE_Message_Queue<ACE_SYNCH> *queue_; 00147 00148 /// Keeps track of whether we need to delete the queue. 00149 bool delete_queue_; 00150 00151 private: 00152 00153 /// Allocation strategy of the queue. 00154 ACE_Allocator *allocator_; 00155 00156 /// Allocation strategy of the message blocks. 00157 ACE_Allocator *data_block_allocator_; 00158 00159 }; 00160 00161 ACE_END_VERSIONED_NAMESPACE_DECL 00162 00163 #if defined (__ACE_INLINE__) 00164 #include "ace/Activation_Queue.inl" 00165 #endif /* __ACE_INLINE__ */ 00166 00167 #include /**/ "ace/post.h" 00168 #endif /* ACE_ACTIVATION_QUEUE_H */