Scheduler/Scheduler.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <stefan.bund@fokus.fraunhofer.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 <signal.h>
  32 #include <setjmp.h>
  33 #include <map>
  34 #include <queue>
  35 #include <boost/function.hpp>
  36 #include <boost/utility.hpp>
  37 #include <boost/call_traits.hpp>
  38 #include <boost/integer.hpp>
  39 #include "ClockService.hh"
  40 #include "../Utils/Logger.hh"
  41
  42 //#include "scheduler.mpp"
  43 ///////////////////////////////hh.p////////////////////////////////////////
  44
  45 /** \brief SENF Project namespace */
  46 namespace senf {
  47
  48     /** \brief Singleton class to manage the event loop
  49
  50         The Scheduler singleton manages the central event loop. It manages and dispatches all types
  51         of events managed by the scheduler library:
  52         \li File descriptor notifications
  53         \li Timeouts
  54         \li UNIX Signals
  55
  56         The scheduler is entered by calling it's process() member. This call will continue to run as
  57         long as there is something to do, or until one of the handlers calls terminate(). The
  58         Scheduler has 'something to do' as long as there is any file descriptor or timeout active.
  59
  60         The Scheduler only provides low level primitive scheduling capability. Additional helpers
  61         are defined on top of this functionality (e.g. ReadHelper or WriteHelper or the interval
  62         timers of the PPI).
  63
  64
  65         \section sched_handlers Specifying handlers
  66
  67         All handlers are passed as generic <a
  68         href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows
  69         to pass any callable as a handler. Depending on the type of handler, some additional
  70         arguments may be passed to the handler by the scheduler.
  71
  72         If you need to pass additional information to your handler, use <a
  73         href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
  74         \code
  75         // Pass 'handle' as additional first argument to callback()
  76         Scheduler::instance().add(handle, boost::bind(&callback, handle, _1))
  77         // Call timeout() handler with argument 'n'
  78         Scheduler::instance().timeout(boost::bind(&timeout, n))
  79         \endcode
  80
  81         To use member-functions as callbacks, use either <a
  82         href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
  83         \code
  84         // e.g. in Foo::Foo() constructor:
  85         Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this))
  86         \endcode
  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);
  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. Registering a timeout will fire the callback when the target time is
 126         reached. The timer may be canceled by passing the returned \a id to cancelTimeout().
 127
 128         There are two parameters which adjust the exact: \a timeoutEarly and \a timeoutAdjust. \a
 129         timeoutEarly is the time, a callback may be called before the deadline time is
 130         reached. Setting this value below the scheduling granularity of the kernel will have the
 131         scheduler go into a <em>busy wait</em> (that is, an endless loop consuming 100% of CPU
 132         recources) until the deadline time is reached! This is seldom desired. The default setting
 133         of 11ms is adequate in most cases (it's slightly above the lowest linux scheduling
 134         granularity).
 135
 136         The other timeout scheduling parameter is \a timeoutAdjust. This value will be added to the
 137         timeout value before calculating the next delay value thereby compensating for \a
 138         timeoutEarly. By default, this value is set to 0 but may be changed if needed.
 139
 140
 141         \section sched_signals Registering POSIX/UNIX signals
 142
 143         The Scheduler also incorporates standard POSIX/UNIX signals. Signals registered with the
 144         scheduler will be handled \e synchronously within the event loop.
 145         \code
 146         Scheduler::instance().registerSignal(SIGUSR1, &callback);
 147         Scheduler::instance().unregisterSignal(SIGUSR1);
 148         \endcode
 149         When registering a signal with the scheduler, that signal will automatically be blocked so
 150         it can be handled within the scheduler.
 151
 152         A registered signal does \e not count as 'something to do'. It is therefore not possible to
 153         wait for signals \e only.
 154
 155         \todo Fix EventId parameter (probably to int) to allow |-ing without casting ...
 156
 157         \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
 158             over e.g. NFS.
 159       */
 160     class Scheduler
 161         : boost::noncopyable
 162     {
 163     public:
 164
 165         SENF_LOG_CLASS_AREA();
 166
 167         ///////////////////////////////////////////////////////////////////////////
 168         // Types
 169
 170         /** \brief Types of file descriptor events */
 171         enum EventId { EV_NONE=0,
 172                        EV_READ=1, EV_PRIO=2, EV_WRITE=4,
 173                        EV_ALL=7,
 174                        EV_HUP=8, EV_ERR=16 };
 175
 176         /** \brief Template typedef for Callback type
 177
 178             This is a template typedef (which does not exist in C++) that is, a template class whose
 179             sole member is a typedef symbol defining the callback type given the handle type.
 180
 181             The Callback is any callable object taking a \c Handle and an \c EventId as argument.
 182         template <class Handle>
 183         struct GenericCallback {
 184             typedef boost::function<void (typename boost::call_traits<Handle>::param_type,
 185                                           EventId) > Callback;
 186         };
 187          */
 188
 189         typedef boost::function<void (EventId)> FdCallback;
 190
 191         /** \brief Callback type for timer events */
 192         typedef boost::function<void ()> SimpleCallback;
 193
 194         ///////////////////////////////////////////////////////////////////////////
 195         ///\name Structors and default members
 196         ///@{
 197
 198         // private default constructor
 199         // no copy constructor
 200         // no copy assignment
 201         // default destructor
 202         // no conversion constructors
 203
 204         /** \brief Return Scheduler instance
 205
 206             This static member is used to access the singleton instance. This member is save to
 207             return a correctly initialized Scheduler instance even if called at global construction
 208             time
 209
 210             \implementation This static member just defines the Scheduler as a static method
 211                 variable. The C++ standard then provides above guarantee. The instance will be
 212                 initialized the first time, the code flow passes the variable declaration found in
 213                 the instance() body.
 214          */
 215         static Scheduler & instance();
 216
 217         ///@}
 218         ///////////////////////////////////////////////////////////////////////////
 219
 220         ///\name File Descriptors
 221         ///\{
 222
 223         template <class Handle>
 224         void add(Handle const & handle, FdCallback const & cb,
 225                  int eventMask = EV_ALL); ///< Add file handle event callback
 226                                         /**< add() will add a callback to the Scheduler. The
 227                                              callback will be called for the given type of event on
 228                                              the given  arbitrary file-descriptor or
 229                                              handle-like object. If there already is a Callback
 230                                              registered for one of the events requested, the new
 231                                              handler will replace the old one.
 232                                              \param[in] handle file descriptor or handle providing
 233                                                  the Handle interface defined above.
 234                                              \param[in] cb callback
 235                                              \param[in] eventMask arbitrary combination via '|'
 236                                                  operator of EventId designators. */
 237         template <class Handle>
 238         void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
 239                                         /**< remove() will remove any callback registered for any of
 240                                              the given events on the given file descriptor or handle
 241                                              like object.
 242                                              \param[in] handle file descriptor or handle providing
 243                                                  the Handle interface defined above.
 244                                              \param[in] eventMask arbitrary combination via '|'
 245                                                  operator of EventId designators. */
 246
 247         ///\}
 248
 249         ///\name Timeouts
 250         ///\{
 251
 252         unsigned timeout(ClockService::clock_type timeout, SimpleCallback const & cb);
 253                                         ///< Add timeout event
 254                                         /**< \param[in] timeout timeout in nanoseconds
 255                                              \param[in] cb callback to call after \a timeout
 256                                                  milliseconds */
 257
 258         void cancelTimeout(unsigned id); ///< Cancel timeout \a id
 259
 260         ClockService::clock_type timeoutEarly() const;
 261                                         ///< Fetch the \a timeoutEarly parameter
 262         void timeoutEarly(ClockService::clock_type v);
 263                                         ///< Set the \a timeoutEarly parameter
 264
 265         ClockService::clock_type timeoutAdjust() const;\
 266                                         ///< Fetch the \a timeoutAdjust parameter
 267         void timeoutAdjust(ClockService::clock_type v);
 268                                         ///< Set the \a timeoutAdjust parameter
 269
 270         ///\}
 271
 272         ///\name Signal handlers
 273         ///\{
 274
 275         void registerSignal(unsigned signal, SimpleCallback const & cb);
 276                                         ///< Add signal handler
 277                                         /**< \param[in] signal signal number to register handler for
 278                                              \param[in] cb callback to call whenever \a signal is
 279                                                  delivered. */
 280
 281         void unregisterSignal(unsigned signal);
 282                                         ///< Remove signal handler for \a signal
 283
 284         struct InvalidSignalNumberException : public std::exception
 285         { virtual char const * what() const throw()
 286                 { return "senf::Scheduler::InvalidSignalNumberException"; } };
 287
 288
 289         ///\}
 290
 291         void process();                 ///< Event handler main loop
 292                                         /**< This member must be called at some time to enter the
 293                                              event handler main loop. Only while this function is
 294                                              running any events are handled. The call will return
 295                                              only, if any callback calls terminate(). */
 296
 297         void terminate();               ///< Called by callbacks to terminate the main loop
 298                                         /**< This member may be called by any callback to tell the
 299                                              main loop to terminate. The main loop will return to
 300                                              it's caller after the currently running callback
 301                                              returns. */
 302
 303         ClockService::clock_type eventTime() const; ///< Return date/time of last event
 304
 305     protected:
 306
 307     private:
 308         Scheduler();
 309
 310         void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL);
 311         void do_remove(int fd, int eventMask = EV_ALL);
 312
 313         void registerSigHandlers();
 314         static void sigHandler(int signal, ::siginfo_t * siginfo, void *);
 315
 316 #       ifndef DOXYGEN
 317
 318         /** \brief Descriptor event specification
 319             \internal */
 320         struct EventSpec
 321         {
 322             FdCallback cb_read;
 323             FdCallback cb_prio;
 324             FdCallback cb_write;
 325
 326             EventSpec() : file(false) {}
 327
 328             int epollMask() const;
 329
 330             bool file;
 331         };
 332
 333         /** \brief Timer event specification
 334             \internal */
 335         struct TimerSpec
 336         {
 337             TimerSpec() : timeout(), cb() {}
 338             TimerSpec(ClockService::clock_type timeout_, SimpleCallback cb_, unsigned id_)
 339                 : timeout(timeout_), cb(cb_), id(id_), canceled(false) {}
 340
 341             bool operator< (TimerSpec const & other) const
 342                 { return timeout > other.timeout; }
 343
 344             ClockService::clock_type timeout;
 345             SimpleCallback cb;
 346             unsigned id;
 347             bool canceled;
 348         };
 349
 350 #       endif
 351
 352         typedef std::map<int,EventSpec> FdTable;
 353         typedef std::map<unsigned,TimerSpec> TimerMap; // sorted by id
 354
 355 #       ifndef DOXYGEN
 356
 357         struct TimerSpecCompare
 358         {
 359             typedef TimerMap::iterator first_argument_type;
 360             typedef TimerMap::iterator second_argument_type;
 361             typedef bool result_type;
 362
 363             result_type operator()(first_argument_type a, second_argument_type b);
 364         };
 365
 366 #       endif
 367
 368         typedef std::priority_queue<TimerMap::iterator, std::vector<TimerMap::iterator>,
 369                                     TimerSpecCompare> TimerQueue; // sorted by time
 370
 371         typedef std::vector<SimpleCallback> SigHandlers;
 372
 373         FdTable fdTable_;
 374         unsigned files_;
 375
 376         unsigned timerIdCounter_;
 377         TimerQueue timerQueue_;
 378         TimerMap timerMap_;
 379
 380         SigHandlers sigHandlers_;
 381         ::sigset_t sigset_;
 382         int sigpipe_[2];
 383
 384         int epollFd_;
 385         bool terminate_;
 386         ClockService::clock_type eventTime_;
 387         ClockService::clock_type eventEarly_;
 388         ClockService::clock_type eventAdjust_;
 389     };
 390
 391     /** \brief Default file descriptor accessor
 392
 393         retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
 394         file handle argument.
 395
 396         \relates Scheduler
 397      */
 398     int retrieve_filehandle(int fd);
 399
 400     /** \brief Scheduler specific time source for Utils/Logger framework
 401
 402         This time source may be used to provide timing information for log messages within the
 403         Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
 404         information.
 405      */
 406     struct SchedulerLogTimeSource : public senf::log::TimeSource
 407     {
 408         boost::posix_time::ptime operator()() const;
 409     };
 410
 411 }
 412
 413 ///////////////////////////////hh.e////////////////////////////////////////
 414 #include "Scheduler.cci"
 415 //#include "Scheduler.ct"
 416 #include "Scheduler.cti"
 417 #endif
 418
 419 \f
 420 // Local Variables:
 421 // mode: c++
 422 // fill-column: 100
 423 // c-file-style: "senf"
 424 // indent-tabs-mode: nil
 425 // ispell-local-dictionary: "american"
 426 // compile-command: "scons -u test"
 427 // comment-column: 40
 428 // End: