#include "EventHook.hh"
//#include "scheduler.mpp"
-///////////////////////////////hh.p////////////////////////////////////////
+//-/////////////////////////////////////////////////////////////////////////////////////////////////
namespace senf {
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.
+ the object responsible for it's creation.
Every event registration is represented by an instance of an event specific class:
\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.
+ 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
public:
SomeServer(SomeSocketHandle handle)
- : handle_ (handle),
+ : handle_ (handle),
event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
handle, senf::scheduler::FdEvent::EV_READ)
{}
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.
+ %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
\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.
+ href="http://www.boost.org/doc/libs/release/libs/functional/index.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>:
+ href="http://www.boost.org/doc/libs/release/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),
+ senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
handle, senf::scheduler::FdEvent::EV_READ);
// Timeout function
void timeout( int n) {..}
\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()
+ href="http://www.boost.org/doc/libs/release/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),
+ readevent_ ("Foo read", senf::membind(&Foo::callback, this),
handle_, senf::scheduler::FdEvent::EV_READ)
{ ... }
\endcode
\section sched_exec Executing the Scheduler
- To enter the scheduler main-loop, call
-
+ To enter the %scheduler main-loop, call
+
\code
senf::scheduler::process();
\endcode
\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,
+ fd,
+ new senf::scheduler::FdEvent("foo", boost::bind(&callback, this, fd, _1), fd,
senf::scheduler::FdEvent::EV_READ) );
}
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>
+ href="http://www.boost.org/doc/libs/release/libs/ptr_container/doc/ptr_container.html">Boost.PointerContainer</a>
for the pointer container library reference.
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
+ 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.
+ 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
*/
namespace scheduler {
- /** \brief Event handler main loop
-
+ /** \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.
- */
+ \li the run queue becomes empty.
+ */
void process();
/** \brief \c true, if scheduler is running, \c false otherwise */
/** \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.
+ will return to it's caller after the currently running callback returns.
*/
- void terminate();
+ void terminate();
/** \brief Immediately rescheduler
/** \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).
+ event is delivered \e not the time it should have been delivered (in the case of timers).
*/
- ClockService::clock_type eventTime();
+ ClockService::clock_type eventTime();
/** \brief Return (approximate) current time
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);
+ void watchdogTimeout(unsigned ms);
/** \brief Current watchdog timeout in milliseconds */
- unsigned watchdogTimeout();
+ unsigned watchdogTimeout();
- /** \brief Number of watchdog events
+ /** \brief Number of watchdog events
calling watchtogEvents() will reset the counter to 0
*/
- unsigned watchdogEvents();
+ unsigned watchdogEvents();
/** \brief Enable/disable abort on watchdog event.
-
+
Calling watchdogAbort(\c true) will enable aborting the program execution on a watchdog
event.
*/
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.
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();
+ 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
+ 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.
/** \brief Temporarily block all signals
This class is used to temporarily block all signals in a critical section.
-
+
\code
// Begin critical section
{
/**< \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
}}
-///////////////////////////////hh.e////////////////////////////////////////
+//-/////////////////////////////////////////////////////////////////////////////////////////////////
#include "Scheduler.cci"
//#include "Scheduler.ct"
//#include "Scheduler.cti"