ACE/ace/Notification_Queue.h

   1 /**
   2  *  @file Notification_Queue.h
   3  *
   4  *  @author Carlos O'Ryan <coryan@atdesk.com>
   5  */
   6
   7 #ifndef ACE_NOTIFICATION_QUEUE_H
   8 #define ACE_NOTIFICATION_QUEUE_H
   9
  10 #include /**/ "ace/pre.h"
  11
  12 #include "ace/Event_Handler.h"
  13 #include "ace/Intrusive_List.h"
  14 #include "ace/Intrusive_List_Node.h"
  15 #include "ace/Unbounded_Queue.h"
  16
  17 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  18
  19 /**
  20  * @class ACE_Notification_Queue_Node
  21  *
  22  * @brief Helper class
  23  */
  24 class ACE_Export ACE_Notification_Queue_Node
  25   : public ACE_Intrusive_List_Node<ACE_Notification_Queue_Node>
  26 {
  27 public:
  28   /**
  29    * @brief Constructor
  30    */
  31   ACE_Notification_Queue_Node();
  32
  33   /**
  34    * @brief Modifier change the contained buffer
  35    */
  36   void set(ACE_Notification_Buffer const & rhs);
  37
  38   /**
  39    * @brief Accessor, fetch the contained buffer
  40    */
  41   ACE_Notification_Buffer const & get() const;
  42
  43   /**
  44    * @brief Checks if the event handler matches the purge condition
  45    */
  46   bool matches_for_purging(ACE_Event_Handler * eh) const;
  47
  48   /**
  49    * @brief Return true if clearing the mask would leave no
  50    * notifications to deliver.
  51    */
  52   bool mask_disables_all_notifications(ACE_Reactor_Mask mask);
  53
  54   /**
  55    * @brief Clear the notifications specified by @c mask
  56    */
  57   void clear_mask(ACE_Reactor_Mask mask);
  58
  59   ACE_ALLOC_HOOK_DECLARE;
  60
  61 private:
  62   ACE_Notification_Buffer contents_;
  63 };
  64
  65 /**
  66  * @class ACE_Notification_Queue
  67  *
  68  * @brief Implements a user-space queue to send Reactor notifications.
  69  *
  70  * The ACE_Reactor uses a pipe to send wake up the thread running the
  71  * event loop from other threads.  This pipe can be limited in size
  72  * under some operating systems.  For some applications, this limit
  73  * presents a problem.  A user-space notification queue is used to
  74  * overcome those limitations.  The queue tries to use as few
  75  * resources on the pipe as possible, while keeping all the data in
  76  * user space.
  77  *
  78  * This code was refactored from Select_Reactor_Base.
  79  */
  80 class ACE_Export ACE_Notification_Queue
  81 {
  82 public:
  83   ACE_Notification_Queue();
  84   ~ACE_Notification_Queue();
  85
  86   /**
  87    * @brief Pre-allocate resources in the queue
  88    */
  89   int open();
  90
  91   /**
  92    * @brief Release all resources in the queue
  93    */
  94   void reset();
  95
  96   /**
  97    * @brief Remove all elements in the queue matching @c eh and @c mask
  98    *
  99    * I suggest reading the documentation in ACE_Reactor to find a more
 100    * detailed description.  This is just a helper function.
 101    */
 102   int purge_pending_notifications(ACE_Event_Handler * eh,
 103                                   ACE_Reactor_Mask mask);
 104
 105   /**
 106    * @brief Add a new notification to the queue
 107    *
 108    * @return -1 on failure, 1 if a new message should be sent through
 109    * the pipe and 0 otherwise.
 110    */
 111   int push_new_notification(ACE_Notification_Buffer const & buffer);
 112
 113   /**
 114    * @brief Extract the next notification from the queue
 115    *
 116    * @return -1 on failure, 1 if a message was popped, 0 otherwise
 117    */
 118   int pop_next_notification(
 119       ACE_Notification_Buffer & current,
 120       bool & more_messages_queued,
 121       ACE_Notification_Buffer & next);
 122
 123 private:
 124   /**
 125    * @brief Allocate more memory for the queue
 126    */
 127   int allocate_more_buffers();
 128
 129   ACE_Notification_Queue (const ACE_Notification_Queue &) = delete;
 130   ACE_Notification_Queue (ACE_Notification_Queue &&) = delete;
 131   ACE_Notification_Queue &operator= (const ACE_Notification_Queue &) = delete;
 132   ACE_Notification_Queue &operator= (ACE_Notification_Queue &&) = delete;
 133
 134 private:
 135   /// Keeps track of allocated arrays of type
 136   /// ACE_Notification_Buffer.  The idea is to amortize allocation
 137   /// costs by allocating multiple ACE_Notification_Buffer objects at
 138   /// a time.
 139   ACE_Unbounded_Queue <ACE_Notification_Queue_Node*> alloc_queue_;
 140
 141   typedef ACE_Intrusive_List<ACE_Notification_Queue_Node> Buffer_List;
 142
 143   /// Keeps track of all pending notifications.
 144   Buffer_List notify_queue_;
 145
 146   /// Keeps track of all free buffers.
 147   Buffer_List free_queue_;
 148
 149   /// Synchronization for handling of queues.
 150   ACE_SYNCH_MUTEX notify_queue_lock_;
 151 };
 152
 153 ACE_END_VERSIONED_NAMESPACE_DECL
 154
 155 #if defined (__ACE_INLINE__)
 156 #include "ace/Notification_Queue.inl"
 157 #endif /* __ACE_INLINE__ */
 158
 159 #include /**/ "ace/post.h"
 160
 161 #endif /* ACE_NOTIFICATION_QUEUE_H */