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"
32 #include "FdDispatcher.hh"
33 #include "TimerDispatcher.hh"
34 #include "SignalDispatcher.hh"
35 #include "FileDispatcher.hh"
36 #include "../Utils/Logger/SenfLog.hh"
38 //#include "scheduler.mpp"
39 ///////////////////////////////hh.p////////////////////////////////////////
41 /** \brief SENF Project namespace */
44 /** \brief Visible scheduler interface
46 The %scheduler singleton manages access to the %scheduler library. It provides access to
47 several event dispatchers:
48 \li File descriptor notifications
52 The %scheduler is entered by calling it's process() member. This call will continue to run as
53 long as there is something to do, or until one of the handlers calls terminate(). The
54 %scheduler has 'something to do' as long as there is any file descriptor or timeout active.
56 The %scheduler only provides low level primitive scheduling capability. Additional helpers
57 are defined on top of this functionality (e.g. ReadHelper or WriteHelper or the interval
61 \section sched_handlers Specifying handlers
63 All handlers are passed as generic <a
64 href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows
65 to pass any callable as a handler. Depending on the type of handler, some additional
66 arguments may be passed to the handler by the %scheduler.
68 If you need to pass additional information to your handler, use <a
69 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
71 // Handle callback function
72 void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
73 // Pass 'handle' as additional first argument to callback()
74 Scheduler::instance().add(handle, boost::bind(&callback, handle, _1), EV_READ)
76 void timeout( int n) {..}
77 // Call timeout() handler with argument 'n'
78 Scheduler::instance().timeout(boost::bind(&timeout, n))
81 To use member-functions as callbacks, use either <a
82 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
84 // e.g. in Foo::Foo() constructor:
85 Scheduler::instance().add(handle_, senf::membind(&Foo::callback, this)), EV_READ)
88 The handler can also be identified by an arbitrary, user specified name. This name is used
89 in error messages to identify the failing handler.
92 \section sched_fd Registering file descriptors
94 File descriptors are managed using add() or remove()
96 Scheduler::instance().add(handle, &callback, EV_ALL);
97 Scheduler::instance().remove(handle);
100 The callback will be called with one additional argument. This argument is the event mask of
101 type EventId. This mask will tell, which of the registered events are signaled. The
102 additional flags EV_HUP or EV_ERR (on hangup or error condition) may be set additionally.
104 Only a single handler may be registered for any combination of file descriptor and event
105 (registering multiple callbacks for a single fd and event does not make sense).
107 The %scheduler will accept any object as \a handle argument as long as retrieve_filehandle()
108 may be called on that object
110 int fd = retrieve_filehandle(handle);
112 to fetch the file handle given some abstract handle type. retrieve_filehandle() will be
113 found using ADL depending on the argument namespace. A default implementation is provided
114 for \c int arguments (file descriptors)
117 \section sched_timers Registering timers
119 The %scheduler has very simple timer support. There is only one type of timer: A single-shot
120 deadline timer. More complex timers are built based on this. Timers are managed using
121 timeout() and cancelTimeout()
123 int id = Scheduler::instance().timeout(Scheduler::instance().eventTime() + ClockService::milliseconds(100),
125 Scheduler::instance().cancelTimeout(id);
127 Timing is based on the ClockService, which provides a high resolution and strictly
128 monotonous time source which again is based on POSIX timers. Registering a timeout will fire
129 the callback when the target time is reached. The timer may be canceled by passing the
130 returned \a id to cancelTimeout().
133 \section sched_signals Registering POSIX/UNIX signals
135 The %scheduler also incorporates standard POSIX/UNIX signals. Signals registered with the
136 %scheduler will be handled \e synchronously within the event loop.
138 Scheduler::instance().registerSignal(SIGUSR1, &callback);
139 Scheduler::instance().unregisterSignal(SIGUSR1);
141 When registering a signal with the %scheduler, that signal will automatically be blocked so
142 it can be handled within the %scheduler.
144 A registered signal does \e not count as 'something to do'. It is therefore not possible to
145 wait for signals \e only.
147 \todo Change the Scheduler API to use RAII. Additionally, this will remove all dynamic
148 memory allocations from the scheduler.
149 \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
157 SENF_LOG_CLASS_AREA();
159 ///////////////////////////////////////////////////////////////////////////
162 /** \brief Types of file descriptor events
164 These events are grouped into to classes:
165 \li Ordinary file descriptor events for which handlers may be registered. These are
166 EV_READ, EV_PRIO and EV_WRITE. EV_ALL is a combination of these three.
167 \li Error flags. These additional flags may be passed to a handler to pass an error
168 condition to the handler.
171 EV_NONE = 0 /**< No event */
172 , EV_READ = scheduler::FdManager::EV_READ /**< File descriptor is readable */
173 , EV_PRIO = scheduler::FdManager::EV_PRIO /**< File descriptor has OOB data */
174 , EV_WRITE = scheduler::FdManager::EV_WRITE /**< File descriptor is writable */
175 , EV_ALL = scheduler::FdManager::EV_READ
176 | scheduler::FdManager::EV_PRIO
177 | scheduler::FdManager::EV_WRITE /**< Used to register all events at once
179 , EV_HUP = scheduler::FdManager::EV_HUP /**< Hangup condition on file handle */
180 , EV_ERR = scheduler::FdManager::EV_ERR /**< Error condition on file handle */
183 /** \brief Callback type for file descriptor events */
184 typedef boost::function<void (int)> FdCallback;
186 /** \brief Callback type for timer events */
187 typedef boost::function<void ()> SimpleCallback;
189 /** \brief Callback type for signal events */
190 typedef boost::function<void (siginfo_t const &)> SignalCallback;
192 /** \brief Timer id type */
193 typedef scheduler::TimerDispatcher::timer_id timer_id;
195 ///////////////////////////////////////////////////////////////////////////
196 ///\name Structors and default members
199 // private default constructor
200 // no copy constructor
201 // no copy assignment
202 // default destructor
203 // no conversion constructors
205 /** \brief Return %scheduler instance
207 This static member is used to access the singleton instance. This member is save to
208 return a correctly initialized %scheduler instance even if called at global construction
211 static Scheduler & instance();
214 ///////////////////////////////////////////////////////////////////////////
216 ///\name File Descriptors
219 template <class Handle>
220 void add(std::string const & name, Handle const & handle, FdCallback const & cb,
221 int eventMask = EV_ALL); ///< Add file handle event callback
222 /**< add() will add a callback to the %scheduler. The
223 callback will be called for the given type of event on
224 the given arbitrary file-descriptor or
225 handle-like object. If there already is a Callback
226 registered for one of the events requested, the new
227 handler will replace the old one.
228 \param[in] name descriptive name to identify the
230 \param[in] handle file descriptor or handle providing
231 the Handle interface defined above.
232 \param[in] cb callback
233 \param[in] eventMask arbitrary combination via '|'
234 operator of \ref senf::Scheduler::EventId "EventId"
237 template <class Handle>
238 void add(Handle const & handle, FdCallback const & cb,
239 int eventMask = EV_ALL); ///< Add file handle event callback
243 template <class Handle>
244 void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
245 /**< remove() will remove any callback registered for any of
246 the given events on the given file descriptor or handle
248 \param[in] handle file descriptor or handle providing
249 the Handle interface defined above.
250 \param[in] eventMask arbitrary combination via '|'
251 operator of \ref senf::Scheduler::EventId "EventId"
259 timer_id timeout(std::string const & name, ClockService::clock_type timeout,
260 SimpleCallback const & cb);
261 ///< Add timeout event
262 /**< \returns timer id
263 \param[in] name descriptive name to identify the
265 \param[in] timeout timeout in nanoseconds
266 \param[in] cb callback to call after \a timeout
269 timer_id timeout(ClockService::clock_type timeout, SimpleCallback const & cb);
270 ///< Add timeout event
271 /**< \see timeout() */
273 void cancelTimeout(timer_id id); ///< Cancel timeout \a id
276 ClockService::clock_type timeoutEarly() const;
277 void timeoutEarly(ClockService::clock_type v);
279 ClockService::clock_type timeoutAdjust() const;
280 void timeoutAdjust(ClockService::clock_type v);
285 ///\name Signal handlers
288 void registerSignal(unsigned signal, SignalCallback const & cb);
289 ///< Add signal handler
290 /**< \param[in] signal signal number to register handler for
291 \param[in] cb callback to call whenever \a signal is
294 void unregisterSignal(unsigned signal);
295 ///< Remove signal handler for \a signal
299 void process(); ///< Event handler main loop
300 /**< This member must be called at some time to enter the
301 event handler main loop. Only while this function is
302 running any events are handled. The call will return
303 only, if any callback calls terminate(). */
305 void terminate(); ///< Called by callbacks to terminate the main loop
306 /**< This member may be called by any callback to tell the
307 main loop to terminate. The main loop will return to
308 it's caller after the currently running callback
311 ClockService::clock_type eventTime() const; ///< Return date/time of last event
312 /**< This is the timestamp, the last event has been
313 signaled. This is the real time at which the event is
314 delivered \e not the time it should have been delivered
315 (in the case of timers). */
317 unsigned hangCount() const;
324 void do_add(int fd, FdCallback const & cb, int eventMask = EV_ALL);
325 void do_add(std::string const & name, int fd, FdCallback const & cb,
326 int eventMask = EV_ALL);
327 void do_remove(int fd, int eventMask);
330 scheduler::FdManager manager_;
331 scheduler::FIFORunner runner_;
333 scheduler::FdDispatcher fdDispatcher_;
334 scheduler::TimerDispatcher timerDispatcher_;
335 scheduler::SignalDispatcher signalDispatcher_;
336 scheduler::FileDispatcher fileDispatcher_;
339 /** \brief Default file descriptor accessor
341 retrieve_filehandle() provides the %scheduler with support for explicit file descriptors as
342 file handle argument.
346 int retrieve_filehandle(int fd);
348 /** \brief %scheduler specific time source for Utils/Logger framework
350 This time source may be used to provide timing information for log messages within the
351 Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
354 struct SchedulerLogTimeSource : public senf::log::TimeSource
356 senf::log::time_type operator()() const;
361 ///////////////////////////////hh.e////////////////////////////////////////
362 #include "Scheduler.cci"
363 //#include "Scheduler.ct"
364 #include "Scheduler.cti"
371 // c-file-style: "senf"
372 // indent-tabs-mode: nil
373 // ispell-local-dictionary: "american"
374 // compile-command: "scons -u test"
375 // comment-column: 40