From: g0dil Date: Thu, 25 Sep 2008 15:34:46 +0000 (+0000) Subject: Documentation updates X-Git-Url: http://g0dil.de/git?p=senf.git;a=commitdiff_plain;h=7fe2d6a5663e7723b8f646333e17fe4ba2a1b77a Documentation updates git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@918 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Examples/Sniffer/Mainpage.dox b/Examples/Sniffer/Mainpage.dox index ea3fc29..5d59420 100644 --- a/Examples/Sniffer/Mainpage.dox +++ b/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 Boost.Function 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 Boost.Function 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: diff --git a/Scheduler/FdEvent.cci b/Scheduler/FdEvent.cci index 6573739..2231de9 100644 --- a/Scheduler/FdEvent.cci +++ b/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; } diff --git a/Scheduler/FdEvent.hh b/Scheduler/FdEvent.hh index 4e9e792..75e3f52 100644 --- a/Scheduler/FdEvent.hh +++ b/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" diff --git a/Scheduler/Scheduler.hh b/Scheduler/Scheduler.hh index 846e60e..3329426 100644 --- a/Scheduler/Scheduler.hh +++ b/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(); + \endcode + Using this information reduces the number of necessary ClockService::now() calls and thus the number of system calls. */