\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 "FdEvent.hh"
#include "TimerEvent.hh"
#include "SignalEvent.hh"
+#include "EventHook.hh"
//#include "scheduler.mpp"
///////////////////////////////hh.p////////////////////////////////////////
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_objects Event classes
+
+ 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.
+
+ Every event registration is represented by an 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
+ \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 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.
+ 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>:
// 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)
+ 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'
- Scheduler::instance().timeout(boost::bind(&timeout, 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:
- Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this)), EV_READ)
+ Foo::Foo()
+ : handle_ (...),
+ readevent_ ("Foo read", senf::membind(&Foo::callback, this),
+ handle_, senf::scheduler::FdEvent::EV_READ)
+ { ... }
\endcode
- The handler can also be identified by an arbitrary, user specified name. This name is used
- in error messages to identify the failing handler.
+ The handler is identified by an arbitrary, user specified name. This name is used in error
+ messages to identify the failing handler.
- \section sched_fd Registering file descriptors
+ \section sched_exec Executing the Scheduler
+
+ To enter the scheduler main-loop, call
- File descriptors are managed using add() or remove()
\code
- Scheduler::instance().add(handle, &callback, EV_ALL);
- Scheduler::instance().remove(handle);
- \endcode
+ senf::scheduler::process();
+ \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.
+ This call will only return in two cases:
- 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).
+ \li When a handler calls senf::scheduler::terminate()
+ \li When there is no active file descriptor or timer event.
- 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)
+ Additional <a href="#autotoc-7.">generic functions</a> provide information and %scheduler
+ parameters.
+ \section sched_container Event objects and container classes
- \section sched_timers Registering timers
+ 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:
- 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().
+ #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_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.
+ \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.
- A registered signal does \e not count as 'something to do'. It is therefore not possible to
- wait for signals \e only.
+ 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 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.
*/
\li a callback calls terminate()
\li the run queue becomes empty.
*/
- void process();
+ void process();
+
+ /** \brief \c true, if scheduler is running, \c false otherwise */
+ bool running();
/** \brief Called by callbacks to terminate the main loop
*/
void terminate();
- /** \brief Return date/time of last event
+ /** \brief Immediately rescheduler
+
+ Calling yield() will cause the scheduler to terminate the current queue run and immediately
+ rescheduler all pending tasks.
+ */
+ void yield();
+
+ /** \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();
- /** \brief Set task watchdog timeout */
- void taskTimeout(unsigned ms);
+ /** \brief Return (approximate) current time
- /** \brief Current task watchdog timeout */
- unsigned taskTimeout();
+ 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();
+
+ /** \brief Set watchdog timeout to \a ms milliseconds.
+
+ Setting the watchdog timeout to 0 will disable the watchdog.
+ */
+ void watchdogTimeout(unsigned ms);
+
+ /** \brief Current watchdog timeout in milliseconds */
+ unsigned watchdogTimeout();
+
+ /** \brief Number of watchdog events
+
+ calling watchtogEvents() will reset the counter to 0
+ */
+ unsigned watchdogEvents();
- /** \brief Number of watchdog events */
- unsigned hangCount();
+ /** \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);
+
+ /** \brief Get current watchdog abort on event status */
+ bool watchdogAbort();
+
+ /** \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.
+
+ High resolution timers are implemented either using POSIX timers or, when available, using
+ the Linux special \c timerfd() syscall.
+
+ 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.
+
+ \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();
+
+ /** \brief return \c true, if \c timerfd() timing is available, \c false otherwise
+ \see hiresTimers()
+ */
+ bool haveScalableHiresTimers();
+
+ /** \brief Return \c true, if using hires times, \c false otherwise
+ \see hiresTimers() */
+ bool usingHiresTimers();
/** \brief Restart 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.
*/
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////////////////////////////////////////
projects / senf.git / blobdiff