From d0b55be2c7afb5b25b42804c9eab4995e64dff52 Mon Sep 17 00:00:00 2001
From: Dana Jansens <danakj@orodu.net>
Date: Mon, 4 Nov 2002 05:40:32 +0000
Subject: [PATCH] OBTimer is fully documented. change how the timerqueuemanager
 makes timers fire recursively, so that OBTimer::halt could go away

---
 otk/timer.cc             | 12 +++-----
 otk/timer.hh             | 65 ++++++++++++++++++++++++++++++++++++++--
 otk/timerqueuemanager.cc |  1 -
 3 files changed, 66 insertions(+), 12 deletions(-)

diff --git a/otk/timer.cc b/otk/timer.cc
index bde95f89..3f1afea0 100644
--- a/otk/timer.cc
+++ b/otk/timer.cc
@@ -77,15 +77,11 @@ void OBTimer::start(void)
 
 void OBTimer::stop(void)
 {
-  timing = false;
+  if (timing) {
+    timing = false;
 
-  manager->removeTimer(this);
-}
-
-
-void OBTimer::halt(void)
-{
-  timing = false;
+    manager->removeTimer(this);
+  }
 }
 
 
diff --git a/otk/timer.hh b/otk/timer.hh
index 610a02e6..509a4a07 100644
--- a/otk/timer.hh
+++ b/otk/timer.hh
@@ -28,43 +28,102 @@ 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);
 
+  //! 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
 
+  //! Determines if this OBTimer will fire before a second OBTimer object
+  /*!
+    @param other The second OBTimer with which to compare
+    @return true if this OBTimer will fire before 'other'; otherwise, false
+  */
   bool operator<(const OBTimer& other) const
   { return shouldFire(other.endpoint()); }
 };
diff --git a/otk/timerqueuemanager.cc b/otk/timerqueuemanager.cc
index 0d7d4983..5bd906c5 100644
--- a/otk/timerqueuemanager.cc
+++ b/otk/timerqueuemanager.cc
@@ -45,7 +45,6 @@ void OBTimerQueueManager::fire()
     timerList.pop();
 
     timer->fireTimeout();
-    timer->halt();
     if (timer->isRecurring())
       timer->start();
   }
-- 
2.39.2