X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Scheduler%2FScheduler.hh;h=846e60eff92bd0bda64630ad8c24d5afe835ac30;hb=df969ccba42d14c91711b27d3cb9ecd448db2617;hp=aac4671a62c5aa8b69045d638f6c28e9fc2b6d1f;hpb=98f3f38c5872d26fcf544a9d28efe0518e3895e2;p=senf.git diff --git a/Scheduler/Scheduler.hh b/Scheduler/Scheduler.hh index aac4671..846e60e 100644 --- a/Scheduler/Scheduler.hh +++ b/Scheduler/Scheduler.hh @@ -1,9 +1,9 @@ // $Id$ // // Copyright (C) 2006 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) -// Stefan Bund +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Stefan Bund // // 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 @@ -28,203 +28,141 @@ #define HH_Scheduler_ 1 // Custom includes -#include -#include -#include -#include -#include - -#include "Utils/MicroTime.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 - - This class manages a single select() type event loop. A customer of this class may register - any number of file descriptors with this class and pass callback functions to be called on - input, output or error. This functions are specified using boost::function objects (See Boost.Function) - - 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 relevant 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 - descriptors. The Socket library provides an - implementation of retrieve_filehandle(FileHandle handle). If you want to support - some other handle type, just define an appropriate \c retrieve_filehandle function in - that types namespace. - - 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 several interested parties, you must take care of this yourself. - - \todo Fix EventId parameter (probably to int) to allow |-ing without casting ... - */ - class Scheduler - : boost::noncopyable - { - public: - /////////////////////////////////////////////////////////////////////////// - // 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 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 - struct GenericCallback { - typedef boost::function::param_type, - EventId) > Callback; - }; - /** \brief Callback type for timer events */ - typedef boost::function TimerCallback; - - /////////////////////////////////////////////////////////////////////////// - ///\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(); - - ///@} - /////////////////////////////////////////////////////////////////////////// - - template - void add(Handle const & handle, - typename GenericCallback::Callback 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 - 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 - 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 */ - - 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. */ - - protected: - - private: - typedef boost::function SimpleCallback; - - Scheduler(); - - void do_add(int fd, SimpleCallback const & cb, int eventMask = EV_ALL); - void do_remove(int fd, int eventMask = EV_ALL); - - /** \brief Descriptor event specification - \internal */ - struct EventSpec - { - SimpleCallback cb_read; - SimpleCallback cb_prio; - SimpleCallback cb_write; - SimpleCallback cb_hup; - SimpleCallback cb_err; - - int epollMask() const; - }; - - /** \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; - }; - - typedef std::map FdTable; - typedef std::priority_queue TimerQueue; - - FdTable fdTable_; - TimerQueue timerQueue_; - int epollFd_; - bool terminate_; - }; +/** \brief The Scheduler interface + + The %scheduler API is comprised of two parts: + + \li Specific event classes, one for each type of event. + \li Some generic functions implemented in the \ref senf::scheduler namespace. + + Events are registered via the respective event class. The (global) functions are used to enter + the application main-loop or query for global information. + + + \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_fd Registering events + + Events are registered by allocating an instance of the corresponding event 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 + + The destructor of each of these classes will ensure, that the event will be properly + unregistered. The registration can be enabled, disabled or changed using appropriate + members. See the event class for details on a specific type of event. + + \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(); + + /** \brief 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. + */ + void terminate(); + + /** \brief 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). + */ + ClockService::clock_type eventTime(); - /** \brief Default file descriptor accessor + /** \brief Set task watchdog timeout */ + void taskTimeout(unsigned ms); - retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as - file handle argument. + /** \brief Current task watchdog timeout */ + unsigned taskTimeout(); - \relates Scheduler + /** \brief Number of watchdog events */ + unsigned hangCount(); + + /** \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 + + 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. + + 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; + }; -} +}} ///////////////////////////////hh.e//////////////////////////////////////// #include "Scheduler.cci" //#include "Scheduler.ct" -#include "Scheduler.cti" +//#include "Scheduler.cti" #endif @@ -234,4 +172,6 @@ namespace senf { // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" +// compile-command: "scons -u test" +// comment-column: 40 // End: