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 Visible scheduler interface
  42
  43     The %scheduler singleton manages access to the %scheduler library. It provides access to
  44     several event dispatchers:
  45     \li File descriptor notifications
  46     \li Timeouts
  47     \li UNIX Signals
  48
  49     The %scheduler is entered by calling it's process() member. This call will continue to run as
  50     long as there is something to do, or until one of the handlers calls terminate(). The
  51     %scheduler has 'something to do' as long as there is any file descriptor or timeout active.
  52
  53     The %scheduler only provides low level primitive scheduling capability. Additional helpers
  54     are defined on top of this functionality (e.g. ReadHelper or WriteHelper or the interval
  55     timers of the PPI).
  56
  57
  58     \section sched_handlers Specifying handlers
  59
  60     All handlers are passed as generic <a
  61     href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows
  62     to pass any callable as a handler. Depending on the type of handler, some additional
  63     arguments may be passed to the handler by the %scheduler.
  64
  65     If you need to pass additional information to your handler, use <a
  66     href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
  67     \code
  68     // Handle callback function
  69     void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
  70     // Pass 'handle' as additional first argument to callback()
  71     Scheduler::instance().add(handle, boost::bind(&callback, handle, _1), EV_READ)
  72      // Timeout function
  73     void timeout( int n) {..}
  74     // Call timeout() handler with argument 'n'
  75     Scheduler::instance().timeout(boost::bind(&timeout, n))
  76     \endcode
  77
  78     To use member-functions as callbacks, use either <a
  79     href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
  80     \code
  81     // e.g. in Foo::Foo() constructor:
  82     Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this)), EV_READ)
  83     \endcode
  84
  85     The handler can also be identified by an arbitrary, user specified name. This name is used
  86     in error messages to identify the failing handler.
  87
  88
  89     \section sched_fd Registering file descriptors
  90
  91     File descriptors are managed using add() or remove()
  92     \code
  93     Scheduler::instance().add(handle, &callback, EV_ALL);
  94     Scheduler::instance().remove(handle);
  95     \endcode
  96
  97     The callback will be called with one additional argument. This argument is the event mask of
  98     type EventId. This mask will tell, which of the registered events are signaled. The
  99     additional flags EV_HUP or EV_ERR (on hangup or error condition) may be set additionally.
 100
 101     Only a single handler may be registered for any combination of file descriptor and event
 102     (registering multiple callbacks for a single fd and event does not make sense).
 103
 104     The %scheduler will accept any object as \a handle argument as long as retrieve_filehandle()
 105     may be called on that object
 106     \code
 107     int fd = retrieve_filehandle(handle);
 108     \endcode
 109     to fetch the file handle given some abstract handle type. retrieve_filehandle() will be
 110     found using ADL depending on the argument namespace. A default implementation is provided
 111     for \c int arguments (file descriptors)
 112
 113
 114     \section sched_timers Registering timers
 115
 116     The %scheduler has very simple timer support. There is only one type of timer: A single-shot
 117     deadline timer. More complex timers are built based on this. Timers are managed using
 118     timeout() and cancelTimeout()
 119     \code
 120     int id = Scheduler::instance().timeout(Scheduler::instance().eventTime() + ClockService::milliseconds(100),
 121                                            &callback);
 122     Scheduler::instance().cancelTimeout(id);
 123     \endcode
 124     Timing is based on the ClockService, which provides a high resolution and strictly
 125     monotonous time source which again is based on POSIX timers. Registering a timeout will fire
 126     the callback when the target time is reached. The timer may be canceled by passing the
 127     returned \a id to cancelTimeout().
 128
 129
 130     \section sched_signals Registering POSIX/UNIX signals
 131
 132     The %scheduler also incorporates standard POSIX/UNIX signals. Signals registered with the
 133     %scheduler will be handled \e synchronously within the event loop.
 134     \code
 135     Scheduler::instance().registerSignal(SIGUSR1, &callback);
 136     Scheduler::instance().unregisterSignal(SIGUSR1);
 137     \endcode
 138     When registering a signal with the %scheduler, that signal will automatically be blocked so
 139     it can be handled within the %scheduler.
 140
 141     A registered signal does \e not count as 'something to do'. It is therefore not possible to
 142     wait for signals \e only.
 143
 144     \todo Change the Scheduler API to use RAII. Additionally, this will remove all dynamic
 145         memory allocations from the scheduler.
 146     \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
 147         over e.g. NFS.
 148   */
 149 namespace scheduler {
 150
 151     /** \brief Event handler main loop
 152
 153         This member must be called at some time to enter the event handler main loop. Only while
 154         this function is running any events are handled. The call will return if
 155         \li a callback calls terminate()
 156         \li the run queue becomes empty.
 157      */
 158     void process();
 159
 160     /** \brief Called by callbacks to terminate the main loop
 161
 162         This member may be called by any callback to tell the main loop to terminate. The main loop
 163         will return to it's caller after the currently running callback returns.
 164      */
 165     void terminate();
 166
 167     /** \brief Return date/time of last event
 168
 169         This is the timestamp, the last event has been signaled. This is the real time at which the
 170         event is delivered \e not the time it should have been delivered (in the case of timers).
 171      */
 172     ClockService::clock_type eventTime();
 173
 174     /** \brief Set task watchdog timeout */
 175     void taskTimeout(unsigned ms);
 176
 177     /** \brief Current task watchdog timeout */
 178     unsigned taskTimeout();
 179
 180     /** \brief Number of watchdog events */
 181     unsigned hangCount();
 182
 183     /** \brief Restart scheduler
 184
 185         This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
 186         is necessary after a fork().
 187         \warning This call will \e remove all registered events from the scheduler
 188      */
 189     void restart();
 190
 191     /** \brief %scheduler specific time source for Utils/Logger framework
 192
 193         This time source may be used to provide timing information for log messages within the
 194         Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
 195         information.
 196
 197         Using this information reduces the number of necessary ClockService::now() calls and thus
 198         the number of system calls.
 199      */
 200     struct LogTimeSource : public senf::log::TimeSource
 201     {
 202         senf::log::time_type operator()() const;
 203     };
 204
 205 }}
 206
 207 ///////////////////////////////hh.e////////////////////////////////////////
 208 #include "Scheduler.cci"
 209 //#include "Scheduler.ct"
 210 //#include "Scheduler.cti"
 211 #endif
 212
 213 \f
 214 // Local Variables:
 215 // mode: c++
 216 // fill-column: 100
 217 // c-file-style: "senf"
 218 // indent-tabs-mode: nil
 219 // ispell-local-dictionary: "american"
 220 // compile-command: "scons -u test"
 221 // comment-column: 40
 222 // End: