added PacketType typedef to PPI-writer interface

[senf.git] / Scheduler / TimerEvent.hh

diff --git a/Scheduler/TimerEvent.hh b/Scheduler/TimerEvent.hh
index b0a4ae5..6084f11 100644 (file)
--- a/Scheduler/TimerEvent.hh
+++ b/Scheduler/TimerEvent.hh
@@ -1,6 +1,6 @@
 // $Id$
 //
-// Copyright (C) 2008 
+// Copyright (C) 2008
 // Fraunhofer Institute for Open Communication Systems (FOKUS)
 // Competence Center NETwork research (NET), St. Augustin, GERMANY
 //     Stefan Bund <g0dil@berlios.de>
@@ -23,8 +23,8 @@
 /** \file
     \brief TimerDispatcher public header */
 
-#ifndef HH_TimerDispatcher_
-#define HH_TimerDispatcher_ 1
+#ifndef HH_SENF_Scheduler_TimerEvent_
+#define HH_SENF_Scheduler_TimerEvent_ 1
 
 // Custom includes
 #include <signal.h>
@@ -47,8 +47,26 @@ namespace scheduler {
         class TimerDispatcher;
     }
 
+    /** \brief Deadline timer event
+
+        The TimerEvent class registers a deadline timer callback which will be called when the
+        timer expires.
+
+        Timer events are implemented using POSIX timers. Depending on kernel features, the timer
+        resolution will be far more precise than the linux clock tick resolution. The nominal timer
+        resolution is 1 nanosecond.
+
+        The timeout time is set as \e absolute time as returned by the senf::ClockService. After
+        expiration, the timer will be disabled. It may be re-enabled by setting a new timeout time.
+        It is also possible to change a running timer resetting the timeout time.
+
+        The TimerEvent class is an implementation of the RAII idiom: The event will be automatically
+        unregistered in the TimerEvent destructor. The TimerEvent instance should be created
+        within the same scope or on a scope below where the callback is defined (e.g. if the
+        callback is a member function it should be defined as a class member).
+     */
     class TimerEvent
-        : public FIFORunner::TaskInfo,
+        : public detail::FIFORunner::TaskInfo,
           public detail::TimerSetBase
     {
     public:
@@ -63,21 +81,47 @@ namespace scheduler {
 
         TimerEvent(std::string const & name, Callback const & cb, ClockService::clock_type timeout,
                    bool initiallyEnabled = true);
+                                        ///< Register a timer event
+                                        /**< Registers \a cb to be called as soon as possible after
+                                             the time \a timeout is reached. If \a initiallyEnabled
+                                             is set \c false, the callback will not be enabled
+                                             automatically. Use enable() to do so.
+                                             \param[in] name Descriptive timer name (purely
+                                                 informational)
+                                             \param[in] cb Callback to call
+                                             \param[in] timeout timeout time after the timer
+                                                 will be disabled
+                                             \param[in] initiallyEnabled if set \c false, do not
+                                                 enable callback automatically. */
         TimerEvent(std::string const & name, Callback const & cb);
+                                        ///< Create a timer event
+                                        /**< Creates a timer event for callback \a cb. The timer is
+                                             initially disabled. Use the timeout() member to set the
+                                             timeout time.
+                                             \param[in] name Descriptive timer name (purely
+                                                 informational)
+                                             \param[in] cb Callback to call. */
         ~TimerEvent();
 
         ///@}
         ///////////////////////////////////////////////////////////////////////////
 
-        void enable();
-        void disable();
-        bool enabled();
+        void disable();                 ///< Disable timer
+        void enable();                  ///< Enable timer
 
-        void action(Callback const & cb);
-        void timeout(ClockService::clock_type timeout, bool enable=true);
+        void action(Callback const & cb); ///< Change timer event callback
+        void timeout(ClockService::clock_type timeout, bool initiallyEnabled=true);
+                                        ///< Re-arm or move timeout
+                                        /**< \param[in] timeout new timeout time
+                                             \param[in] initiallyEnabled if set \c false, do not
+                                                 enable callback automatically. */
+        ClockService::clock_type timeout() const;
+                                        ///< Get current/last timeout value
 
     private:
-        virtual void run();
+        virtual void v_run();
+        virtual char const * v_type() const;
+        virtual std::string v_info() const;
 
         Callback cb_;
         ClockService::clock_type timeout_;