X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Scheduler%2FScheduler.hh;h=a8cfe59f3629b6e50190aef537a218d4e3e00a25;hb=eb89ea10c8c11d2ef12239cb037c958dec50f006;hp=846e60eff92bd0bda64630ad8c24d5afe835ac30;hpb=04b5fd6be72efd504de15a215a268f8b82f4d132;p=senf.git
diff --git a/Scheduler/Scheduler.hh b/Scheduler/Scheduler.hh
index 846e60e..a8cfe59 100644
--- a/Scheduler/Scheduler.hh
+++ b/Scheduler/Scheduler.hh
@@ -24,14 +24,15 @@
\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 "../Utils/Logger/SenfLog.hh"
#include "FdEvent.hh"
#include "TimerEvent.hh"
#include "SignalEvent.hh"
+#include "EventHook.hh"
//#include "scheduler.mpp"
///////////////////////////////hh.p////////////////////////////////////////
@@ -42,12 +43,62 @@ namespace senf {
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.
+ \li Specific \ref sched_objects, 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.
+ \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
@@ -86,18 +137,64 @@ namespace senf {
messages to identify the failing handler.
- \section sched_fd Registering events
+ \section sched_exec Executing the Scheduler
- Events are registered by allocating an instance of the corresponding event class:
+ To enter the scheduler main-loop, call
+
+ \code
+ senf::scheduler::process();
+ \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
+ 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:
- 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.
+ \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) );
+ }
+
+ void callback(int fd, int events)
+ {
+ FdEvent & event (fdEvents_[fd]);
+
+ // ...
+
+ if (complete)
+ fdEvents_.remove(fd)
+ }
+
+ private:
+ boost::ptr_map 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 Boost.PointerContainer
+ for the pointer container library reference.
+
\todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
over e.g. NFS.
*/
@@ -119,7 +216,7 @@ namespace scheduler {
*/
void terminate();
- /** \brief Return date/time of last event
+ /** \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).
@@ -143,12 +240,19 @@ namespace scheduler {
*/
void restart();
+ /** \brief Return \c true, if any 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.
*/