svn commit: r1641658 - /qpid/trunk/qpid/cpp/src/qpid/sys/Timer.h

[as...@apache.org]

Author: astitcher
Date: Tue Nov 25 17:39:54 2014
New Revision: 1641658

URL: http://svn.apache.org/r1641658
Log:
NO-JIRA: Improve the Timer/TimerTask documentation.

Modified:
    qpid/trunk/qpid/cpp/src/qpid/sys/Timer.h

Modified: qpid/trunk/qpid/cpp/src/qpid/sys/Timer.h
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/src/qpid/sys/Timer.h?rev=1641658&r1=1641657&r2=1641658&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/src/qpid/sys/Timer.h (original)
+++ qpid/trunk/qpid/cpp/src/qpid/sys/Timer.h Tue Nov 25 17:39:54 2014
@@ -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:



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org