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
28 #define HH_Scheduler_ 1
31 #include "../Utils/Logger/SenfLog.hh"
33 #include "TimerEvent.hh"
34 #include "SignalEvent.hh"
36 //#include "scheduler.mpp"
37 ///////////////////////////////hh.p////////////////////////////////////////
41 /** \brief The Scheduler interface
43 The %scheduler API is comprised of two parts:
45 \li Specific event classes, one for each type of event.
46 \li Some generic functions implemented in the \ref senf::scheduler namespace.
48 Events are registered via the respective event class. The (global) functions are used to enter
49 the application main-loop or query for global information.
54 \section sched_objects Event classes
56 Every event registration is represented by a class instance of an event specific class:
58 \li senf::scheduler::FdEvent for file descriptor events
59 \li senf::scheduler::TimerEvent for single-shot deadline timer events
60 \li senf::scheduler::SignalEvent for UNIX signal events
62 These instance are owned and managed by the user of the scheduler \e not by the scheduler so the
63 RAII concept can be used.
68 SomeSocketHandle handle_;
69 senf::scheduler::FdEvent event_;
72 SomeServer(SomeSocketHandle handle)
74 event_ ("SomeServer handler", senf::membind(&SomeServer::readData, this),
75 handle, senf::scheduler::FdEvent::EV_READ)
78 void readData(int events)
80 // read data from handle_, check for eof and so on.
85 The event is defined as a class member variable. When the event member is initialized in the
86 constructor, the event is automatically registered (except if the optional \a initiallyEnabled
87 flag argument is set to \c false). The Destructor will automatically remove the event from the
88 scheduler and ensure, that no dead code is called accidentally.
90 The process is the same for the other event types or when registering multiple events. For
91 detailed information on the constructor arguments and other features see the event class
92 documentation referenced below.
95 \section sched_handlers Specifying handlers
97 All handlers are specified as generic <a
98 href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows to
99 pass any callable as a handler. Depending on the type of handler, some additional arguments may
100 be passed to the handler by the %scheduler.
102 If you need to pass additional information to your handler, use <a
103 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
105 // Handle callback function
106 void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
107 // Pass 'handle' as additional first argument to callback()
108 senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
109 handle, senf::scheduler::FdEvent::EV_READ);
111 void timeout( int n) {..}
112 // Call timeout() handler with argument 'n'
113 senf::scheduler::TimerEvent timer ("name", boost::bind(&timeout, n),
114 senf::ClockService::now() + senf::ClockService::seconds(1));
117 To use member-functions as callbacks, use either <a
118 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
120 // e.g. in Foo::Foo() constructor:
123 readevent_ ("Foo read", senf::membind(&Foo::callback, this),
124 handle_, senf::scheduler::FdEvent::EV_READ)
128 The handler is identified by an arbitrary, user specified name. This name is used in error
129 messages to identify the failing handler.
131 \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
134 namespace scheduler {
136 /** \brief Event handler main loop
138 This member must be called at some time to enter the event handler main loop. Only while
139 this function is running any events are handled. The call will return if
140 \li a callback calls terminate()
141 \li the run queue becomes empty.
145 /** \brief Called by callbacks to terminate the main loop
147 This member may be called by any callback to tell the main loop to terminate. The main loop
148 will return to it's caller after the currently running callback returns.
152 /** \brief Return date/time of last event
154 This is the timestamp, the last event has been signaled. This is the real time at which the
155 event is delivered \e not the time it should have been delivered (in the case of timers).
157 ClockService::clock_type eventTime();
159 /** \brief Set task watchdog timeout */
160 void taskTimeout(unsigned ms);
162 /** \brief Current task watchdog timeout */
163 unsigned taskTimeout();
165 /** \brief Number of watchdog events */
166 unsigned hangCount();
168 /** \brief Restart scheduler
170 This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
171 is necessary after a fork().
172 \warning This call will \e remove all registered events from the scheduler
176 /** \brief %scheduler specific time source for Utils/Logger framework
178 This time source may be used to provide timing information for log messages within the
179 Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
183 senf::log::timeSource<senf::scheduler::LogTimeSource>();
186 Using this information reduces the number of necessary ClockService::now() calls and thus
187 the number of system calls.
189 struct LogTimeSource : public senf::log::TimeSource
191 senf::log::time_type operator()() const;
196 ///////////////////////////////hh.e////////////////////////////////////////
197 #include "Scheduler.cci"
198 //#include "Scheduler.ct"
199 //#include "Scheduler.cti"
206 // c-file-style: "senf"
207 // indent-tabs-mode: nil
208 // ispell-local-dictionary: "american"
209 // compile-command: "scons -u test"
210 // comment-column: 40