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
  52     \section sched_handlers Specifying handlers
  53
  54     All handlers are specified as generic <a
  55     href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows to
  56     pass any callable as a handler. Depending on the type of handler, some additional arguments may
  57     be passed to the handler by the %scheduler.
  58
  59     If you need to pass additional information to your handler, use <a
  60     href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
  61     \code
  62     // Handle callback function
  63     void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
  64     // Pass 'handle' as additional first argument to callback()
  65     senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
  66                                     handle, senf::scheduler::FdEvent::EV_READ);
  67      // Timeout function
  68     void timeout( int n) {..}
  69     // Call timeout() handler with argument 'n'
  70     senf::scheduler::TimerEvent timer ("name", boost::bind(&timeout, n),
  71                                        senf::ClockService::now() + senf::ClockService::seconds(1));
  72     \endcode
  73
  74     To use member-functions as callbacks, use either <a
  75     href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
  76     \code
  77     // e.g. in Foo::Foo() constructor:
  78     Foo::Foo()
  79         : handle_ (...),
  80           readevent_ ("Foo read", senf::membind(&Foo::callback, this),
  81                       handle_, senf::scheduler::FdEvent::EV_READ)
  82     { ... }
  83     \endcode
  84
  85     The handler is identified by an arbitrary, user specified name. This name is used in error
  86     messages to identify the failing handler.
  87
  88
  89     \section sched_fd Registering events
  90
  91     Events are registered by allocating an instance of the corresponding event class:
  92
  93     \li senf::scheduler::FdEvent for file descriptor events
  94     \li senf::scheduler::TimerEvent for single-shot deadline timer events
  95     \li senf::scheduler::SignalEvent for UNIX signal events
  96
  97     The destructor of each of these classes will ensure, that the event will be properly
  98     unregistered. The registration can be enabled, disabled or changed using appropriate
  99     members. See the event class for details on a specific type of event.
 100
 101     \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
 102         over e.g. NFS.
 103   */
 104 namespace scheduler {
 105
 106     /** \brief Event handler main loop
 107
 108         This member must be called at some time to enter the event handler main loop. Only while
 109         this function is running any events are handled. The call will return if
 110         \li a callback calls terminate()
 111         \li the run queue becomes empty.
 112      */
 113     void process();
 114
 115     /** \brief Called by callbacks to terminate the main loop
 116
 117         This member may be called by any callback to tell the main loop to terminate. The main loop
 118         will return to it's caller after the currently running callback returns.
 119      */
 120     void terminate();
 121
 122     /** \brief Return date/time of last event
 123
 124         This is the timestamp, the last event has been signaled. This is the real time at which the
 125         event is delivered \e not the time it should have been delivered (in the case of timers).
 126      */
 127     ClockService::clock_type eventTime();
 128
 129     /** \brief Set task watchdog timeout */
 130     void taskTimeout(unsigned ms);
 131
 132     /** \brief Current task watchdog timeout */
 133     unsigned taskTimeout();
 134
 135     /** \brief Number of watchdog events */
 136     unsigned hangCount();
 137
 138     /** \brief Restart scheduler
 139
 140         This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
 141         is necessary after a fork().
 142         \warning This call will \e remove all registered events from the scheduler
 143      */
 144     void restart();
 145
 146     /** \brief %scheduler specific time source for Utils/Logger framework
 147
 148         This time source may be used to provide timing information for log messages within the
 149         Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
 150         information.
 151
 152         Using this information reduces the number of necessary ClockService::now() calls and thus
 153         the number of system calls.
 154      */
 155     struct LogTimeSource : public senf::log::TimeSource
 156     {
 157         senf::log::time_type operator()() const;
 158     };
 159
 160 }}
 161
 162 ///////////////////////////////hh.e////////////////////////////////////////
 163 #include "Scheduler.cci"
 164 //#include "Scheduler.ct"
 165 //#include "Scheduler.cti"
 166 #endif
 167
 168 \f
 169 // Local Variables:
 170 // mode: c++
 171 // fill-column: 100
 172 // c-file-style: "senf"
 173 // indent-tabs-mode: nil
 174 // ispell-local-dictionary: "american"
 175 // compile-command: "scons -u test"
 176 // comment-column: 40
 177 // End: