\brief Scheduler public header
*/
-#ifndef HH_Scheduler_
-#define HH_Scheduler_ 1
+#ifndef HH_SENF_Scheduler_Scheduler_
+#define HH_SENF_Scheduler_Scheduler_ 1
// Custom includes
+#include <boost/utility.hpp>
#include "../Utils/Logger/SenfLog.hh"
-#include "FdDispatcher.hh"
+#include "FdEvent.hh"
#include "TimerEvent.hh"
#include "SignalEvent.hh"
-#include "FileDispatcher.hh"
-#include "../Utils/Logger/SenfLog.hh"
+#include "EventHook.hh"
//#include "scheduler.mpp"
///////////////////////////////hh.p////////////////////////////////////////
-/** \brief SENF Project namespace */
namespace senf {
- /** \brief Visible scheduler interface
+/** \brief The Scheduler interface
- The %scheduler singleton manages access to the %scheduler library. It provides access to
- several event dispatchers:
- \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 \ref sched_objects, one for each type of event.
+ \li Some <a href="#autotoc-7.">generic functions</a> 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
- // Handle callback function
- void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
- // Pass 'handle' as additional first argument to callback()
- Scheduler::instance().add(handle, boost::bind(&callback, handle, _1), EV_READ)
- // Timeout function
- void timeout( int n) {..}
- // Call timeout() handler with argument 'n'
- Scheduler::instance().timeout(boost::bind(&timeout, n))
- \endcode
+ The Scheduler is based on the RAII principle: Every event is represented by a class
+ instance. The event is registered in the constructor and removed by the destructor of that
+ instance. This implementation automatically links the lifetime of an event with the lifetime of
+ the object resposible for it's creation.
- 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)), EV_READ)
- \endcode
+ Every event registration is represented by an instance of an event specific class:
- The handler can also be identified by an arbitrary, user specified name. This name is used
- in error messages to identify the failing handler.
+ \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
+ \li senf::scheduler::EventHook for a special event hook
+
+ These instance are owned and managed by the user of the scheduler \e not by the scheduler so the
+ RAII concept can be used.
+
+ \code
+ class SomeServer
+ {
+ SomeSocketHandle handle_;
+ senf::scheduler::FdEvent event_;
+
+ public:
+ SomeServer(SomeSocketHandle handle)
+ : handle_ (handle),
+ event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
+ handle, senf::scheduler::FdEvent::EV_READ)
+ {}
+
+ void readData(int events)
+ {
+ // 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.
+
+
+ \section sched_exec Executing the Scheduler
+
+ To enter the scheduler main-loop, call
+
+ \code
+ senf::scheduler::process();
+ \endcode
+
+ This call will only return in two cases:
+
+ \li When a handler calls senf::scheduler::terminate()
+ \li When there is no active file descriptor or timer event.
+
+ Additional <a href="#autotoc-7.">generic functions</a> provide information and %scheduler
+ parameters.
+
+ \section sched_container Event objects and container classes
+
+ As the event objects are \e not copyable, they cannot be placed into ordinary
+ containers. However, it is quite simple to use pointer containers to hold event instances:
+
+ \code
+ #include <boost/ptr_container/ptr_map.hpp>
+ #include <boost/bind.hpp>
+
+ class Foo
+ {
+ public:
+ void add(int fd)
+ {
+ fdEvents.insert(
+ fd,
+ new senf::scheduler::FdEvent("foo", boost::bind(&callback, this, fd, _1), fd,
+ senf::scheduler::FdEvent::EV_READ) );
+ }
+
+ void callback(int fd, int events)
+ {
+ FdEvent & event (fdEvents_[fd]);
+
+ // ...
+
+ if (complete)
+ fdEvents_.remove(fd)
+ }
+
+ private:
+ boost::ptr_map<int, FdEvent> fdEvents_;
+ };
+ \endcode
+ The pointer container API is (almost) completely identical to the corresponding standard library
+ container API. The only difference is, that all elements added to the container \e must be
+ created via \c new and that the pointer containers themselves are \e not copyable (ok, they are,
+ if the elements are cloneable ...). See <a
+ href="http://www.boost.org/doc/libs/1_36_0/libs/ptr_container/doc/ptr_container.html">Boost.PointerContainer</a>
+ for the pointer container library reference.
- \section sched_fd Registering file descriptors
+
+ \section sched_signals Signals and the Watchdog
+
+ To secure against blocking callbacks, the %scheduler implementation includes a watchdog
+ timer. This timer will produce a warning message on the standard error stream when a single
+ callback is executing for more than the watchdog timeout value. Since the scheduler
+ implementation is completely single threaded, we cannot terminate the callback but at least we
+ can produce an informative message and optionally the program can be aborted.
+
+ The watchdog is controlled using the watchdogTimeout(), watchdogEvents() and watchdogAbort().
+ functions.
+
+ The watchdog is implemented using a free running interval timer. The watchdog signal (\c SIGURG)
+ must \e not be blocked. If signals need to be blocked for some reason, those regions will not be
+ checked by the watchdog. If a callback blocks, the watchdog has no chance to interrupt the
+ process.
+
+ \warning Since the watchdog is free running for performance reasons, every callback must expect
+ signals to happen. Signals \e will certainly happen since the watchdog signal is generated
+ periodically (which does not necessarily generate a watchdog event ...)
+
+ Additional signals (\c SIGALRM) may occur when using using hires timers on kernel/glibc
+ combinations which do not support timerfd(). On such systems, hires timers are implemented using
+ POSIX timers which generate a considerable number of additional signals.
+
+ \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
- File descriptors are managed using add() or remove()
- \code
- Scheduler::instance().add(handle, &callback, EV_ALL);
- Scheduler::instance().remove(handle);
- \endcode
+ 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();
- 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.
+ /** \brief \c true, if scheduler is running, \c false otherwise */
+ bool running();
- 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).
+ /** \brief Called by callbacks to terminate the main loop
- 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)
+ 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();
+ /** \brief Immediately rescheduler
- \section sched_timers Registering timers
+ Calling yield() will cause the scheduler to terminate the current queue run and immediately
+ rescheduler all pending tasks.
+ */
+ void yield();
- 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 which again is based on POSIX timers. 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().
+ /** \brief Return timestamp of last event
+ 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();
- \section sched_signals Registering POSIX/UNIX signals
+ /** \brief Return (approximate) current time
- 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 Change the Scheduler API to use RAII. Additionally, this will remove all dynamic
- memory allocations from the scheduler.
- \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:
+ This call will return the current time as far as it is already known to the scheduler. If
+ the scheduler is running, this will return eventTime(), otherwise it will return
+ ClockService::now(). While the scheduler is running, this will reduce the number of system
+ calls.
+ */
+ ClockService::clock_type now();
- SENF_LOG_CLASS_AREA();
-
- ///////////////////////////////////////////////////////////////////////////
- // Types
-
- /** \brief Types of file descriptor events
-
- These events are grouped into to classes:
- \li Ordinary file descriptor events for which handlers may be registered. These are
- EV_READ, EV_PRIO and EV_WRITE. EV_ALL is a combination of these three.
- \li Error flags. These additional flags may be passed to a handler to pass an error
- condition to the handler.
- */
- enum EventId {
- EV_NONE = 0 /**< No event */
- , EV_READ = scheduler::FdManager::EV_READ /**< File descriptor is readable */
- , EV_PRIO = scheduler::FdManager::EV_PRIO /**< File descriptor has OOB data */
- , EV_WRITE = scheduler::FdManager::EV_WRITE /**< File descriptor is writable */
- , EV_ALL = scheduler::FdManager::EV_READ
- | scheduler::FdManager::EV_PRIO
- | scheduler::FdManager::EV_WRITE /**< Used to register all events at once
- (read/prio/write) */
- , EV_HUP = scheduler::FdManager::EV_HUP /**< Hangup condition on file handle */
- , EV_ERR = scheduler::FdManager::EV_ERR /**< Error condition on file handle */
- };
-
- /** \brief Callback type for file descriptor events */
- typedef boost::function<void (int)> FdCallback;
-
- /** \brief Callback type for timer events */
- typedef boost::function<void ()> SimpleCallback;
-
- /** \brief Callback type for signal events */
- typedef boost::function<void (siginfo_t const &)> SignalCallback;
-
- ///////////////////////////////////////////////////////////////////////////
- ///\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
- */
- static Scheduler & instance();
-
- ///@}
- ///////////////////////////////////////////////////////////////////////////
-
- ///\name File Descriptors
- ///\{
-
- template <class Handle>
- void add(std::string const & name, 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] name descriptive name to identify the
- callback.
- \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 \ref senf::Scheduler::EventId "EventId"
- designators. */
-
- template <class Handle>
- void add(Handle const & handle, FdCallback const & cb,
- int eventMask = EV_ALL); ///< Add file handle event callback
- /**< \see add() */
-
-
- 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 \ref senf::Scheduler::EventId "EventId"
- designators. */
-
- ///\}
-
- 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. */
+ /** \brief Set watchdog timeout to \a ms milliseconds.
- ClockService::clock_type eventTime() const; ///< Return date/time of last event
- /**< 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). */
+ Setting the watchdog timeout to 0 will disable the watchdog.
+ */
+ void watchdogTimeout(unsigned ms);
- void taskTimeout(unsigned ms);
- unsigned taskTimeout() const;
- unsigned hangCount() const;
+ /** \brief Current watchdog timeout in milliseconds */
+ unsigned watchdogTimeout();
- void restart();
+ /** \brief Number of watchdog events
- protected:
+ calling watchtogEvents() will reset the counter to 0
+ */
+ unsigned watchdogEvents();
- private:
- Scheduler();
+ /** \brief Enable/disable abort on watchdog event.
+
+ Calling watchdogAbort(\c true) will enable aborting the program execution on a watchdog
+ event.
+ */
+ void watchdogAbort(bool flag);
- void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL);
- void do_add(std::string const & name, int fd, FdCallback const & cb,
- int eventMask = EV_ALL);
- void do_remove(int fd, int eventMask);
+ /** \brief Get current watchdog abort on event status */
+ bool watchdogAbort();
- bool terminate_;
+ /** \brief Switch to using hi resolution timers
+
+ By default, timers are implemented directly using epoll. This however restricts the timer
+ resolution to that of the kernel HZ value.
- scheduler::FdDispatcher fdDispatcher_;
- scheduler::FileDispatcher fileDispatcher_;
- };
+ High resolution timers are implemented either using POSIX timers or, when available, using
+ the Linux special \c timerfd() syscall.
- /** \brief Default file descriptor accessor
+ POSIX timers are delivered using signals. A high timer load this increases the signal load
+ considerably. \c timerfd()'s are delivered on a file descriptor and thus don't have such a
+ scalability issue.
- retrieve_filehandle() provides the %scheduler with support for explicit file descriptors as
- file handle argument.
+ \warning The timer source must not be switched from a scheduler callback
+ */
+ void hiresTimers();
+
+ /** \brief Switch back to using epoll for timing
+ \see hiresTimers()
+ */
+ void loresTimers();
- \relates Scheduler
+ /** \brief return \c true, if \c timerfd() timing is available, \c false otherwise
+ \see hiresTimers()
*/
- int retrieve_filehandle(int fd);
+ bool haveScalableHiresTimers();
+
+ /** \brief Return \c true, if using hires times, \c false otherwise
+ \see hiresTimers() */
+ bool usingHiresTimers();
+
+ /** \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
+ */
+ void restart();
+
+ /** \brief Return \c true, if no event is registered, \c false otherwise. */
+ bool empty();
/** \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
{
senf::log::time_type operator()() const;
};
-}
+ /** \brief Temporarily block all signals
+
+ This class is used to temporarily block all signals in a critical section.
+
+ \code
+ // Begin critical section
+ {
+ senf::scheduler::BlockSignals signalBlocker;
+
+ // critical code executed with all signals blocked
+ }
+ // End critical section
+ \endcode
+
+ You need to take care not to block since even the watchdog timer will be disabled while
+ executing within a critical section.
+ */
+ class BlockSignals
+ : boost::noncopyable
+ {
+ public:
+ BlockSignals(bool initiallyBlocked=true);
+ ///< Block signals until end of scope
+ /**< \param[in] initiallyBlocked set to \c false to not
+ automatically block signals initially */
+ ~BlockSignals(); ///< Release all signal blocks
+
+ void block(); ///< Block signals if not blocked
+ void unblock(); ///< Unblock signals if blocked
+ bool blocked() const; ///< \c true, if signals currently blocked, \c false
+ ///< otherwise
+
+ private:
+ bool blocked_;
+ sigset_t allSigs_;
+ sigset_t savedSigs_;
+ };
+
+}}
///////////////////////////////hh.e////////////////////////////////////////
#include "Scheduler.cci"
//#include "Scheduler.ct"
-#include "Scheduler.cti"
+//#include "Scheduler.cti"
#endif
\f
projects / senf.git / blobdiff