otk/timer.hh

   1 // -*- mode: C++; indent-tabs-mode: nil; -*-
   2 #ifndef   __timer_hh
   3 #define   __timer_hh
   4
   5 extern "C" {
   6 #ifdef    TIME_WITH_SYS_TIME
   7 #  include <sys/time.h>
   8 #  include <time.h>
   9 #else // !TIME_WITH_SYS_TIME
  10 #  ifdef    HAVE_SYS_TIME_H
  11 #    include <sys/time.h>
  12 #  else // !HAVE_SYS_TIME_H
  13 #    include <time.h>
  14 #  endif // HAVE_SYS_TIME_H
  15 #endif // TIME_WITH_SYS_TIME
  16 }
  17
  18 namespace otk {
  19
  20 class OBTimerQueueManager;
  21
  22 //! The data passed to the OBTimeoutHandler function.
  23 /*!
  24   Note: this is a very useful place to put an object instance, and set the
  25   event handler to a static function in the same class.
  26 */
  27 typedef void *OBTimeoutData;
  28 //! The type of function which can be set as the callback for an OBTimer firing
  29 typedef void (*OBTimeoutHandler)(OBTimeoutData);
  30
  31 //! A Timer class which will fire a function when its time elapses
  32 class OBTimer {
  33 private:
  34   //! The manager which to add ourself to and remove ourself after we are done
  35   OBTimerQueueManager *manager;
  36   //! The function to call when the time elapses
  37   OBTimeoutHandler handler;
  38   //! The data which gets passed along to the OBTimeoutHandler
  39   OBTimeoutData data;
  40   //! Determines if the timer is currently started
  41   bool timing;
  42   //! When this is true, the timer will reset itself to fire again every time
  43   bool recur;
  44
  45   //! The time at which the timer started
  46   timeval _start;
  47   //! The time at which the timer is going to fire
  48   timeval _timeout;
  49
  50   //! Disallows copying of OBTimer objects
  51   OBTimer(const OBTimer&);
  52   //! Disallows copying of OBTimer objects
  53   OBTimer& operator=(const OBTimer&);
  54
  55 public:
  56   //! Constructs a new OBTimer object
  57   /*!
  58     @param m The OBTimerQueueManager with which to associate. The manager
  59              specified will be resposible for making this timer fire.
  60     @param h The function to call when the timer fires
  61     @param d The data to pass along to the function call when the timer fires
  62   */
  63   OBTimer(OBTimerQueueManager *m, OBTimeoutHandler h, OBTimeoutData d);
  64   //! Destroys the OBTimer object
  65   virtual ~OBTimer();
  66
  67   //! Fires the timer, calling its OBTimeoutHandler
  68   void fireTimeout();
  69
  70   //! Returns if the OBTimer is started and timing
  71   inline bool isTiming() const { return timing; }
  72   //! Returns if the OBTimer is going to repeat
  73   inline bool isRecurring() const { return recur; }
  74
  75   //! Gets the amount of time the OBTimer should last before firing
  76   inline const timeval &getTimeout() const { return _timeout; }
  77   //! Gets the time at which the OBTimer started
  78   inline const timeval &getStartTime() const { return _start; }
  79
  80   //! Gets the amount of time left before the OBTimer fires
  81   timeval timeRemaining(const timeval &tm) const;
  82   //! Returns if the OBTimer is past its timeout time, and should fire
  83   bool shouldFire(const timeval &tm) const;
  84
  85   //! Gets the time at which the OBTimer will fire
  86   timeval endpoint() const;
  87
  88   //! Sets the OBTimer to repeat or not
  89   /*!
  90     @param b If true, the timer is set to repeat; otherwise, it will fire only
  91              once
  92   */
  93   inline void recurring(bool b) { recur = b; }
  94
  95   //! Sets the amount of time for the OBTimer to last before firing in
  96   //! milliseconds
  97   /*!
  98     @param t The number of milliseconds the timer should last
  99   */
 100   void setTimeout(long t);
 101   //! Sets the amount of time the OBTimer should last before firing
 102   /*!
 103     @param t The amount of time the timer should last
 104   */
 105   void setTimeout(const timeval &t);
 106
 107   //! Causes the timer to begin
 108   /*!
 109     The timer fires after the time in OBTimer::getTimeout has passed since this
 110     function was called.
 111     Calling this function while the timer is already started will cause it to
 112     restart its countdown.
 113   */
 114   void start();  // manager acquires timer
 115   //! Causes the timer to stop
 116   /*!
 117     The timer will no longer fire once this function has been called.
 118     Calling this function more than once does not have any effect.
 119   */
 120   void stop();   // manager releases timer
 121
 122   //! Determines if this OBTimer will fire before a second OBTimer object
 123   /*!
 124     @param other The second OBTimer with which to compare
 125     @return true if this OBTimer will fire before 'other'; otherwise, false
 126   */
 127   bool operator<(const OBTimer& other) const
 128   { return shouldFire(other.endpoint()); }
 129 };
 130
 131 }
 132
 133 #endif // __timer_hh