NO-JIRA: Improve the Timer/TimerTask documentation.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1641658 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 56 insertions, 0 deletions

diff --git a/qpid/cpp/src/qpid/sys/Timer.h b/qpid/cpp/src/qpid/sys/Timer.h
index 5045009609..6281e08913 100644
--- a/qpid/cpp/src/qpid/sys/Timer.h
+++ b/qpid/cpp/src/qpid/sys/Timer.h
@@ -57,12 +57,50 @@ class TimerTask : public RefCounted {
     void fireTask();
 
   public:
+    /** Create a periodic TimerTask
+     *
+     * This TimerTask type will trigger after the specified duration
+     * and can also be retriggered again after the same duration
+     * by using setupNextFire() after it has been fired.
+     *
+     * Before it has been triggered you can use restart() to push off
+     * triggering the TimerTask by the specified duration.
+     */
     QPID_COMMON_EXTERN TimerTask(Duration period, const std::string& name);
+
+    /** Create a TimerTask that fires at a given absolute time
+     *
+     * This is a once only Timer and cannot be restarted after it has fired.
+     */
     QPID_COMMON_EXTERN TimerTask(AbsTime fireTime, const std::string& name);
+
     QPID_COMMON_EXTERN virtual ~TimerTask();
 
+    /** Adjust a periodic TimerTask for next firing time
+     *
+     * Called after a TimerTask has been triggered - probably in the fire()
+     * callback function itself. This will set up a TimerTask for the next
+     * triggering.
+     *
+     * Note that the TimerTask will need to be added again to the Timer.
+     */
     QPID_COMMON_EXTERN void setupNextFire();
+
+    /** Restart a TimerTask so to delay it being firing
+     *
+     * This can be called either with the TimerTask already added to a Timer
+     * or after the task has been triggered. It has the effect of delaying
+     * the task triggering by the initially specified duration.
+     */
     QPID_COMMON_EXTERN void restart();
+
+    /** Cancel a TimerTask so that it is no longer triggered
+     *
+     * After cancelling the only thing you can do nothing further
+     * with a TimerTask.
+     *
+     * The Timer will delete the cancelled TimerTask.
+     */
     QPID_COMMON_EXTERN void cancel();
 
     std::string getName() const { return name; }
@@ -89,8 +127,26 @@ class Timer : private Runnable {
     QPID_COMMON_EXTERN Timer();
     QPID_COMMON_EXTERN virtual ~Timer();
 
+    /** Add an TimerTask to the Timer queue
+     *
+     * Once a TimerTask has been triggered by (calling its fire() function)
+     * the TimerTask is no longer on the Timer queue and needs to be added again.
+     *
+     * Note that TimerTasks must never be added more than once to a Timer
+     * and must never be added simultaneuosly to multiple Timers.
+     */
     QPID_COMMON_EXTERN virtual void add(boost::intrusive_ptr<TimerTask> task);
+
+    /** Start the Timer
+     *
+     * This will start a new thread that runs the Timer and the fire callbacks.
+     */
     QPID_COMMON_EXTERN virtual void start();
+
+    /** Stop the Timer
+     *
+     * This will stop the Timer and its thread.
+     */
     QPID_COMMON_EXTERN virtual void stop();
 
   protected: