X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=otk%2Ftimer.hh;h=7d3e726d224c464e0be69668d9d352dcd7e3a600;hb=cc86c196a2c2793403396bb1d2335b63e1413067;hp=0bc38e1be945ed6474e54028fd18c199153f936c;hpb=d4d89ce0bbd3dd0c556a593accb5e48f7ae09d9e;p=chaz%2Fopenbox diff --git a/otk/timer.hh b/otk/timer.hh index 0bc38e1b..7d3e726d 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 +// -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*- +#ifndef __timer_hh +#define __timer_hh extern "C" { #ifdef TIME_WITH_SYS_TIME @@ -15,127 +15,118 @@ extern "C" { #endif // TIME_WITH_SYS_TIME } -#include -#include -#include - namespace otk { -// forward declaration -class OBTimerQueueManager; +class TimerQueueManager; -typedef void *OBTimeoutData; -typedef void (*OBTimeoutHandler)(OBTimeoutData); +//! 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 *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); - void start(); // manager acquires timer - 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; - -//! Manages a queue of OBTimer objects -/*! - All OBTimer objects add themself to an OBTimerQueueManager. The manager is - what fires the timers when their time has elapsed. This is done by having the - application call the OBTimerQueueManager::fire class in its main event loop. -*/ -class OBTimerQueueManager { -private: - //! A priority queue of all timers being managed by this class. - TimerQueue timerList; -public: - //! Constructs a new OBTimerQueueManager - OBTimerQueueManager() {} - //! Destroys the OBTimerQueueManager - virtual ~OBTimerQueueManager() {} - - //! Will wait for and fire the next timer in the queue. + //! Causes the timer to begin /*! - The function will stop waiting if an event is received from the X server. + 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. */ - virtual void fire(); - - //! Adds a new timer to the queue + void start(); // manager acquires timer + //! Causes the timer to stop /*! - @param timer An OBTimer to add to the queue + The timer will no longer fire once this function has been called. + Calling this function more than once does not have any effect. */ - virtual void addTimer(OBTimer* timer); - //! Removes a timer from the queue + void stop(); // manager releases timer + + //! Determines if this Timer will fire before a second Timer object /*! - @param timer An OBTimer already in the queue to remove + @param other The second Timer with which to compare + @return true if this Timer will fire before 'other'; otherwise, false */ - virtual void removeTimer(OBTimer* timer); + bool operator<(const Timer& other) const + { return shouldFire(other.endTime()); } }; } -#endif // _BLACKBOX_Timer_hh +#endif // __timer_hh