X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Scheduler%2FScheduler.hh;h=62a687ce5f39cea447d7228642a5abff0069b5f8;hb=a1fdb7bb122f0b05be809a922d4b7ef5e125fa67;hp=8c73cdac42a1ca5561348c82be499b7ada463075;hpb=1d247d12d1759ffd77f456efe3a52f03dd289994;p=senf.git diff --git a/Scheduler/Scheduler.hh b/Scheduler/Scheduler.hh index 8c73cda..62a687c 100644 --- a/Scheduler/Scheduler.hh +++ b/Scheduler/Scheduler.hh @@ -24,412 +24,378 @@ \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 -#include -#include -#include -#include #include -#include -#include -#include "ClockService.hh" #include "../Utils/Logger/SenfLog.hh" +#include "FdEvent.hh" +#include "TimerEvent.hh" +#include "SignalEvent.hh" +#include "EventHook.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 \ref sched_objects, 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 Boost.Function 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 Boost.Bind: - \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 + 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 Boost.Bind or senf::membind() - \code - // e.g. in Foo::Foo() constructor: - Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this)) - \endcode - + Every event registration is represented by an instance of an event specific class: - \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 + \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 - 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. + These instance are owned and managed by the user of the scheduler \e not by the scheduler so the + RAII concept can be used. - 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). + \code + class SomeServer + { + SomeSocketHandle handle_; + senf::scheduler::FdEvent 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) + 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 Boost.Function 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 Boost.Bind: + \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 Boost.Bind 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 generic functions 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 + #include + + 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) ); + } - \section sched_timers Registering timers + void callback(int fd, int events) + { + FdEvent & event (fdEvents_[fd]); - 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 busy wait (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. + if (complete) + fdEvents_.remove(fd) + } - \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: + private: + boost::ptr_map fdEvents_; + }; + \endcode - 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 = 1 /**< File descriptor is readable */ - , EV_PRIO = 2 /**< File descriptor has OOB data */ - , EV_WRITE = 4 /**< File descriptor is writable */ - , EV_ALL = 7 /**< Used to register all events at once (read/prio/write) */ - , EV_HUP = 8 /**< Hangup condition on file handle */ - , EV_ERR = 16 /**< Error condition on file handle */ - }; - - /** \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. - \code - template - struct GenericCallback { - typedef boost::function::param_type, - EventId) > Callback; - }; - \endcode - */ - typedef boost::function FdCallback; - - /** \brief Callback type for timer events */ - typedef boost::function 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 - 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 - 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 senf::Exception - { InvalidSignalNumberException() - : senf::Exception("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 + 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 Boost.PointerContainer + for the pointer container library reference. - protected: - private: - Scheduler(); + \section sched_signals Signals and the Watchdog - void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL); - void do_remove(int fd, int eventMask = EV_ALL); + 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. - void registerSigHandlers(); - static void sigHandler(int signal, ::siginfo_t * siginfo, void *); + The watchdog is controlled using the watchdogTimeout(), watchdogEvents() and watchdogAbort(). + functions. -# ifndef DOXYGEN + 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. - /** \brief Descriptor event specification - \internal */ - struct EventSpec - { - FdCallback cb_read; - FdCallback cb_prio; - FdCallback cb_write; + \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 ...) - EventSpec() : file(false) {} + 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. - int epollMask() const; + \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even + over e.g. NFS. + */ +namespace scheduler { - bool file; - }; + /** \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(); - /** \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) {} + /** \brief \c true, if scheduler is running, \c false otherwise */ + bool running(); - bool operator< (TimerSpec const & other) const - { return timeout > other.timeout; } + /** \brief Called by callbacks to terminate the main loop - ClockService::clock_type timeout; - SimpleCallback cb; - unsigned id; - bool canceled; - }; + 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(); -# endif + /** \brief Immediately rescheduler - typedef std::map FdTable; - typedef std::map TimerMap; // sorted by id - typedef std::vector FdEraseList; + Calling yield() will cause the scheduler to terminate the current queue run and immediately + rescheduler all pending tasks. + */ + void yield(); -# ifndef DOXYGEN + /** \brief Return timestamp of last event - 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); - }; + 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 Return (approximate) current time + + 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(); -# endif + /** \brief Set watchdog timeout to \a ms milliseconds. + + Setting the watchdog timeout to 0 will disable the watchdog. + */ + void watchdogTimeout(unsigned ms); - typedef std::priority_queue, - TimerSpecCompare> TimerQueue; // sorted by time + /** \brief Current watchdog timeout in milliseconds */ + unsigned watchdogTimeout(); - typedef std::vector SigHandlers; + /** \brief Number of watchdog events + + calling watchtogEvents() will reset the counter to 0 + */ + unsigned watchdogEvents(); - FdTable fdTable_; - FdEraseList fdErase_; - unsigned files_; + /** \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); - unsigned timerIdCounter_; - TimerQueue timerQueue_; - TimerMap timerMap_; + /** \brief Get current watchdog abort on event status */ + bool watchdogAbort(); - SigHandlers sigHandlers_; - ::sigset_t sigset_; - int sigpipe_[2]; + /** \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. - int epollFd_; - bool terminate_; - ClockService::clock_type eventTime_; - ClockService::clock_type eventEarly_; - ClockService::clock_type eventAdjust_; - }; + 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(); - \relates Scheduler + /** \brief Switch back to using epoll for timing + \see hiresTimers() */ - int retrieve_filehandle(int fd); + 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 + + 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(); + \endcode + + Using this information reduces the number of necessary ClockService::now() calls and thus + the number of system calls. + */ + 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. */ - struct SchedulerLogTimeSource : public senf::log::TimeSource + class BlockSignals + : boost::noncopyable { - boost::posix_time::ptime operator()() const; + 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