// $Id$
//
// Copyright (C) 2006
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// 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
#include <boost/call_traits.hpp>
#include <boost/integer.hpp>
#include "ClockService.hh"
-#include "../Utils/Logger.hh"
+#include "../Utils/Logger/SenfLog.hh"
//#include "scheduler.mpp"
///////////////////////////////hh.p////////////////////////////////////////
/** \brief Singleton class to manage the event loop
- The Scheduler singleton manages the central event loop. It manages and dispatches all types
+ 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
+ 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.
+ %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
+ 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).
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.
+ 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()
- Scheduler::instance().add(handle, boost::bind(&callback, handle, _1))
+ 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
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))
+ Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this)), EV_READ)
\endcode
File descriptors are managed using add() or remove()
\code
- Scheduler::instance().add(handle, &callback);
+ Scheduler::instance().add(handle, &callback, EV_ALL);
Scheduler::instance().remove(handle);
\endcode
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()
+ 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);
\section sched_timers Registering timers
- The Scheduler has very simple timer support. There is only one type of timer: A single-shot
+ 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
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
+ %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).
\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.
+ 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.
+ 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.
///////////////////////////////////////////////////////////////////////////
// Types
- /** \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 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
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 <class Handle>
- struct GenericCallback {
- typedef boost::function<void (typename boost::call_traits<Handle>::param_type,
- EventId) > Callback;
- };
+ \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 */
// default destructor
// no conversion constructors
- /** \brief Return Scheduler instance
+ /** \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
+ 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
+ \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.
template <class Handle>
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
+ /**< 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
the Handle interface defined above.
\param[in] cb callback
\param[in] eventMask arbitrary combination via '|'
- operator of EventId designators. */
+ operator of \ref senf::Scheduler::EventId "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
\param[in] handle file descriptor or handle providing
the Handle interface defined above.
\param[in] eventMask arbitrary combination via '|'
- operator of EventId designators. */
-
+ operator of \ref senf::Scheduler::EventId "EventId"
+ designators. */
///\}
///\name Timeouts
///< 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"; } };
+ struct InvalidSignalNumberException : public senf::Exception
+ { InvalidSignalNumberException()
+ : senf::Exception("senf::Scheduler::InvalidSignalNumberException"){} };
///\}
/** \brief Default file descriptor accessor
- retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
+ 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
+ /** \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
projects / senf.git / blobdiff