Scheduler/Scheduler.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Scheduler public header
  25  */
  26
  27 #ifndef HH_Scheduler_
  28 #define HH_Scheduler_ 1
  29
  30 // Custom includes
  31 #include "../Utils/Logger/SenfLog.hh"
  32 #include "FdEvent.hh"
  33 #include "TimerEvent.hh"
  34 #include "SignalEvent.hh"
  35
  36 //#include "scheduler.mpp"
  37 ///////////////////////////////hh.p////////////////////////////////////////
  38
  39 namespace senf {
  40
  41 /** \brief The Scheduler interface
  42
  43     The %scheduler API is comprised of two parts:
  44
  45     \li Specific event classes, one for each type of event.
  46     \li Some generic functions implemented in the \ref senf::scheduler namespace.
  47
  48     Events are registered via the respective event class. The (global) functions are used to enter
  49     the application main-loop or query for global information.
  50
  51     \autotoc
  52
  53
  54     \section sched_objects Event classes
  55
  56     Every event registration is represented by a class instance of an event specific class:
  57
  58     \li senf::scheduler::FdEvent for file descriptor events
  59     \li senf::scheduler::TimerEvent for single-shot deadline timer events
  60     \li senf::scheduler::SignalEvent for UNIX signal events
  61
  62     These instance are owned and managed by the user of the scheduler \e not by the scheduler so the
  63     RAII concept can be used.
  64
  65     \code
  66     class SomeServer
  67     {
  68         SomeSocketHandle handle_;
  69         senf::scheduler::FdEvent event_;
  70
  71     public:
  72         SomeServer(SomeSocketHandle handle)
  73             : handle_ (handle),
  74               event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
  75                       handle, senf::scheduler::FdEvent::EV_READ)
  76         {}
  77
  78         void readData(int events)
  79         {
  80             // read data from handle_, check for eof and so on.
  81         }
  82     };
  83     \endcode
  84
  85     The event is defined as a class member variable. When the event member is initialized in the
  86     constructor, the event is automatically registered (except if the optional \a initiallyEnabled
  87     flag argument is set to \c false). The Destructor will automatically remove the event from the
  88     scheduler and ensure, that no dead code is called accidentally.
  89
  90     The process is the same for the other event types or when registering multiple events. For
  91     detailed information on the constructor arguments and other features see the event class
  92     documentation referenced below.
  93
  94
  95     \section sched_handlers Specifying handlers
  96
  97     All handlers are specified as generic <a
  98     href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows to
  99     pass any callable as a handler. Depending on the type of handler, some additional arguments may
 100     be passed to the handler by the %scheduler.
 101
 102     If you need to pass additional information to your handler, use <a
 103     href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
 104     \code
 105     // Handle callback function
 106     void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
 107     // Pass 'handle' as additional first argument to callback()
 108     senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
 109                                     handle, senf::scheduler::FdEvent::EV_READ);
 110      // Timeout function
 111     void timeout( int n) {..}
 112     // Call timeout() handler with argument 'n'
 113     senf::scheduler::TimerEvent timer ("name", boost::bind(&timeout, n),
 114                                        senf::ClockService::now() + senf::ClockService::seconds(1));
 115     \endcode
 116
 117     To use member-functions as callbacks, use either <a
 118     href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
 119     \code
 120     // e.g. in Foo::Foo() constructor:
 121     Foo::Foo()
 122         : handle_ (...),
 123           readevent_ ("Foo read", senf::membind(&Foo::callback, this),
 124                       handle_, senf::scheduler::FdEvent::EV_READ)
 125     { ... }
 126     \endcode
 127
 128     The handler is identified by an arbitrary, user specified name. This name is used in error
 129     messages to identify the failing handler.
 130
 131     \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
 132         over e.g. NFS.
 133   */
 134 namespace scheduler {
 135
 136     /** \brief Event handler main loop
 137
 138         This member must be called at some time to enter the event handler main loop. Only while
 139         this function is running any events are handled. The call will return if
 140         \li a callback calls terminate()
 141         \li the run queue becomes empty.
 142      */
 143     void process();
 144
 145     /** \brief Called by callbacks to terminate the main loop
 146
 147         This member may be called by any callback to tell the main loop to terminate. The main loop
 148         will return to it's caller after the currently running callback returns.
 149      */
 150     void terminate();
 151
 152     /** \brief Return date/time of last event
 153
 154         This is the timestamp, the last event has been signaled. This is the real time at which the
 155         event is delivered \e not the time it should have been delivered (in the case of timers).
 156      */
 157     ClockService::clock_type eventTime();
 158
 159     /** \brief Set task watchdog timeout */
 160     void taskTimeout(unsigned ms);
 161
 162     /** \brief Current task watchdog timeout */
 163     unsigned taskTimeout();
 164
 165     /** \brief Number of watchdog events */
 166     unsigned hangCount();
 167
 168     /** \brief Restart scheduler
 169
 170         This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
 171         is necessary after a fork().
 172         \warning This call will \e remove all registered events from the scheduler
 173      */
 174     void restart();
 175
 176     /** \brief %scheduler specific time source for Utils/Logger framework
 177
 178         This time source may be used to provide timing information for log messages within the
 179         Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
 180         information.
 181
 182         \code
 183         senf::log::timeSource<senf::scheduler::LogTimeSource>();
 184         \endcode
 185
 186         Using this information reduces the number of necessary ClockService::now() calls and thus
 187         the number of system calls.
 188      */
 189     struct LogTimeSource : public senf::log::TimeSource
 190     {
 191         senf::log::time_type operator()() const;
 192     };
 193
 194 }}
 195
 196 ///////////////////////////////hh.e////////////////////////////////////////
 197 #include "Scheduler.cci"
 198 //#include "Scheduler.ct"
 199 //#include "Scheduler.cti"
 200 #endif
 201
 202 \f
 203 // Local Variables:
 204 // mode: c++
 205 // fill-column: 100
 206 // c-file-style: "senf"
 207 // indent-tabs-mode: nil
 208 // ispell-local-dictionary: "american"
 209 // compile-command: "scons -u test"
 210 // comment-column: 40
 211 // End: