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 fire();
  69
  70   //! Returns if the OBTimer is started and timing
  71   inline bool timing() const { return _timing; }
  72   //! Returns if the OBTimer is going to repeat
  73   inline bool recurring() const { return _recur; }
  74
  75   //! Gets the amount of time the OBTimer should last before firing
  76   inline const timeval &timeout() const { return _timeout; }
  77   //! Gets the time at which the OBTimer started
  78   inline const timeval &startTime() const { return _start; }
  79
  80   //! Gets the amount of time left before the OBTimer fires
  81   timeval remainingTime(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 endTime() 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 setRecurring(bool b) { _recur = b; }
  94
  95   //! Sets the amount of time for the OBTimer to last in milliseconds
  96   /*!
  97     @param t The number of milliseconds the timer should last
  98   */
  99   void setTimeout(long t);
 100   //! Sets the amount of time the OBTimer should last before firing
 101   /*!
 102     @param t The amount of time the timer should last
 103   */
 104   void setTimeout(const timeval &t);
 105
 106   //! Causes the timer to begin
 107   /*!
 108     The timer fires after the time in OBTimer::getTimeout has passed since this
 109     function was called.
 110     Calling this function while the timer is already started will cause it to
 111     restart its countdown.
 112   */
 113   void start();  // manager acquires timer
 114   //! Causes the timer to stop
 115   /*!
 116     The timer will no longer fire once this function has been called.
 117     Calling this function more than once does not have any effect.
 118   */
 119   void stop();   // manager releases timer
 120
 121   //! Determines if this OBTimer will fire before a second OBTimer object
 122   /*!
 123     @param other The second OBTimer with which to compare
 124     @return true if this OBTimer will fire before 'other'; otherwise, false
 125   */
 126   bool operator<(const OBTimer& other) const
 127   { return shouldFire(other.endTime()); }
 128 };
 129
 130 }
 131
 132 #endif // __timer_hh