X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;f=otk%2Ftimer.hh;h=d518dc5a9abfec6187d365eb97e02f758d6e5c13;hb=f25252a4849ab205856629480178946b2b454aa3;hp=2deeba58ea831c615b79a0164810ae026cda04f6;hpb=9259ec5732851dd66f7c598d629e3808ac7ab3d8;p=chaz%2Fopenbox diff --git a/otk/timer.hh b/otk/timer.hh index 2deeba58..d518dc5a 100644 --- a/otk/timer.hh +++ b/otk/timer.hh @@ -1,6 +1,6 @@ // -*- 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 @@ -15,110 +15,118 @@ extern "C" { #endif // TIME_WITH_SYS_TIME } -#include -#include -#include - 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 _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, 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