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