Documentation updates

Examples/Sniffer/Mainpage.dox

@@ -132,33 +132,31 @@
 
     \until }
 
-    The class constructor binds the socket defined as a data member to the correct interface.
-
-    \until add
-
-    The public \c run() member is called to run the sniffer.  It first adds the socket to the
-    Scheduler. The \c add() call takes two Arguments, the socket to bind to (which can be a lot of
-    things and must not necessarily be a socket instance) and callback to call, whenever there is an
-    event on that socket. A third argument may be specified to restrict the events, on which the
-    function is called, here we have left out this argument which defaults to
-    senf::Scheduler::EV_ALL.
-
-    The callback is specified as a <a
-    href="http://www.boost.org/doc/html/function.html">Boost.Function</a> object. We use the \c
-    senf::membind helper from the Utils library to build such a function object. This helper takes
-    an arbitrary class member and binds it to a specific instance.
+    The class constructor binds the socket defined as a data member to the correct interface. To
+    tell the scheduler to call us back whenever data is available on the socket, we add a
+    senf::scheduler::FdEvent isntance to out class.
+
+    The senf::scheduler::FdEvent constructor takes several arguments:
+    \li a string describing the event.
+    \li the callback to call whenever the event occurs.  The callback is specified as a <a
+        href="http://www.boost.org/doc/html/function.html">Boost.Function</a> object. We use the \c
+        senf::membind helper from the Utils library to build such a function object. This helper
+        takes an arbitrary class member and binds it to a specific instance.
+    \li the handle or file descriptor to monitor.
+    \li and the events to watch for.
 
     \until }
 
-    Calling the Schedulers \c process() method will start the event loop. This call does not return
-    (ok, it does return in special cases if \c senf::Scheduler::terminate() is called which does not
-    apply here).
+    The public \c run() member is called to run the sniffer.  Here we just forward the call to the
+    scheduler. Calling the Schedulers \c process() method will start the event loop. This call does
+    not return (ok, it does return in special cases if \c senf::scheduler::terminate() is called
+    which does not apply here).
 
     \until {
 
     The \c dumpPacket() member is called by the scheduler whenever an event on the socket is
-    encountered. The scheduler always passes two arguments: The socket and an event id which
-    identifies the type of event which triggered the call.
+    encountered. The scheduler calls this function with a mask of the events which triggered the
+    call.
 
     \until };
 
@@ -189,7 +187,7 @@
 // c-file-style: "senf"
 // indent-tabs-mode: nil
 // ispell-local-dictionary: "american"
-// compile-command: "scons -u test"
+// compile-command: "scons -u doc"
 // mode: flyspell
 // mode: auto-fill
 // End:

Scheduler/FdEvent.cci

@@ -109,7 +109,7 @@ prefix_ bool senf::scheduler::detail::FileDispatcher::empty()
 
 ///////////////////////////////////////////////////////////////////////////
 
-prefix_ int senf::scheduler::retrieve_filehandle(int fd)
+prefix_ int retrieve_filehandle(int fd)
 {
     return fd;
 }

Scheduler/FdEvent.hh

@@ -99,7 +99,7 @@ namespace scheduler {
           , EV_ERR = detail::FdManager::EV_ERR      ///< transport error
           , EV_ALL = (detail::FdManager::EV_READ 
                       | detail::FdManager::EV_WRITE 
-                      | detail::FdManager::EV_PRIO) ///< register all events
+                      | detail::FdManager::EV_PRIO) ///< register all events (read, prio and write)
         };
 
         ///////////////////////////////////////////////////////////////////////////
@@ -171,10 +171,10 @@ namespace scheduler {
         friend class detail::FileDispatcher;
     };
 
-    int retrieve_filehandle(int fd);
-
 }}
 
+int retrieve_filehandle(int fd);
+
 ///////////////////////////////hh.e////////////////////////////////////////
 #include "FdEvent.cci"
 #include "FdEvent.ct"

Scheduler/Scheduler.hh

@@ -48,6 +48,49 @@ namespace senf {
     Events are registered via the respective event class. The (global) functions are used to enter
     the application main-loop or query for global information.
 
+    \autotoc
+
+
+    \section sched_objects Event classes
+
+    Every event registration is represented by a class instance of an event specific class:
+
+    \li senf::scheduler::FdEvent for file descriptor events
+    \li senf::scheduler::TimerEvent for single-shot deadline timer events
+    \li senf::scheduler::SignalEvent for UNIX signal events
+
+    These instance are owned and managed by the user of the scheduler \e not by the scheduler so the
+    RAII concept can be used.
+
+    \code
+    class SomeServer
+    {
+        SomeSocketHandle handle_;
+        senf::scheduler::FdEvent event_;
+
+    public:
+        SomeServer(SomeSocketHandle handle)
+            : handle_ (handle), 
+              event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
+                      handle, senf::scheduler::FdEvent::EV_READ)
+        {}
+
+        void readData(int events)
+        {
+            // read data from handle_, check for eof and so on.
+        }
+    };
+    \endcode
+
+    The event is defined as a class member variable. When the event member is initialized in the
+    constructor, the event is automatically registered (except if the optional \a initiallyEnabled
+    flag argument is set to \c false). The Destructor will automatically remove the event from the
+    scheduler and ensure, that no dead code is called accidentally.
+
+    The process is the same for the other event types or when registering multiple events. For
+    detailed information on the constructor arguments and other features see the event class
+    documentation referenced below.
+
 
     \section sched_handlers Specifying handlers
 
@@ -85,19 +128,6 @@ namespace senf {
     The handler is identified by an arbitrary, user specified name. This name is used in error
     messages to identify the failing handler.
 
-
-    \section sched_fd Registering events
-
-    Events are registered by allocating an instance of the corresponding event class:
-
-    \li senf::scheduler::FdEvent for file descriptor events
-    \li senf::scheduler::TimerEvent for single-shot deadline timer events
-    \li senf::scheduler::SignalEvent for UNIX signal events
-
-    The destructor of each of these classes will ensure, that the event will be properly
-    unregistered. The registration can be enabled, disabled or changed using appropriate
-    members. See the event class for details on a specific type of event.
-    
     \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
         over e.g. NFS.
   */
@@ -149,6 +179,10 @@ namespace scheduler {
         Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
         information.
 
+        \code
+        senf::log::timeSource<senf::scheduler::LogTimeSource>();
+        \endcode
+
         Using this information reduces the number of necessary ClockService::now() calls and thus
         the number of system calls.
      */