// -*- mode: C++; indent-tabs-mode: nil; -*-
-#ifndef _BLACKBOX_Timer_hh
-#define _BLACKBOX_Timer_hh
+#ifndef __timer_hh
+#define __timer_hh
extern "C" {
#ifdef TIME_WITH_SYS_TIME
#endif // TIME_WITH_SYS_TIME
}
-#include <queue>
-#include <algorithm>
-#include <vector>
-
namespace otk {
-// forward declaration
class OBTimerQueueManager;
+//! The data passed to the OBTimeoutHandler 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);
+//! A Timer class which will fire a function when its time elapses
class OBTimer {
private:
- OBTimerQueueManager *manager;
- OBTimeoutHandler handler;
- OBTimeoutData data;
- bool timing, recur;
-
- timeval _start, _timeout;
-
+ //! The manager which to add ourself to and remove ourself after we are done
+ OBTimerQueueManager *_manager;
+ //! The function to call when the time elapses
+ OBTimeoutHandler _handler;
+ //! The data which gets passed along to the OBTimeoutHandler
+ OBTimeoutData _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 OBTimer objects
OBTimer(const OBTimer&);
+ //! Disallows copying of OBTimer objects
OBTimer& operator=(const OBTimer&);
public:
+ //! Constructs a new OBTimer object
+ /*!
+ @param m The OBTimerQueueManager 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
+ */
OBTimer(OBTimerQueueManager *m, OBTimeoutHandler h, OBTimeoutData d);
+ //! Destroys the OBTimer object
virtual ~OBTimer();
- void fireTimeout();
+ //! Fires the timer, calling its OBTimeoutHandler
+ void fire();
- inline bool isTiming() const { return timing; }
- inline bool isRecurring() const { return recur; }
+ //! Returns if the OBTimer is started and timing
+ inline bool timing() const { return _timing; }
+ //! Returns if the OBTimer is going to repeat
+ inline bool recurring() const { return _recur; }
- inline const timeval &getTimeout() const { return _timeout; }
- inline const timeval &getStartTime() const { return _start; }
+ //! Gets the amount of time the OBTimer should last before firing
+ inline const timeval &timeout() const { return _timeout; }
+ //! Gets the time at which the OBTimer started
+ inline const timeval &startTime() const { return _start; }
- timeval timeRemaining(const timeval &tm) const;
+ //! Gets the amount of time left before the OBTimer fires
+ timeval remainingTime(const timeval &tm) const;
+ //! Returns if the OBTimer 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 OBTimer will fire
+ timeval endTime() const;
+
+ //! Sets the OBTimer 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 OBTimer to last in milliseconds
+ /*!
+ @param t The number of milliseconds the timer should last
+ */
void setTimeout(long t);
+ //! Sets the amount of time the OBTimer 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 OBTimer::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()); }
-};
-
-
-template <class _Tp, class _Sequence, class _Compare>
-class _timer_queue: protected std::priority_queue<_Tp, _Sequence, _Compare> {
-public:
- typedef std::priority_queue<_Tp, _Sequence, _Compare> _Base;
-
- _timer_queue(): _Base() {}
- ~_timer_queue() {}
-
- void release(const _Tp& value) {
- c.erase(std::remove(c.begin(), c.end(), value), c.end());
- // after removing the item we need to make the heap again
- std::make_heap(c.begin(), c.end(), comp);
- }
- bool empty() const { return _Base::empty(); }
- size_t size() const { return _Base::size(); }
- void push(const _Tp& value) { _Base::push(value); }
- void pop() { _Base::pop(); }
- const _Tp& top() const { return _Base::top(); }
-private:
- // no copying!
- _timer_queue(const _timer_queue&) {}
- _timer_queue& operator=(const _timer_queue&) {}
-};
-
-struct TimerLessThan {
- bool operator()(const OBTimer* const l, const OBTimer* const r) const {
- return *r < *l;
- }
-};
-
-typedef _timer_queue<OBTimer*,
- std::vector<OBTimer*>, TimerLessThan> TimerQueue;
-
-class OBTimerQueueManager {
-private:
- TimerQueue timerList;
-public:
- OBTimerQueueManager() {}
- virtual ~OBTimerQueueManager() {}
-
- //! Will wait for and fire the next timer in the queue.
+ //! Determines if this OBTimer will fire before a second OBTimer object
/*!
- The function will stop waiting if an event is received from the X server.
+ @param other The second OBTimer with which to compare
+ @return true if this OBTimer will fire before 'other'; otherwise, false
*/
- virtual void fire();
-
- virtual void addTimer(OBTimer* timer);
- virtual void removeTimer(OBTimer* timer);
+ bool operator<(const OBTimer& other) const
+ { return shouldFire(other.endTime()); }
};
}
-#endif // _BLACKBOX_Timer_hh
+#endif // __timer_hh