ACE/ace/Timer_List_T.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Timer_List_T.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_TIMER_LIST_T_H
  12 #define ACE_TIMER_LIST_T_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Timer_Queue_T.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 // Forward declaration.
  22 template <class TYPE, class FUNCTOR, class ACE_LOCK, typename TIME_POLICY>
  23 class ACE_Timer_List_T;
  24
  25 /**
  26  * @class ACE_Timer_List_Iterator_T
  27  *
  28  * @brief Iterates over an ACE_Timer_List.
  29  *
  30  * This is a generic iterator that can be used to visit every
  31  * node of a timer queue.
  32  */
  33 template <class TYPE, class FUNCTOR, class ACE_LOCK, typename TIME_POLICY = ACE_Default_Time_Policy>
  34 class ACE_Timer_List_Iterator_T
  35 : public ACE_Timer_Queue_Iterator_T <TYPE>
  36 {
  37 public:
  38   typedef ACE_Timer_List_T<TYPE, FUNCTOR, ACE_LOCK, TIME_POLICY> List;
  39   /// Constructor.
  40   ACE_Timer_List_Iterator_T (List& lst);
  41
  42   /// Destructor.
  43   virtual ~ACE_Timer_List_Iterator_T ();
  44
  45   /// Positions the iterator at the earliest node in the Timer Queue
  46   virtual void first ();
  47
  48   /// Positions the iterator at the next node in the Timer Queue
  49   virtual void next ();
  50
  51   /// Returns true when there are no more nodes in the sequence
  52   virtual bool isdone () const;
  53
  54   /// Returns the node at the current position in the sequence
  55   virtual ACE_Timer_Node_T<TYPE> *item ();
  56
  57 protected:
  58   /// Pointer to the ACE_Timer_List that we are iterating over.
  59   List& list_;
  60
  61   /// Current position in the ACE_Timer_List
  62   ACE_Timer_Node_T<TYPE>* current_node_;
  63 };
  64
  65 /**
  66  * @class ACE_Timer_List_T
  67  *
  68  * @brief Provides a simple implementation of timers.
  69  *
  70  * This implementation uses a linked list of absolute times.
  71  * Therefore, in the average case, scheduling and canceling
  72  * timers is O(N) (where N is the total number of timers) and
  73  * expiring timers is O(K) (where K is the total number of timers
  74  * that are < the current time of day).
  75  * More clever implementations could use a delta-list, a heap,
  76  * or timing wheels, etc.  For instance, ACE_Timer_Heap
  77  * is a subclass of ACE_Timer_List that implements a
  78  * heap-based callout queue.  For most applications, the
  79  * ACE_Timer_Heap will perform substantially faster than the
  80  * ACE_Timer_List.
  81  */
  82 template <class TYPE, class FUNCTOR, class ACE_LOCK, typename TIME_POLICY = ACE_Default_Time_Policy>
  83 class ACE_Timer_List_T : public ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK, TIME_POLICY>
  84 {
  85 public:
  86   /// Type of iterator
  87   typedef ACE_Timer_List_Iterator_T<TYPE, FUNCTOR, ACE_LOCK, TIME_POLICY> Iterator;
  88
  89   /// Iterator is a friend
  90   friend class ACE_Timer_List_Iterator_T<TYPE, FUNCTOR, ACE_LOCK, TIME_POLICY>;
  91
  92   typedef ACE_Timer_Node_T<TYPE> Node;
  93   /// Type inherited from
  94   typedef ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK, TIME_POLICY> Base_Timer_Queue;
  95   typedef ACE_Free_List<Node> FreeList;
  96
  97   /**
  98    * Default constructor. @a upcall_functor is the instance of the
  99    * FUNCTOR to be used by the list. If @a upcall_functor is 0, a
 100    * default FUNCTOR will be created.  @a freelist is the freelist of
 101    * timer nodes.  If 0, then a default freelist will be created.
 102    */
 103   ACE_Timer_List_T (FUNCTOR* upcall_functor = 0, FreeList* freelist = 0,
 104                     TIME_POLICY const & time_policy = TIME_POLICY());
 105
 106   /// Destructor
 107   virtual ~ACE_Timer_List_T ();
 108
 109   /// True if queue is empty, else false.
 110   virtual bool is_empty () const;
 111
 112   /// Returns the time of the earlier node in the ACE_Timer_List.
 113   /// Must be called on a non-empty queue.
 114   virtual const ACE_Time_Value& earliest_time () const;
 115
 116   /**
 117    * Resets the interval of the timer represented by @a timer_id to
 118    * @a interval, which is specified in relative time to the current
 119    * <gettimeofday>.  If @a interval is equal to
 120    * ACE_Time_Value::zero, the timer will become a non-rescheduling
 121    * timer.  Returns 0 if successful, -1 if not.
 122    */
 123   virtual int reset_interval (long timer_id,
 124                               const ACE_Time_Value& interval);
 125
 126   /**
 127    * Cancel all timers associated with @a type.  If @a dont_call_handle_close
 128    * is 0 then the @a functor will be invoked.  Returns the number of timers
 129    * cancelled.
 130    */
 131   virtual int cancel (const TYPE& type,
 132                       int dont_call_handle_close = 1);
 133
 134   /**
 135    * Cancel the single timer that matches the @a timer_id value (which
 136    * was returned from the <schedule> method).  If act is non-NULL
 137    * then it will be set to point to the ``magic cookie'' argument
 138    * passed in when the timer was registered.  This makes it possible
 139    * to free up the memory and avoid memory leaks.  If <dont_call> is
 140    * 0 then the <functor> will be invoked.  Returns 1 if cancellation
 141    * succeeded and 0 if the @a timer_id wasn't found.
 142    */
 143   virtual int cancel (long timer_id,
 144                       const void** act = 0,
 145                       int dont_call_handle_close = 1);
 146
 147   /**
 148    * Destroy timer queue. Cancels all timers.
 149    */
 150   virtual int close ();
 151
 152   /// Returns a pointer to this ACE_Timer_Queue's iterator.
 153   virtual ACE_Timer_Queue_Iterator_T<TYPE>& iter ();
 154
 155   /// Removes the earliest node from the queue and returns it
 156   virtual ACE_Timer_Node_T<TYPE>* remove_first ();
 157
 158   /// Dump the state of an object.
 159   virtual void dump () const;
 160
 161   /// Reschedule an "interval" ACE_Timer_Node_T.  This should be private
 162   /// but for now it needs to be public for <ACE_Timer_Hash_T>
 163   virtual void reschedule (ACE_Timer_Node_T<TYPE> *);
 164
 165   /// Reads the earliest node from the queue and returns it.
 166   virtual ACE_Timer_Node_T<TYPE>* get_first ();
 167
 168 private:
 169   /**
 170    * Schedule @a type that will expire at @a future_time, which is
 171    * specified in absolute time.  If it expires then @a act is passed
 172    * in as the value to the <functor>.  If @a interval is != to
 173    * ACE_Time_Value::zero then it is used to reschedule the @a type
 174    * automatically, using relative time to the current <gettimeofday>.
 175    * This method returns a timer_id that uniquely identifies the the
 176    * @a type entry in an internal list.  This timer_id can be used to
 177    * cancel the timer before it expires.  The cancellation ensures
 178    * that <timer_ids> are unique up to values of greater than 2
 179    * billion timers.  As long as timers don't stay around longer than
 180    * this there should be no problems with accidentally deleting the
 181    * wrong timer.  Returns -1 on failure (which is guaranteed never to
 182    * be a valid <timer_id>).
 183    */
 184   virtual long schedule_i (const TYPE& type,
 185                            const void* act,
 186                            const ACE_Time_Value& future_time,
 187                            const ACE_Time_Value& interval);
 188
 189   void schedule_i(ACE_Timer_Node_T<TYPE>* n, const ACE_Time_Value& exp);
 190
 191   ACE_Timer_Node_T<TYPE>* find_node(long timer_id) const;
 192
 193   void cancel_i (ACE_Timer_Node_T<TYPE>* n);
 194
 195   void unlink (ACE_Timer_Node_T<TYPE>* n);
 196
 197   ACE_Timer_Node_T<TYPE>* get_first_i() const;
 198
 199 private:
 200   /// Pointer to linked list of <ACE_Timer_Handles>.
 201   ACE_Timer_Node_T<TYPE>* head_;
 202
 203   /// Iterator used to expire timers.
 204   Iterator* iterator_;
 205
 206   /**
 207    * Keeps track of the timer id that uniquely identifies each timer.
 208    * This id can be used to cancel a timer via the <cancel(long)>
 209    * method.
 210    */
 211   long id_counter_;
 212
 213   // = Don't allow these operations for now.
 214   ACE_Timer_List_T (const ACE_Timer_List_T<TYPE, FUNCTOR, ACE_LOCK> &) = delete;
 215   void operator= (const ACE_Timer_List_T<TYPE, FUNCTOR, ACE_LOCK> &) = delete;
 216 };
 217
 218 #include "ace/Timer_List_T.cpp"
 219
 220 #include /**/ "ace/post.h"
 221 #endif /* ACE_TIMER_LIST_T_H */