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.
52 \section sched_handlers Specifying handlers
54 All handlers are specified as generic <a
55 href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows to
56 pass any callable as a handler. Depending on the type of handler, some additional arguments may
57 be passed to the handler by the %scheduler.
59 If you need to pass additional information to your handler, use <a
60 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
62 // Handle callback function
63 void callback(UDPv4ClientSocketHandle handle, senf::Scheduler::EventId event) {..}
64 // Pass 'handle' as additional first argument to callback()
65 senf::scheduler::FdEvent event ("name", boost::bind(&callback, handle, _1),
66 handle, senf::scheduler::FdEvent::EV_READ);
68 void timeout( int n) {..}
69 // Call timeout() handler with argument 'n'
70 senf::scheduler::TimerEvent timer ("name", boost::bind(&timeout, n),
71 senf::ClockService::now() + senf::ClockService::seconds(1));
74 To use member-functions as callbacks, use either <a
75 href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> or senf::membind()
77 // e.g. in Foo::Foo() constructor:
80 readevent_ ("Foo read", senf::membind(&Foo::callback, this),
81 handle_, senf::scheduler::FdEvent::EV_READ)
85 The handler is identified by an arbitrary, user specified name. This name is used in error
86 messages to identify the failing handler.
89 \section sched_fd Registering events
91 Events are registered by allocating an instance of the corresponding event class:
93 \li senf::scheduler::FdEvent for file descriptor events
94 \li senf::scheduler::TimerEvent for single-shot deadline timer events
95 \li senf::scheduler::SignalEvent for UNIX signal events
97 The destructor of each of these classes will ensure, that the event will be properly
98 unregistered. The registration can be enabled, disabled or changed using appropriate
99 members. See the event class for details on a specific type of event.
101 \todo Fix the file support to use threads (?) fork (?) and a pipe so it works reliably even
104 namespace scheduler {
106 /** \brief Event handler main loop
108 This member must be called at some time to enter the event handler main loop. Only while
109 this function is running any events are handled. The call will return if
110 \li a callback calls terminate()
111 \li the run queue becomes empty.
115 /** \brief Called by callbacks to terminate the main loop
117 This member may be called by any callback to tell the main loop to terminate. The main loop
118 will return to it's caller after the currently running callback returns.
122 /** \brief Return date/time of last event
124 This is the timestamp, the last event has been signaled. This is the real time at which the
125 event is delivered \e not the time it should have been delivered (in the case of timers).
127 ClockService::clock_type eventTime();
129 /** \brief Set task watchdog timeout */
130 void taskTimeout(unsigned ms);
132 /** \brief Current task watchdog timeout */
133 unsigned taskTimeout();
135 /** \brief Number of watchdog events */
136 unsigned hangCount();
138 /** \brief Restart scheduler
140 This call will restart all scheduler dispatchers (timers, signals, file descriptors). This
141 is necessary after a fork().
142 \warning This call will \e remove all registered events from the scheduler
146 /** \brief %scheduler specific time source for Utils/Logger framework
148 This time source may be used to provide timing information for log messages within the
149 Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
152 Using this information reduces the number of necessary ClockService::now() calls and thus
153 the number of system calls.
155 struct LogTimeSource : public senf::log::TimeSource
157 senf::log::time_type operator()() const;
162 ///////////////////////////////hh.e////////////////////////////////////////
163 #include "Scheduler.cci"
164 //#include "Scheduler.ct"
165 //#include "Scheduler.cti"
172 // c-file-style: "senf"
173 // indent-tabs-mode: nil
174 // ispell-local-dictionary: "american"
175 // compile-command: "scons -u test"
176 // comment-column: 40