// $Id$
//
// Copyright (C) 2006
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
+// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
#define HH_Scheduler_ 1
// Custom includes
-#include <signal.h>
-#include <setjmp.h>
-#include <map>
-#include <queue>
-#include <boost/function.hpp>
-#include <boost/utility.hpp>
-#include <boost/call_traits.hpp>
-#include <boost/integer.hpp>
-#include "ClockService.hh"
-#include "../Utils/Logger.hh"
+#include "../Utils/Logger/SenfLog.hh"
+#include "FdEvent.hh"
+#include "TimerEvent.hh"
+#include "SignalEvent.hh"
//#include "scheduler.mpp"
///////////////////////////////hh.p////////////////////////////////////////
-/** \brief SENF Project namespace */
namespace senf {
- /** \brief Singleton class to manage the event loop
+/** \brief The Scheduler interface
- The Scheduler singleton manages the central event loop. It manages and dispatches all types
- of events managed by the scheduler library:
- \li File descriptor notifications
- \li Timeouts
- \li UNIX Signals
+ The %scheduler API is comprised of two parts:
- The scheduler is entered by calling it's process() member. This call will continue to run as
- long as there is something to do, or until one of the handlers calls terminate(). The
- Scheduler has 'something to do' as long as there is any file descriptor or timeout active.
+ \li Specific event classes, one for each type of event.
+ \li Some generic functions implemented in the \ref senf::scheduler namespace.
- The Scheduler only provides low level primitive scheduling capability. Additional helpers
- are defined on top of this functionality (e.g. ReadHelper or WriteHelper or the interval
- timers of the PPI).
+ Events are registered via the respective event class. The (global) functions are used to enter
+ the application main-loop or query for global information.
+ \autotoc
- \section sched_handlers Specifying handlers
- All handlers are passed as generic <a
- href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows
- to pass any callable as a handler. Depending on the type of handler, some additional
- arguments may be passed to the handler by the scheduler.
+ \section sched_objects Event classes
- If you need to pass additional information to your handler, use <a
- href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
- \code
- // Pass 'handle' as additional first argument to callback()
- Scheduler::instance().add(handle, boost::bind(&callback, handle, _1))
- // Call timeout() handler with argument 'n'
- Scheduler::instance().timeout(boost::bind(&timeout, n))
- \endcode
-
- To use member-functions as callbacks, use either <a
- href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
- \code
- // e.g. in Foo::Foo() constructor:
- Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this))
- \endcode
-
-
- \section sched_fd Registering file descriptors
-
- File descriptors are managed using add() or remove()
- \code
- Scheduler::instance().add(handle, &callback);
- Scheduler::instance().remove(handle);
- \endcode
-
- The callback will be called with one additional argument. This argument is the event mask of
- type EventId. This mask will tell, which of the registered events are signaled. The
- additional flags EV_HUP or EV_ERR (on hangup or error condition) may be set additionally.
-
- Only a single handler may be registered for any combination of file descriptor and event
- (registering multiple callbacks for a single fd and event does not make sense).
-
- The scheduler will accept any object as \a handle argument as long as retrieve_filehandle()
- may be called on that object
- \code
- int fd = retrieve_filehandle(handle);
- \endcode
- to fetch the file handle given some abstract handle type. retrieve_filehandle() will be
- found using ADL depending on the argument namespace. A default implementation is provided
- for \c int arguments (file descriptors)
+ Every event registration is represented by a class instance of an event specific class:
+ \li senf::scheduler::FdEvent for file descriptor events
+ \li senf::scheduler::TimerEvent for single-shot deadline timer events
+ \li senf::scheduler::SignalEvent for UNIX signal events
- \section sched_timers Registering timers
+ These instance are owned and managed by the user of the scheduler \e not by the scheduler so the
+ RAII concept can be used.
- The Scheduler has very simple timer support. There is only one type of timer: A single-shot
- deadline timer. More complex timers are built based on this. Timers are managed using
- timeout() and cancelTimeout()
- \code
- int id = Scheduler::instance().timeout(Scheduler::instance().eventTime() + ClockService::milliseconds(100),
- &callback);
- Scheduler::instance().cancelTimeout(id);
- \endcode
- Timing is based on the ClockService, which provides a high resolution and strictly
- monotonous time source. Registering a timeout will fire the callback when the target time is
- reached. The timer may be canceled by passing the returned \a id to cancelTimeout().
-
- There are two parameters which adjust the exact: \a timeoutEarly and \a timeoutAdjust. \a
- timeoutEarly is the time, a callback may be called before the deadline time is
- reached. Setting this value below the scheduling granularity of the kernel will have the
- scheduler go into a <em>busy wait</em> (that is, an endless loop consuming 100% of CPU
- recources) until the deadline time is reached! This is seldom desired. The default setting
- of 11ms is adequate in most cases (it's slightly above the lowest linux scheduling
- granularity).
-
- The other timeout scheduling parameter is \a timeoutAdjust. This value will be added to the
- timeout value before calculating the next delay value thereby compensating for \a
- timeoutEarly. By default, this value is set to 0 but may be changed if needed.
-
-
- \section sched_signals Registering POSIX/UNIX signals
-
- The Scheduler also incorporates standard POSIX/UNIX signals. Signals registered with the
- scheduler will be handled \e synchronously within the event loop.
- \code
- Scheduler::instance().registerSignal(SIGUSR1, &callback);
- Scheduler::instance().unregisterSignal(SIGUSR1);
- \endcode
- When registering a signal with the scheduler, that signal will automatically be blocked so
- it can be handled within the scheduler.
-
- A registered signal does \e not count as 'something to do'. It is therefore not possible to
- wait for signals \e only.
-
- \todo Fix EventId parameter (probably to int) to allow |-ing without casting ...
-
- \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
- over e.g. NFS.
- */
- class Scheduler
- : boost::noncopyable
+ \code
+ class SomeServer
{
- public:
-
- SENF_LOG_CLASS_AREA();
-
- ///////////////////////////////////////////////////////////////////////////
- // Types
-
- /** \brief Types of file descriptor events */
- enum EventId { EV_NONE=0,
- EV_READ=1, EV_PRIO=2, EV_WRITE=4,
- EV_ALL=7,
- EV_HUP=8, EV_ERR=16 };
-
- /** \brief Template typedef for Callback type
-
- This is a template typedef (which does not exist in C++) that is, a template class whose
- sole member is a typedef symbol defining the callback type given the handle type.
-
- The Callback is any callable object taking a \c Handle and an \c EventId as argument.
- template <class Handle>
- struct GenericCallback {
- typedef boost::function<void (typename boost::call_traits<Handle>::param_type,
- EventId) > Callback;
- };
- */
-
- typedef boost::function<void (EventId)> FdCallback;
-
- /** \brief Callback type for timer events */
- typedef boost::function<void ()> SimpleCallback;
-
- ///////////////////////////////////////////////////////////////////////////
- ///\name Structors and default members
- ///@{
-
- // private default constructor
- // no copy constructor
- // no copy assignment
- // default destructor
- // no conversion constructors
-
- /** \brief Return Scheduler instance
-
- This static member is used to access the singleton instance. This member is save to
- return a correctly initialized Scheduler instance even if called at global construction
- time
-
- \implementation This static member just defines the Scheduler as a static method
- variable. The C++ standard then provides above guarantee. The instance will be
- initialized the first time, the code flow passes the variable declaration found in
- the instance() body.
- */
- static Scheduler & instance();
-
- ///@}
- ///////////////////////////////////////////////////////////////////////////
-
- ///\name File Descriptors
- ///\{
-
- template <class Handle>
- void add(Handle const & handle, FdCallback const & cb,
- int eventMask = EV_ALL); ///< Add file handle event callback
- /**< add() will add a callback to the Scheduler. The
- callback will be called for the given type of event on
- the given arbitrary file-descriptor or
- handle-like object. If there already is a Callback
- registered for one of the events requested, the new
- handler will replace the old one.
- \param[in] handle file descriptor or handle providing
- the Handle interface defined above.
- \param[in] cb callback
- \param[in] eventMask arbitrary combination via '|'
- operator of EventId designators. */
- template <class Handle>
- void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
- /**< remove() will remove any callback registered for any of
- the given events on the given file descriptor or handle
- like object.
- \param[in] handle file descriptor or handle providing
- the Handle interface defined above.
- \param[in] eventMask arbitrary combination via '|'
- operator of EventId designators. */
-
- ///\}
-
- ///\name Timeouts
- ///\{
-
- unsigned timeout(ClockService::clock_type timeout, SimpleCallback const & cb);
- ///< Add timeout event
- /**< \param[in] timeout timeout in nanoseconds
- \param[in] cb callback to call after \a timeout
- milliseconds */
-
- void cancelTimeout(unsigned id); ///< Cancel timeout \a id
-
- ClockService::clock_type timeoutEarly() const;
- ///< Fetch the \a timeoutEarly parameter
- void timeoutEarly(ClockService::clock_type v);
- ///< Set the \a timeoutEarly parameter
-
- ClockService::clock_type timeoutAdjust() const;\
- ///< Fetch the \a timeoutAdjust parameter
- void timeoutAdjust(ClockService::clock_type v);
- ///< Set the \a timeoutAdjust parameter
-
- ///\}
-
- ///\name Signal handlers
- ///\{
-
- void registerSignal(unsigned signal, SimpleCallback const & cb);
- ///< Add signal handler
- /**< \param[in] signal signal number to register handler for
- \param[in] cb callback to call whenever \a signal is
- delivered. */
-
- void unregisterSignal(unsigned signal);
- ///< Remove signal handler for \a signal
-
- /// The signal number passed to registerSignal or unregisterSignal is invalid
- struct InvalidSignalNumberException : public std::exception
- { virtual char const * what() const throw()
- { return "senf::Scheduler::InvalidSignalNumberException"; } };
-
-
- ///\}
-
- void process(); ///< Event handler main loop
- /**< This member must be called at some time to enter the
- event handler main loop. Only while this function is
- running any events are handled. The call will return
- only, if any callback calls terminate(). */
-
- void terminate(); ///< Called by callbacks to terminate the main loop
- /**< This member may be called by any callback to tell the
- main loop to terminate. The main loop will return to
- it's caller after the currently running callback
- returns. */
-
- ClockService::clock_type eventTime() const; ///< Return date/time of last event
-
- protected:
-
- private:
- Scheduler();
-
- void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL);
- void do_remove(int fd, int eventMask = EV_ALL);
+ SomeSocketHandle handle_;
+ senf::scheduler::FdEvent event_;
- void registerSigHandlers();
- static void sigHandler(int signal, ::siginfo_t * siginfo, void *);
-
-# ifndef DOXYGEN
-
- /** \brief Descriptor event specification
- \internal */
- struct EventSpec
- {
- FdCallback cb_read;
- FdCallback cb_prio;
- FdCallback cb_write;
-
- EventSpec() : file(false) {}
-
- int epollMask() const;
-
- bool file;
- };
-
- /** \brief Timer event specification
- \internal */
- struct TimerSpec
- {
- TimerSpec() : timeout(), cb() {}
- TimerSpec(ClockService::clock_type timeout_, SimpleCallback cb_, unsigned id_)
- : timeout(timeout_), cb(cb_), id(id_), canceled(false) {}
-
- bool operator< (TimerSpec const & other) const
- { return timeout > other.timeout; }
-
- ClockService::clock_type timeout;
- SimpleCallback cb;
- unsigned id;
- bool canceled;
- };
-
-# endif
-
- typedef std::map<int,EventSpec> FdTable;
- typedef std::map<unsigned,TimerSpec> TimerMap; // sorted by id
- typedef std::vector<unsigned> FdEraseList;
-
-# ifndef DOXYGEN
+ public:
+ SomeServer(SomeSocketHandle handle)
+ : handle_ (handle),
+ event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
+ handle, senf::scheduler::FdEvent::EV_READ)
+ {}
- struct TimerSpecCompare
+ void readData(int events)
{
- typedef TimerMap::iterator first_argument_type;
- typedef TimerMap::iterator second_argument_type;
- typedef bool result_type;
-
- result_type operator()(first_argument_type a, second_argument_type b);
- };
-
-# endif
+ // read data from handle_, check for eof and so on.
+ }
+ };
+ \endcode
+
+ The event is defined as a class member variable. When the event member is initialized in the
+ constructor, the event is automatically registered (except if the optional \a initiallyEnabled
+ flag argument is set to \c false). The Destructor will automatically remove the event from the
+ scheduler and ensure, that no dead code is called accidentally.
+
+ The process is the same for the other event types or when registering multiple events. For
+ detailed information on the constructor arguments and other features see the event class
+ documentation referenced below.
+
+
+ \section sched_handlers Specifying handlers
+
+ All handlers are specified as generic <a
+ href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows to
+ pass any callable as a handler. Depending on the type of handler, some additional arguments may
+ be passed to the handler by the %scheduler.
+
+ If you need to pass additional information to your handler, use <a
+ href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
+ \code
+ // Handle callback function
+ void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
+ // Pass 'handle' as additional first argument to callback()
+ senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
+ handle, senf::scheduler::FdEvent::EV_READ);
+ // Timeout function
+ void timeout( int n) {..}
+ // Call timeout() handler with argument 'n'
+ senf::scheduler::TimerEvent timer ("name", boost::bind(&timeout, n),
+ senf::ClockService::now() + senf::ClockService::seconds(1));
+ \endcode
+
+ To use member-functions as callbacks, use either <a
+ href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
+ \code
+ // e.g. in Foo::Foo() constructor:
+ Foo::Foo()
+ : handle_ (...),
+ readevent_ ("Foo read", senf::membind(&Foo::callback, this),
+ handle_, senf::scheduler::FdEvent::EV_READ)
+ { ... }
+ \endcode
+
+ The handler is identified by an arbitrary, user specified name. This name is used in error
+ messages to identify the failing handler.
+
+ \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
+ over e.g. NFS.
+ */
+namespace scheduler {
+
+ /** \brief Event handler main loop
+
+ This member must be called at some time to enter the event handler main loop. Only while
+ this function is running any events are handled. The call will return if
+ \li a callback calls terminate()
+ \li the run queue becomes empty.
+ */
+ void process();
- typedef std::priority_queue<TimerMap::iterator, std::vector<TimerMap::iterator>,
- TimerSpecCompare> TimerQueue; // sorted by time
+ /** \brief Called by callbacks to terminate the main loop
- typedef std::vector<SimpleCallback> SigHandlers;
+ This member may be called by any callback to tell the main loop to terminate. The main loop
+ will return to it's caller after the currently running callback returns.
+ */
+ void terminate();
- FdTable fdTable_;
- FdEraseList fdErase_;
- unsigned files_;
+ /** \brief Return date/time of last event
- unsigned timerIdCounter_;
- TimerQueue timerQueue_;
- TimerMap timerMap_;
+ This is the timestamp, the last event has been signaled. This is the real time at which the
+ event is delivered \e not the time it should have been delivered (in the case of timers).
+ */
+ ClockService::clock_type eventTime();
- SigHandlers sigHandlers_;
- ::sigset_t sigset_;
- int sigpipe_[2];
+ /** \brief Set task watchdog timeout */
+ void taskTimeout(unsigned ms);
- int epollFd_;
- bool terminate_;
- ClockService::clock_type eventTime_;
- ClockService::clock_type eventEarly_;
- ClockService::clock_type eventAdjust_;
- };
+ /** \brief Current task watchdog timeout */
+ unsigned taskTimeout();
- /** \brief Default file descriptor accessor
+ /** \brief Number of watchdog events */
+ unsigned hangCount();
- retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
- file handle argument.
-
- \relates Scheduler
+ /** \brief Restart scheduler
+
+ This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
+ is necessary after a fork().
+ \warning This call will \e remove all registered events from the scheduler
*/
- int retrieve_filehandle(int fd);
+ void restart();
- /** \brief Scheduler specific time source for Utils/Logger framework
+ /** \brief %scheduler specific time source for Utils/Logger framework
This time source may be used to provide timing information for log messages within the
Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
information.
+
+ \code
+ senf::log::timeSource<senf::scheduler::LogTimeSource>();
+ \endcode
+
+ Using this information reduces the number of necessary ClockService::now() calls and thus
+ the number of system calls.
*/
- struct SchedulerLogTimeSource : public senf::log::TimeSource
+ struct LogTimeSource : public senf::log::TimeSource
{
- boost::posix_time::ptime operator()() const;
+ senf::log::time_type operator()() const;
};
-}
+}}
///////////////////////////////hh.e////////////////////////////////////////
#include "Scheduler.cci"
//#include "Scheduler.ct"
-#include "Scheduler.cti"
+//#include "Scheduler.cti"
#endif
\f
projects / senf.git / blobdiff