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/SenfLog.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             \code
 183             template <class Handle>
 184             struct GenericCallback {
 185                 typedef boost::function<void (typename boost::call_traits<Handle>::param_type,
 186                                               EventId) > Callback;
 187             };
 188             \endcode
 189          */
 190         typedef boost::function<void (EventId)> FdCallback;
 191
 192         /** \brief Callback type for timer events */
 193         typedef boost::function<void ()> SimpleCallback;
 194
 195         ///////////////////////////////////////////////////////////////////////////
 196         ///\name Structors and default members
 197         ///@{
 198
 199         // private default constructor
 200         // no copy constructor
 201         // no copy assignment
 202         // default destructor
 203         // no conversion constructors
 204
 205         /** \brief Return Scheduler instance
 206
 207             This static member is used to access the singleton instance. This member is save to
 208             return a correctly initialized Scheduler instance even if called at global construction
 209             time
 210
 211             \implementation This static member just defines the Scheduler as a static method
 212                 variable. The C++ standard then provides above guarantee. The instance will be
 213                 initialized the first time, the code flow passes the variable declaration found in
 214                 the instance() body.
 215          */
 216         static Scheduler & instance();
 217
 218         ///@}
 219         ///////////////////////////////////////////////////////////////////////////
 220
 221         ///\name File Descriptors
 222         ///\{
 223
 224         template <class Handle>
 225         void add(Handle const & handle, FdCallback const & cb,
 226                  int eventMask = EV_ALL); ///< Add file handle event callback
 227                                         /**< add() will add a callback to the Scheduler. The
 228                                              callback will be called for the given type of event on
 229                                              the given  arbitrary file-descriptor or
 230                                              handle-like object. If there already is a Callback
 231                                              registered for one of the events requested, the new
 232                                              handler will replace the old one.
 233                                              \param[in] handle file descriptor or handle providing
 234                                                  the Handle interface defined above.
 235                                              \param[in] cb callback
 236                                              \param[in] eventMask arbitrary combination via '|'
 237                                                  operator of EventId designators. */
 238         template <class Handle>
 239         void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
 240                                         /**< remove() will remove any callback registered for any of
 241                                              the given events on the given file descriptor or handle
 242                                              like object.
 243                                              \param[in] handle file descriptor or handle providing
 244                                                  the Handle interface defined above.
 245                                              \param[in] eventMask arbitrary combination via '|'
 246                                                  operator of EventId designators. */
 247
 248         ///\}
 249
 250         ///\name Timeouts
 251         ///\{
 252
 253         unsigned timeout(ClockService::clock_type timeout, SimpleCallback const & cb);
 254                                         ///< Add timeout event
 255                                         /**< \param[in] timeout timeout in nanoseconds
 256                                              \param[in] cb callback to call after \a timeout
 257                                                  milliseconds */
 258
 259         void cancelTimeout(unsigned id); ///< Cancel timeout \a id
 260
 261         ClockService::clock_type timeoutEarly() const;
 262                                         ///< Fetch the \a timeoutEarly parameter
 263         void timeoutEarly(ClockService::clock_type v);
 264                                         ///< Set the \a timeoutEarly parameter
 265
 266         ClockService::clock_type timeoutAdjust() const;\
 267                                         ///< Fetch the \a timeoutAdjust parameter
 268         void timeoutAdjust(ClockService::clock_type v);
 269                                         ///< Set the \a timeoutAdjust parameter
 270
 271         ///\}
 272
 273         ///\name Signal handlers
 274         ///\{
 275
 276         void registerSignal(unsigned signal, SimpleCallback const & cb);
 277                                         ///< Add signal handler
 278                                         /**< \param[in] signal signal number to register handler for
 279                                              \param[in] cb callback to call whenever \a signal is
 280                                                  delivered. */
 281
 282         void unregisterSignal(unsigned signal);
 283                                         ///< Remove signal handler for \a signal
 284
 285         /// The signal number passed to registerSignal or unregisterSignal is invalid
 286         struct InvalidSignalNumberException : public std::exception
 287         { virtual char const * what() const throw()
 288                 { return "senf::Scheduler::InvalidSignalNumberException"; } };
 289
 290
 291         ///\}
 292
 293         void process();                 ///< Event handler main loop
 294                                         /**< This member must be called at some time to enter the
 295                                              event handler main loop. Only while this function is
 296                                              running any events are handled. The call will return
 297                                              only, if any callback calls terminate(). */
 298
 299         void terminate();               ///< Called by callbacks to terminate the main loop
 300                                         /**< This member may be called by any callback to tell the
 301                                              main loop to terminate. The main loop will return to
 302                                              it's caller after the currently running callback
 303                                              returns. */
 304
 305         ClockService::clock_type eventTime() const; ///< Return date/time of last event
 306
 307     protected:
 308
 309     private:
 310         Scheduler();
 311
 312         void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL);
 313         void do_remove(int fd, int eventMask = EV_ALL);
 314
 315         void registerSigHandlers();
 316         static void sigHandler(int signal, ::siginfo_t * siginfo, void *);
 317
 318 #       ifndef DOXYGEN
 319
 320         /** \brief Descriptor event specification
 321             \internal */
 322         struct EventSpec
 323         {
 324             FdCallback cb_read;
 325             FdCallback cb_prio;
 326             FdCallback cb_write;
 327
 328             EventSpec() : file(false) {}
 329
 330             int epollMask() const;
 331
 332             bool file;
 333         };
 334
 335         /** \brief Timer event specification
 336             \internal */
 337         struct TimerSpec
 338         {
 339             TimerSpec() : timeout(), cb() {}
 340             TimerSpec(ClockService::clock_type timeout_, SimpleCallback cb_, unsigned id_)
 341                 : timeout(timeout_), cb(cb_), id(id_), canceled(false) {}
 342
 343             bool operator< (TimerSpec const & other) const
 344                 { return timeout > other.timeout; }
 345
 346             ClockService::clock_type timeout;
 347             SimpleCallback cb;
 348             unsigned id;
 349             bool canceled;
 350         };
 351
 352 #       endif
 353
 354         typedef std::map<int,EventSpec> FdTable;
 355         typedef std::map<unsigned,TimerSpec> TimerMap; // sorted by id
 356         typedef std::vector<unsigned> FdEraseList;
 357
 358 #       ifndef DOXYGEN
 359
 360         struct TimerSpecCompare
 361         {
 362             typedef TimerMap::iterator first_argument_type;
 363             typedef TimerMap::iterator second_argument_type;
 364             typedef bool result_type;
 365
 366             result_type operator()(first_argument_type a, second_argument_type b);
 367         };
 368
 369 #       endif
 370
 371         typedef std::priority_queue<TimerMap::iterator, std::vector<TimerMap::iterator>,
 372                                     TimerSpecCompare> TimerQueue; // sorted by time
 373
 374         typedef std::vector<SimpleCallback> SigHandlers;
 375
 376         FdTable fdTable_;
 377         FdEraseList fdErase_;
 378         unsigned files_;
 379
 380         unsigned timerIdCounter_;
 381         TimerQueue timerQueue_;
 382         TimerMap timerMap_;
 383
 384         SigHandlers sigHandlers_;
 385         ::sigset_t sigset_;
 386         int sigpipe_[2];
 387
 388         int epollFd_;
 389         bool terminate_;
 390         ClockService::clock_type eventTime_;
 391         ClockService::clock_type eventEarly_;
 392         ClockService::clock_type eventAdjust_;
 393     };
 394
 395     /** \brief Default file descriptor accessor
 396
 397         retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
 398         file handle argument.
 399
 400         \relates Scheduler
 401      */
 402     int retrieve_filehandle(int fd);
 403
 404     /** \brief Scheduler specific time source for Utils/Logger framework
 405
 406         This time source may be used to provide timing information for log messages within the
 407         Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
 408         information.
 409      */
 410     struct SchedulerLogTimeSource : public senf::log::TimeSource
 411     {
 412         boost::posix_time::ptime operator()() const;
 413     };
 414
 415 }
 416
 417 ///////////////////////////////hh.e////////////////////////////////////////
 418 #include "Scheduler.cci"
 419 //#include "Scheduler.ct"
 420 #include "Scheduler.cti"
 421 #endif
 422
 423 \f
 424 // Local Variables:
 425 // mode: c++
 426 // fill-column: 100
 427 // c-file-style: "senf"
 428 // indent-tabs-mode: nil
 429 // ispell-local-dictionary: "american"
 430 // compile-command: "scons -u test"
 431 // comment-column: 40
 432 // End: