ACE/ace/Abstract_Timer_Queue.h

   1 #ifndef ACE_ABSTRACT_TIMER_QUEUE_H
   2 #define ACE_ABSTRACT_TIMER_QUEUE_H
   3
   4 #include /**/ "ace/pre.h"
   5 /**
   6  * @file Abstract_Timer_Queue.h
   7  *
   8  * @author Carlos O'Ryan <coryan@atdesk.com>
   9  *
  10  * Based on classes and files developed by Doug Schmidt, Darrell
  11  * Brunsch, Irfan Pyarali and a cast of thousands.
  12  */
  13
  14 #include "ace/Versioned_Namespace.h"
  15
  16 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  17
  18 // Forward declares
  19 class ACE_Time_Value;
  20 class ACE_Command_Base;
  21 template<typename TYPE> class ACE_Timer_Queue_Iterator_T;
  22 template<typename TYPE> class ACE_Timer_Node_T;
  23
  24 /**
  25  * @class ACE_Abstract_Timer_Queue
  26  *
  27  * @brief Base class for all timer queues of a single type.
  28  *
  29  * This is a base class for all the timer queues, regardless of
  30  * locking strategy, upcall mechanism, internal implementation, etc.
  31  * The class was motivated by bug 3706:
  32  *    http://bugzilla.dre.vanderbilt.edu/show_bug.cgi?id=3706
  33  * In short, the Reactor (and potentially other classes) want to refer
  34  * to timer queues regardless of the implementation internals.
  35  */
  36 template<typename TYPE>
  37 class ACE_Abstract_Timer_Queue
  38 {
  39 public:
  40   /// Destructor
  41   virtual ~ACE_Abstract_Timer_Queue () = 0;
  42
  43   /// True if queue is empty, else false.
  44   virtual bool is_empty () const = 0;
  45
  46   /// Returns the time of the earlier node in the Timer_Queue.  Must
  47   /// be called on a non-empty queue.
  48   virtual const ACE_Time_Value &earliest_time () const = 0;
  49
  50   /**
  51    * Schedule @a type that will expire at @a future_time, which is
  52    * specified in absolute time.  If it expires then @a act is passed
  53    * in as the value to the <functor>.  If @a interval is != to
  54    * ACE_Time_Value::zero then it is used to reschedule the @a type
  55    * automatically, using relative time to the current <gettimeofday>.
  56    * This method returns a <timer_id> that uniquely identifies the the
  57    * @a type entry in an internal list.  This <timer_id> can be used to
  58    * cancel the timer before it expires.  The cancellation ensures
  59    * that <timer_ids> are unique up to values of greater than 2
  60    * billion timers.  As long as timers don't stay around longer than
  61    * this there should be no problems with accidentally deleting the
  62    * wrong timer.  Returns -1 on failure (which is guaranteed never to
  63    * be a valid <timer_id>).
  64    */
  65   virtual long schedule (const TYPE &type,
  66                          const void *act,
  67                          const ACE_Time_Value &future_time,
  68                          const ACE_Time_Value &interval = ACE_Time_Value::zero) = 0;
  69
  70   /**
  71    * Run the <functor> for all timers whose values are <= @a current_time.
  72    * This does not account for <timer_skew>.  Returns the number of
  73    * timers canceled.
  74    */
  75   virtual int expire (const ACE_Time_Value &current_time) = 0;
  76
  77   /**
  78    * Run the <functor> for all timers whose values are <=
  79    * <ACE_OS::gettimeofday>.  Also accounts for <timer_skew>.
  80    *
  81    * Depending on the resolution of the underlying OS the system calls
  82    * like select()/poll() might return at time different than that is
  83    * specified in the timeout. Suppose the OS guarantees a resolution of t ms.
  84    * The timeline will look like
  85    *
  86    *             A                   B
  87    *             |                   |
  88    *             V                   V
  89    *  |-------------|-------------|-------------|-------------|
  90    *  t             t             t             t             t
  91    *
  92    *
  93    * If you specify a timeout value of A, then the timeout will not occur
  94    * at A but at the next interval of the timer, which is later than
  95    * that is expected. Similarly, if your timeout value is equal to B,
  96    * then the timeout will occur at interval after B. Now depending upon the
  97    * resolution of your timeouts and the accuracy of the timeouts
  98    * needed for your application, you should set the value of
  99    * <timer_skew>. In the above case, if you want the timeout A to fire
 100    * no later than A, then you should specify your <timer_skew> to be
 101    * A % t.
 102    *
 103    * The timeout value should be specified via the macro ACE_TIMER_SKEW
 104    * in your config.h file. The default value is zero.
 105    *
 106    * Things get interesting if the t before the timeout value B is zero
 107    * i.e your timeout is less than the interval. In that case, you are
 108    * almost sure of not getting the desired timeout behaviour. Maybe you
 109    * should look for a better OS :-)
 110    *
 111    *  Returns the number of timers canceled.
 112    */
 113   virtual int expire () = 0;
 114
 115   /**
 116    * A couple of classes using Timer_Queues need to dispatch a single
 117    * event at a time.  But before they dispatch the event they need to
 118    * release a lock, signal other threads, etc.
 119    *
 120    * This member function should be used in that case.  The additional
 121    * operations to be called just before dispatching the event, and
 122    * only if an event will be dispatched, are encapsulated in the
 123    * ACE_Command_Base object.
 124    */
 125   virtual int expire_single(ACE_Command_Base & pre_dispatch_command) = 0;
 126
 127   /**
 128    * Resets the interval of the timer represented by @a timer_id to
 129    * @a interval, which is specified in relative time to the current
 130    * <gettimeofday>.  If @a interval is equal to
 131    * ACE_Time_Value::zero, the timer will become a non-rescheduling
 132    * timer.  Returns 0 if successful, -1 if not.
 133    */
 134   virtual int reset_interval (long timer_id,
 135                               const ACE_Time_Value &interval) = 0;
 136
 137   /**
 138    * Cancel all timer associated with @a type.  If
 139    * @a dont_call_handle_close is 0 then the <functor> will be invoked,
 140    * which typically invokes the <handle_close> hook.  Returns number
 141    * of timers cancelled.
 142    */
 143   virtual int cancel (const TYPE &type,
 144                       int dont_call_handle_close = 1) = 0;
 145
 146   /**
 147    * Cancel the single timer that matches the @a timer_id value (which
 148    * was returned from the <schedule> method).  If act is non-NULL
 149    * then it will be set to point to the ``magic cookie'' argument
 150    * passed in when the timer was registered.  This makes it possible
 151    * to free up the memory and avoid memory leaks.  If
 152    * @a dont_call_handle_close is 0 then the <functor> will be invoked,
 153    * which typically calls the <handle_close> hook.  Returns 1 if
 154    * cancellation succeeded and 0 if the @a timer_id wasn't found.
 155    */
 156   virtual int cancel (long timer_id,
 157                       const void **act = 0,
 158                       int dont_call_handle_close = 1) = 0;
 159
 160   /**
 161    * Close timer queue. Cancels all timers.
 162    */
 163   virtual int close () = 0;
 164
 165   /**
 166    * Returns the current time of day.  This method allows different
 167    * implementations of the timer queue to use special high resolution
 168    * timers.
 169    */
 170   virtual ACE_Time_Value gettimeofday () = 0;
 171
 172   /**
 173    * Allows applications to control how the timer queue gets the time
 174    * of day.
 175    * @deprecated Use TIME_POLICY support instead. See Timer_Queue_T.h
 176    */
 177   virtual void gettimeofday (ACE_Time_Value (*gettimeofday)()) = 0;
 178
 179   /// Determine the next event to timeout.  Returns @a max if there are
 180   /// no pending timers or if all pending timers are longer than max.
 181   /// This method acquires a lock internally since it modifies internal state.
 182   virtual ACE_Time_Value *calculate_timeout (ACE_Time_Value *max) = 0;
 183
 184   /**
 185    * Determine the next event to timeout.  Returns @a max if there are
 186    * no pending timers or if all pending timers are longer than max.
 187    * @a the_timeout should be a pointer to storage for the timeout value,
 188    * and this value is also returned.  This method does not acquire a
 189    * lock internally since it doesn't modify internal state.  If you
 190    * need to call this method when the queue is being modified
 191    * concurrently, however, you should make sure to acquire the <mutex()>
 192    * externally before making the call.
 193    */
 194   virtual ACE_Time_Value *calculate_timeout (ACE_Time_Value *max,
 195                                              ACE_Time_Value *the_timeout) = 0;
 196
 197   /**
 198    * Return the current time, using the right time policy and any
 199    * timer skew defined in derived classes.
 200    */
 201   virtual ACE_Time_Value current_time() = 0;
 202
 203   /// Type of Iterator.
 204   typedef ACE_Timer_Queue_Iterator_T<TYPE> ITERATOR;
 205
 206   /// Returns a pointer to this ACE_Timer_Queue's iterator.
 207   virtual ITERATOR & iter () = 0;
 208
 209   /// Removes the earliest node from the queue and returns it
 210   virtual ACE_Timer_Node_T<TYPE> *remove_first () = 0;
 211
 212   /// Reads the earliest node from the queue and returns it.
 213   virtual ACE_Timer_Node_T<TYPE> *get_first () = 0;
 214
 215   /// Dump the state of a object.
 216   virtual void dump () const = 0;
 217 };
 218
 219 ACE_END_VERSIONED_NAMESPACE_DECL
 220
 221 #include "ace/Abstract_Timer_Queue.cpp"
 222
 223 #include /**/ "ace/post.h"
 224 #endif /* ACE_ABSTRACT_TIMER_QUEUE_H */