ACE/ace/Activation_Queue.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Activation_Queue.h
   6  *
   7  *  @author Andres Kruse <Andres.Kruse@cern.ch>
   8  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_ACTIVATION_QUEUE_H
  13 #define ACE_ACTIVATION_QUEUE_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include /**/ "ace/ACE_export.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/Message_Queue.h"
  24 #include "ace/Copy_Disabled.h"
  25 #include "ace/Condition_Thread_Mutex.h"
  26
  27 /// Define to be compatible with the terminology in the POSA2 book!
  28 #define ACE_Activation_List ACE_Activation_Queue
  29
  30 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  31
  32 class ACE_Method_Request;
  33
  34 /**
  35  * @class ACE_Activation_Queue
  36  *
  37  * @brief
  38  * Reifies a method into a request.  Subclasses typically
  39  * represent necessary state and behavior.
  40  *
  41  * Maintains a priority-ordered queue of ACE_Method_Request objects.
  42  * A scheduler class (often derived from ACE_Task) subsequently removes
  43  * each method request and invokes its @c call() method.
  44  *
  45  * This class is discussed in depth in the Active Object chapter
  46  * of POSA2. In that book, it is referred to as an Activation List.
  47  *
  48  * @sa ACE_Method_Request
  49  */
  50 class ACE_Export ACE_Activation_Queue
  51 {
  52 public:
  53   /// Constructor.
  54   /**
  55    * Initializes a new activation queue.
  56    *
  57    * @param new_queue The activation queue uses an ACE_Message_Queue to
  58    *                  queue and order the method requests. If this argument
  59    *                  is 0, a new ACE_Message_Queue is created for this
  60    *                  object's use and will be deleted when this object is
  61    *                  destroyed. If a non-zero pointer is supplied, the
  62    *                  passed object will be used and will not be deleted when
  63    *                  this object is destroyed. If an ACE_Task is being created
  64    *                  to act as the scheduler, for instance, its
  65    *                  ACE_Message_Queue pointer can be passed to this object.
  66    * @param alloc     Optional, the allocator to use when allocating
  67    *                  ACE_Message_Block instances that wrap the method requests
  68    *                  queued to this activation queue. Defaults to
  69    *                  ACE_Allocator::instance().
  70    * @param db_alloc  Optional, the allocator to use when allocating
  71    *                  data blocks for the ACE_Message_Block instances that
  72    *                  wrap the method requests queued to this activation queue.
  73    *                  Defaults to ACE_Allocator::instance().
  74    */
  75   ACE_Activation_Queue (ACE_Message_Queue<ACE_SYNCH> *new_queue = 0,
  76                         ACE_Allocator *alloc = nullptr,
  77                         ACE_Allocator *db_alloc = 0);
  78
  79   /// Destructor.
  80   virtual ~ACE_Activation_Queue ();
  81
  82   // = Activate Queue operations.
  83
  84   /// Dequeue the next available ACE_Method_Request.
  85   /**
  86    * @param tv  If 0, the method will block until a method request is
  87    *            available, else will wait until the absolute time specified
  88    *            in the referenced ACE_Time_Value.  This method will return,
  89    *            earlier, however, if queue is closed, deactivated, or when
  90    *            a signal occurs.
  91    *
  92    * @retval    Pointer to the dequeued ACE_Method_Request object.
  93    * @retval    0 an error occurs; errno contains further information. If
  94    *            the specified timeout elapses, errno will be @c EWOULDBLOCK.
  95    */
  96   ACE_Method_Request *dequeue (ACE_Time_Value *tv = 0);
  97
  98   /// Enqueue the ACE_Method_Request in priority order.
  99   /**
 100    * The priority of the method request is obtained via the @c priority()
 101    * method of the queued method request. Priority ordering is determined
 102    * by the ACE_Message_Queue class; 0 is the lowest priority.
 103    *
 104    * @param new_method_request  Pointer to the ACE_Method_Request object to
 105    *            queue. This object's @c priority() method is called to obtain
 106    *            the priority.
 107    * @param tv  If 0, the method will block until the method request can
 108    *            be queued, else will wait until the absolute time specified
 109    *            in the referenced ACE_Time_Value.  This method will return,
 110    *            earlier, however, if queue is closed, deactivated, or when
 111    *            a signal occurs.
 112    *
 113    * @retval    >0 The number of method requests on the queue after adding
 114    *            the specified request.
 115    * @retval    -1 if an error occurs; errno contains further information. If
 116    *            the specified timeout elapses, errno will be @c EWOULDBLOCK.
 117    */
 118   int enqueue (ACE_Method_Request *new_method_request, ACE_Time_Value *tv = 0);
 119
 120   /// Get the current number of method objects in the queue.
 121   size_t method_count () const;
 122
 123   /// Returns 1 if the queue is empty, 0 otherwise.
 124   int is_empty () const;
 125
 126   /// Returns 1 if the queue is full, 0 otherwise.
 127   int is_full () const;
 128
 129   /// Dump the state of an request.
 130   void dump () const;
 131
 132   /// Get a pointer to the underlying queue.
 133   ACE_Message_Queue<ACE_SYNCH> *queue () const;
 134
 135   /// Set the pointer to the underlying queue.
 136   void queue (ACE_Message_Queue<ACE_SYNCH> *q);
 137
 138   /// Declare the dynamic allocation hooks.
 139   ACE_ALLOC_HOOK_DECLARE;
 140
 141 protected:
 142   /// Stores the Method_Requests.
 143   ACE_Message_Queue<ACE_SYNCH> *queue_;
 144
 145   /// Keeps track of whether we need to delete the queue.
 146   bool delete_queue_;
 147
 148 private:
 149   /// Allocation strategy of the queue.
 150   ACE_Allocator *allocator_;
 151
 152   /// Allocation strategy of the message blocks.
 153   ACE_Allocator *data_block_allocator_;
 154
 155   void operator= (const ACE_Activation_Queue &) = delete;
 156   ACE_Activation_Queue (const ACE_Activation_Queue &) = delete;
 157   void operator= (ACE_Activation_Queue &&) = delete;
 158   ACE_Activation_Queue (ACE_Activation_Queue &&) = delete;
 159 };
 160
 161 ACE_END_VERSIONED_NAMESPACE_DECL
 162
 163 #if defined (__ACE_INLINE__)
 164 #include "ace/Activation_Queue.inl"
 165 #endif /* __ACE_INLINE__ */
 166
 167 #include /**/ "ace/post.h"
 168 #endif /* ACE_ACTIVATION_QUEUE_H */