]> Dogcows Code - chaz/openbox/blobdiff - otk/timer.hh
OBTimer is fully documented.
[chaz/openbox] / otk / timer.hh
index 0bc38e1be945ed6474e54028fd18c199153f936c..509a4a070d5a16170b1a533db4ec2fe4f91eaed3 100644 (file)
@@ -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,127 +15,119 @@ extern "C" {
 #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:
+  //! 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;
-  bool timing, recur;
+  //! 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;
 
-  timeval _start, _timeout;
+  //! 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();
 
+  //! Fires the timer, calling its OBTimeoutHandler
   void fireTimeout();
 
+  //! Returns if the OBTimer is started and timing
   inline bool isTiming() const { return timing; }
+  //! Returns if the OBTimer is going to repeat
   inline bool isRecurring() const { return recur; }
 
+  //! Gets the amount of time the OBTimer should last before firing
   inline const timeval &getTimeout() const { return _timeout; }
+  //! Gets the time at which the OBTimer started
   inline const timeval &getStartTime() const { return _start; }
 
+  //! Gets the amount of time left before the OBTimer fires
   timeval timeRemaining(const timeval &tm) const;
+  //! Returns if the OBTimer is past its timeout time, and should fire
   bool shouldFire(const timeval &tm) const;
+
+  //! Gets the time at which the OBTimer will fire
   timeval endpoint() 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 recurring(bool b) { recur = b; }
 
+  //! Sets the amount of time for the OBTimer to last before firing 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);
 
-  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 _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;
-
-//! 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 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.
   */
-  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 OBTimer will fire before a second OBTimer object
   /*!
-    @param timer An OBTimer already in the queue to remove
+    @param other The second OBTimer with which to compare
+    @return true if this OBTimer will fire before 'other'; otherwise, false
   */
-  virtual void removeTimer(OBTimer* timer);
+  bool operator<(const OBTimer& other) const
+  { return shouldFire(other.endpoint()); }
 };
 
 }
 
-#endif // _BLACKBOX_Timer_hh
+#endif // __timer_hh
This page took 0.028293 seconds and 4 git commands to generate.