4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief Scheduler public header
27 #ifndef HH_SENF_Scheduler_Scheduler_
28 #define HH_SENF_Scheduler_Scheduler_ 1
31 #include "../Utils/Logger/SenfLog.hh"
33 #include "TimerEvent.hh"
34 #include "SignalEvent.hh"
35 #include "EventHook.hh"
37 //#include "scheduler.mpp"
38 ///////////////////////////////hh.p////////////////////////////////////////
42 /** \brief The Scheduler interface
44 The %scheduler API is comprised of two parts:
46 \li Specific \ref sched_objects, one for each type of event.
47 \li Some <a href="#autotoc-7.">generic functions</a> implemented in the \ref senf::scheduler
50 Events are registered via the respective event class. The (global) functions are used to enter
51 the application main-loop or query for global information.
56 \section sched_objects Event classes
58 The Scheduler is based on the RAII principle: Every event is represented by a class
59 instance. The event is registered in the constructor and removed by the destructor of that
60 instance. This implementation automatically links the lifetime of an event with the lifetime of
61 the object resposible for it's creation.
63 Every event registration is represented by an instance of an event specific class:
65 \li senf::scheduler::FdEvent for file descriptor events
66 \li senf::scheduler::TimerEvent for single-shot deadline timer events
67 \li senf::scheduler::SignalEvent for UNIX signal events
68 \li senf::scheduler::EventHook for a special event hook
70 These instance are owned and managed by the user of the scheduler \e not by the scheduler so the
71 RAII concept can be used.
76 SomeSocketHandle handle_;
77 senf::scheduler::FdEvent event_;
80 SomeServer(SomeSocketHandle handle)
82 event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
83 handle, senf::scheduler::FdEvent::EV_READ)
86 void readData(int events)
88 // read data from handle_, check for eof and so on.
93 The event is defined as a class member variable. When the event member is initialized in the
94 constructor, the event is automatically registered (except if the optional \a initiallyEnabled
95 flag argument is set to \c false). The Destructor will automatically remove the event from the
96 scheduler and ensure, that no dead code is called accidentally.
98 The process is the same for the other event types or when registering multiple events. For
99 detailed information on the constructor arguments and other features see the event class
100 documentation referenced below.
103 \section sched_handlers Specifying handlers
105 All handlers are specified as generic <a
106 href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows to
107 pass any callable as a handler. Depending on the type of handler, some additional arguments may
108 be passed to the handler by the %scheduler.
110 If you need to pass additional information to your handler, use <a
111 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
113 // Handle callback function
114 void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
115 // Pass 'handle' as additional first argument to callback()
116 senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
117 handle, senf::scheduler::FdEvent::EV_READ);
119 void timeout( int n) {..}
120 // Call timeout() handler with argument 'n'
121 senf::scheduler::TimerEvent timer ("name", boost::bind(&timeout, n),
122 senf::ClockService::now() + senf::ClockService::seconds(1));
125 To use member-functions as callbacks, use either <a
126 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
128 // e.g. in Foo::Foo() constructor:
131 readevent_ ("Foo read", senf::membind(&Foo::callback, this),
132 handle_, senf::scheduler::FdEvent::EV_READ)
136 The handler is identified by an arbitrary, user specified name. This name is used in error
137 messages to identify the failing handler.
140 \section sched_exec Executing the Scheduler
142 To enter the scheduler main-loop, call
145 senf::scheduler::process();
148 This call will only return in two cases:
150 \li When a handler calls senf::scheduler::terminate()
151 \li When there is no active file descriptor or timer event.
153 Additional <a href="#autotoc-7.">generic functions</a> provide information and %scheduler
156 \section sched_container Event objects and container classes
158 As the event objects are \e not copyable, they cannot be placed into ordinary
159 containers. However, it is quite simple to use pointer containers to hold event instances:
162 #include <boost/ptr_container/ptr_map.hpp>
163 #include <boost/bind.hpp>
172 new senf::scheduler::FdEvent("foo", boost::bind(&callback, this, fd, _1), fd,
173 senf::scheduler::FdEvent::EV_READ) );
176 void callback(int fd, int events)
178 FdEvent & event (fdEvents_[fd]);
187 boost::ptr_map<int, FdEvent> fdEvents_;
191 The pointer container API is (almost) completely identical to the corresponding standard library
192 container API. The only difference is, that all elements added to the container \e must be
193 created via \c new and that the pointer containers themselves are \e not copyable (ok, they are,
194 if the elements are cloneable ...). See <a
195 href="http://www.boost.org/doc/libs/1_36_0/libs/ptr_container/doc/ptr_container.html">Boost.PointerContainer</a>
196 for the pointer container library reference.
198 \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
201 namespace scheduler {
203 /** \brief Event handler main loop
205 This member must be called at some time to enter the event handler main loop. Only while
206 this function is running any events are handled. The call will return if
207 \li a callback calls terminate()
208 \li the run queue becomes empty.
212 /** \brief Called by callbacks to terminate the main loop
214 This member may be called by any callback to tell the main loop to terminate. The main loop
215 will return to it's caller after the currently running callback returns.
219 /** \brief Return timestamp of last event
221 This is the timestamp, the last event has been signaled. This is the real time at which the
222 event is delivered \e not the time it should have been delivered (in the case of timers).
224 ClockService::clock_type eventTime();
226 /** \brief Set task watchdog timeout */
227 void taskTimeout(unsigned ms);
229 /** \brief Current task watchdog timeout */
230 unsigned taskTimeout();
232 /** \brief Number of watchdog events */
233 unsigned hangCount();
235 /** \brief Restart scheduler
237 This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
238 is necessary after a fork().
239 \warning This call will \e remove all registered events from the scheduler
243 /** \brief Return \c true, if any event is registered, \c false otherwise. */
246 /** \brief %scheduler specific time source for Utils/Logger framework
248 This time source may be used to provide timing information for log messages within the
249 Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
253 senf::log::timeSource<senf::scheduler::LogTimeSource>();
256 Using this information reduces the number of necessary ClockService::now() calls and thus
257 the number of system calls.
259 struct LogTimeSource : public senf::log::TimeSource
261 senf::log::time_type operator()() const;
266 ///////////////////////////////hh.e////////////////////////////////////////
267 #include "Scheduler.cci"
268 //#include "Scheduler.ct"
269 //#include "Scheduler.cti"
276 // c-file-style: "senf"
277 // indent-tabs-mode: nil
278 // ispell-local-dictionary: "american"
279 // compile-command: "scons -u test"
280 // comment-column: 40