// $Id$
//
-// Copyright (C) 2006
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// Copyright (C) 2006
+// 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 "Utils/MicroTime.hh"
+#include <boost/integer.hpp>
+#include "ClockService.hh"
+#include "../Utils/Logger/SenfLog.hh"
//#include "scheduler.mpp"
///////////////////////////////hh.p////////////////////////////////////////
/** \brief Singleton class to manage the event loop
- This class manages a single select() type event loop. A customer of this class may register
- any number of file descriptiors with this class and pass callback functions to be called on
- input, output or error. This functions are specified using boost::function objects (See <a
- href="http://www.boost.org/doc/html/function.html">Boost.Function</a>)
-
- The Scheduler is based on a generic handle representation. The only information needed from
- a handle, is the intrinsic file descriptor. Any object for which the statement
- \code
- int fd = retrieve_filehandle(object);
- \endcode
- is valid and places the relevent file descriptor into fd can be used as a Handle type. There
- is an implementation of retrieve_filehandle(int) within the library to handle explicit file
- descrptors. The <a href="../../../Socket/doc/html/index.html">Socket library</a> provides an
- implementation of <tt>retrive_filehandle(FileHandle handle)</tt>. If you want to support
- some other handle type, just define an apropriate \c retrieve_filehandle function <em>in
- that types namespace</em>.
-
- It is important to note, that for every combination of file descriptor and event, only a \e
- single handler may be installed. Installing more handlers does not make sense. If you need
- to distribute data to serveral interested parties, you must take care of this yourself.
-
- \todo Fix EventId parameter (probably to int) to allow |-ing without casting ...
+ 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 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.
+
+ 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).
+
+
+ \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.
+
+ 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)
+
+
+ \section sched_timers Registering timers
+
+ 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
{
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_HUP=8, EV_ERR=16,
- EV_ALL=31 };
+ /** \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.
+ /** \brief Template typedef for Callback 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;
- };
- /** \brief Callback type for timer events */
- typedef boost::function<void ()> TimerCallback;
+ 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.
+ \code
+ template <class Handle>
+ struct GenericCallback {
+ typedef boost::function<void (typename boost::call_traits<Handle>::param_type,
+ EventId) > Callback;
+ };
+ \endcode
+ */
+ typedef boost::function<void (EventId)> FdCallback;
+
+ /** \brief Callback type for timer events */
+ typedef boost::function<void ()> SimpleCallback;
///////////////////////////////////////////////////////////////////////////
///\name Structors and default members
// 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 guaratee. The instance will be
- initialized the first time, the code flow passes the variable declaration found in
- the instance() body.
- */
+ /** \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,
- typename GenericCallback<Handle>::Callback const & cb,
+ 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
- callbeck 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
- register ed 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>
+ 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. */
-
- void timeout(unsigned long timeout, TimerCallback const & cb); ///< Add timeout event
- /**< \param[in] timeout timeout in milliseconds
- \param[in] cb callback to call after \a timeout
- milliseconds
- \todo Return some kind of handle/pointer and add
- support to update or revoke a timeout */
+ 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(). */
+ 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. */
+ 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:
- typedef boost::function<void (EventId)> SimpleCallback;
-
Scheduler();
-
- void do_add(int fd, SimpleCallback const & cb, int eventMask = EV_ALL);
+
+ void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL);
void do_remove(int fd, int eventMask = EV_ALL);
- /** \brief Descriptor event specification
- \internal */
- struct EventSpec
+ void registerSigHandlers();
+ static void sigHandler(int signal, ::siginfo_t * siginfo, void *);
+
+# ifndef DOXYGEN
+
+ /** \brief Descriptor event specification
+ \internal */
+ struct EventSpec
{
- SimpleCallback cb_read;
- SimpleCallback cb_prio;
- SimpleCallback cb_write;
- SimpleCallback cb_hup;
- SimpleCallback cb_err;
+ 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(unsigned long long timeout_, TimerCallback cb_)
- : timeout(timeout_), cb(cb_) {}
-
- bool operator< (TimerSpec const & other) const
- { return timeout > other.timeout; }
-
- unsigned long long timeout;
- TimerCallback cb;
- };
-
+
+ /** \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::priority_queue<TimerSpec> TimerQueue;
+ typedef std::map<unsigned,TimerSpec> TimerMap; // sorted by id
+ typedef std::vector<unsigned> FdEraseList;
+
+# ifndef DOXYGEN
+
+ struct TimerSpecCompare
+ {
+ 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
+
+ typedef std::priority_queue<TimerMap::iterator, std::vector<TimerMap::iterator>,
+ TimerSpecCompare> TimerQueue; // sorted by time
+
+ typedef std::vector<SimpleCallback> SigHandlers;
FdTable fdTable_;
- TimerQueue timerQueue_;
+ FdEraseList fdErase_;
+ unsigned files_;
+
+ unsigned timerIdCounter_;
+ TimerQueue timerQueue_;
+ TimerMap timerMap_;
+
+ SigHandlers sigHandlers_;
+ ::sigset_t sigset_;
+ int sigpipe_[2];
+
int epollFd_;
bool terminate_;
+ ClockService::clock_type eventTime_;
+ ClockService::clock_type eventEarly_;
+ ClockService::clock_type eventAdjust_;
};
/** \brief Default file descriptor accessor
-
- retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
- file handle argument.
- \relates Scheduler
+ retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
+ file handle argument.
+
+ \relates Scheduler
*/
int retrieve_filehandle(int fd);
+ /** \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.
+ */
+ struct SchedulerLogTimeSource : public senf::log::TimeSource
+ {
+ boost::posix_time::ptime operator()() const;
+ };
+
}
///////////////////////////////hh.e////////////////////////////////////////
\f
// Local Variables:
// mode: c++
-// c-file-style: "senf"
// fill-column: 100
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// comment-column: 40
// End: