Scheduler: begin new implementation

[senf.git] / Scheduler / Scheduler.hh

diff --git a/Scheduler/Scheduler.hh b/Scheduler/Scheduler.hh
index 5f0f635..0d8a149 100644 (file)
--- a/Scheduler/Scheduler.hh
+++ b/Scheduler/Scheduler.hh
@@ -72,8 +72,12 @@ namespace senf {
         If you need to pass additional information to your handler, use <a
         href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
         \code
+        // Handle callback function
+        void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
         // Pass 'handle' as additional first argument to callback()
-        Scheduler::instance().add(handle, boost::bind(&callback, handle, _1))
+        Scheduler::instance().add(handle, boost::bind(&callback, handle, _1), EV_READ)
+         // Timeout function
+        void timeout( int n) {..}
         // Call timeout() handler with argument 'n'
         Scheduler::instance().timeout(boost::bind(&timeout, n))
         \endcode
@@ -82,7 +86,7 @@ namespace senf {
         href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
         \code
         // e.g. in Foo::Foo() constructor:
-        Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this))
+        Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this)), EV_READ)
         \endcode
         
 
@@ -90,7 +94,7 @@ namespace senf {
         
         File descriptors are managed using add() or remove()
         \code
-        Scheduler::instance().add(handle, &callback);
+        Scheduler::instance().add(handle, &callback, EV_ALL);
         Scheduler::instance().remove(handle);
         \endcode 
 
@@ -156,6 +160,9 @@ namespace senf {
         
         \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
             over e.g. NFS.
+
+        \todo Add a check in the alarm callback which is already called every x seconds to check,
+            that a single callback is not blocking.
       */
     class Scheduler
         : boost::noncopyable
@@ -167,11 +174,23 @@ namespace senf {
         ///////////////////////////////////////////////////////////////////////////
         // Types
 
-        /** \brief Types of file descriptor events */
-        enum EventId { EV_NONE=0,
-                       EV_READ=1, EV_PRIO=2, EV_WRITE=4, 
-                       EV_ALL=7,
-                       EV_HUP=8, EV_ERR=16 };
+        /** \brief Types of file descriptor events 
+
+            These events are grouped into to classes:
+            \li Ordinary file descriptor events for which handlers may be registered. These are
+                EV_READ, EV_PRIO and EV_WRITE. EV_ALL is a combination of these three.
+            \li Error flags. These additional flags may be passed to a handler to pass an error
+                condition to the handler. 
+         */
+        enum EventId { 
+            EV_NONE  =  0   /**< No event */
+          , EV_READ  =  1   /**< File descriptor is readable */
+          , EV_PRIO  =  2   /**< File descriptor has OOB data */
+          , EV_WRITE =  4   /**< File descriptor is writable */
+          , EV_ALL   =  7   /**< Used to register all events at once (read/prio/write) */
+          , EV_HUP   =  8   /**< Hangup condition on file handle */
+          , EV_ERR   = 16   /**< Error condition on file handle */
+        };
 
         /** \brief Template typedef for Callback type
 
@@ -234,7 +253,8 @@ namespace senf {
                                                  the Handle interface defined above.
                                              \param[in] cb callback
                                              \param[in] eventMask arbitrary combination via '|'
-                                                 operator of EventId designators. */
+                                                 operator of \ref senf::Scheduler::EventId "EventId"
+                                                 designators. */
         template <class Handle>
         void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
                                         /**< remove() will remove any callback registered for any of
@@ -243,8 +263,8 @@ namespace senf {
                                              \param[in] handle file descriptor or handle providing
                                                  the Handle interface defined above.
                                              \param[in] eventMask arbitrary combination via '|'
-                                                 operator of EventId designators. */
-
+                                                 operator of \ref senf::Scheduler::EventId "EventId"
+                                                 designators. */
         ///\}
 
         ///\name Timeouts
@@ -252,7 +272,8 @@ namespace senf {
 
         unsigned timeout(ClockService::clock_type timeout, SimpleCallback const & cb); 
                                         ///< Add timeout event
-                                        /**< \param[in] timeout timeout in nanoseconds
+                                        /**< \returns timer id
+                                             \param[in] timeout timeout in nanoseconds
                                              \param[in] cb callback to call after \a timeout
                                                  milliseconds */
 
@@ -263,7 +284,7 @@ namespace senf {
         void timeoutEarly(ClockService::clock_type v);
                                         ///< Set the \a timeoutEarly parameter
 
-        ClockService::clock_type timeoutAdjust() const;\
+        ClockService::clock_type timeoutAdjust() const;
                                         ///< Fetch the \a timeoutAdjust parameter
         void timeoutAdjust(ClockService::clock_type v);
                                         ///< Set the \a timeoutAdjust parameter
@@ -283,9 +304,9 @@ namespace senf {
                                         ///< Remove signal handler for \a signal
 
         /// The signal number passed to registerSignal or unregisterSignal is invalid
-        struct InvalidSignalNumberException : public std::exception
-        { virtual char const * what() const throw() 
-                { return "senf::Scheduler::InvalidSignalNumberException"; } };
+        struct InvalidSignalNumberException : public senf::Exception
+        { InvalidSignalNumberException() 
+              : senf::Exception("senf::Scheduler::InvalidSignalNumberException"){} };
 
 
         ///\}
@@ -303,6 +324,10 @@ namespace senf {
                                              returns. */
         
         ClockService::clock_type eventTime() const; ///< Return date/time of last event
+                                        /**< This is the timestamp, the last event has been
+                                             signaled. This is the real time at which the event is
+                                             delivered \e not the time it should have been delivered
+                                             (in the case of timers). */
 
     protected:
 
@@ -409,7 +434,7 @@ namespace senf {
      */
     struct SchedulerLogTimeSource : public senf::log::TimeSource
     {
-        boost::posix_time::ptime operator()() const;
+        senf::log::time_type operator()() const;
     };
 
 }