-// -*- mode: C++; indent-tabs-mode: nil; -*-
+// -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*-
#ifndef __timer_hh
#define __timer_hh
namespace otk {
-class OBTimerQueueManager;
+class TimerQueueManager;
-//! The data passed to the OBTimeoutHandler function.
+//! The data passed to the TimeoutHandler function.
/*!
Note: this is a very useful place to put an object instance, and set the
event handler to a static function in the same class.
*/
-typedef void *OBTimeoutData;
-//! The type of function which can be set as the callback for an OBTimer firing
-typedef void (*OBTimeoutHandler)(OBTimeoutData);
+typedef void *TimeoutData;
+//! The type of function which can be set as the callback for a Timer firing
+typedef void (*TimeoutHandler)(TimeoutData);
-class OBTimer {
+//! A Timer class which will fire a function when its time elapses
+class Timer {
private:
- OBTimerQueueManager *manager;
- OBTimeoutHandler handler;
- OBTimeoutData data;
- bool timing, recur;
-
- timeval _start, _timeout;
-
- OBTimer(const OBTimer&);
- OBTimer& operator=(const OBTimer&);
+ //! The manager which to add ourself to and remove ourself after we are done
+ TimerQueueManager *_manager;
+ //! The function to call when the time elapses
+ TimeoutHandler _handler;
+ //! The data which gets passed along to the TimeoutHandler
+ TimeoutData _data;
+ //! Determines if the timer is currently started
+ bool _timing;
+ //! When this is true, the timer will reset itself to fire again every time
+ bool _recur;
+
+ //! The time at which the timer started
+ timeval _start;
+ //! The time at which the timer is going to fire
+ timeval _timeout;
+
+ //! Disallows copying of Timer objects
+ Timer(const Timer&);
+ //! Disallows copying of Timer objects
+ Timer& operator=(const Timer&);
public:
- OBTimer(OBTimerQueueManager *m, OBTimeoutHandler h, OBTimeoutData d);
- virtual ~OBTimer();
-
- void fireTimeout();
-
- inline bool isTiming() const { return timing; }
- inline bool isRecurring() const { return recur; }
-
- inline const timeval &getTimeout() const { return _timeout; }
- inline const timeval &getStartTime() const { return _start; }
-
- timeval timeRemaining(const timeval &tm) const;
+ //! Constructs a new Timer object
+ /*!
+ @param m The TimerQueueManager with which to associate. The manager
+ specified will be resposible for making this timer fire.
+ @param h The function to call when the timer fires
+ @param d The data to pass along to the function call when the timer fires
+ */
+ Timer(TimerQueueManager *m, TimeoutHandler h, TimeoutData d);
+ //! Destroys the Timer object
+ virtual ~Timer();
+
+ //! Fires the timer, calling its TimeoutHandler
+ void fire();
+
+ //! Returns if the Timer is started and timing
+ inline bool timing() const { return _timing; }
+ //! Returns if the Timer is going to repeat
+ inline bool recurring() const { return _recur; }
+
+ //! Gets the amount of time the Timer should last before firing
+ inline const timeval &timeout() const { return _timeout; }
+ //! Gets the time at which the Timer started
+ inline const timeval &startTime() const { return _start; }
+
+ //! Gets the amount of time left before the Timer fires
+ timeval remainingTime(const timeval &tm) const;
+ //! Returns if the Timer is past its timeout time, and should fire
bool shouldFire(const timeval &tm) const;
- timeval endpoint() const;
- inline void recurring(bool b) { recur = b; }
+ //! Gets the time at which the Timer will fire
+ timeval endTime() const;
+
+ //! Sets the Timer to repeat or not
+ /*!
+ @param b If true, the timer is set to repeat; otherwise, it will fire only
+ once
+ */
+ inline void setRecurring(bool b) { _recur = b; }
+ //! Sets the amount of time for the Timer to last in milliseconds
+ /*!
+ @param t The number of milliseconds the timer should last
+ */
void setTimeout(long t);
+ //! Sets the amount of time the Timer should last before firing
+ /*!
+ @param t The amount of time the timer should last
+ */
void setTimeout(const timeval &t);
+ //! Causes the timer to begin
+ /*!
+ The timer fires after the time in Timer::getTimeout has passed since this
+ function was called.
+ Calling this function while the timer is already started will cause it to
+ restart its countdown.
+ */
void start(); // manager acquires timer
+ //! Causes the timer to stop
+ /*!
+ The timer will no longer fire once this function has been called.
+ Calling this function more than once does not have any effect.
+ */
void stop(); // manager releases timer
- void halt(); // halts the timer
- bool operator<(const OBTimer& other) const
- { return shouldFire(other.endpoint()); }
+ //! Determines if this Timer will fire before a second Timer object
+ /*!
+ @param other The second Timer with which to compare
+ @return true if this Timer will fire before 'other'; otherwise, false
+ */
+ bool operator<(const Timer& other) const
+ { return shouldFire(other.endTime()); }
};
}