4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
6 // Stefan Bund <stefan.bund@fokus.fraunhofer.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
33 #include <boost/function.hpp>
34 #include <boost/utility.hpp>
35 #include <boost/call_traits.hpp>
37 #include "Utils/MicroTime.hh"
39 //#include "scheduler.mpp"
40 ///////////////////////////////hh.p////////////////////////////////////////
42 /** \brief SENF Project namespace */
45 /** \brief Singleton class to manage the event loop
47 This class manages a single select() type event loop. A customer of this class may register
48 any number of file descriptiors with this class and pass callback functions to be called on
49 input, output or error. This functions are specified using boost::function objects (See <a
50 href="http://www.boost.org/doc/html/function.html">Boost.Function</a>)
52 The Scheduler is based on a generic handle representation. The only information needed from
53 a handle, is the intrinsic file descriptor. Any object for which the statement
55 int fd = retrieve_filehandle(object);
57 is valid and places the relevent file descriptor into fd can be used as a Handle type. There
58 is an implementation of retrieve_filehandle(int) within the library to handle explicit file
59 descrptors. The <a href="../../../Socket/doc/html/index.html">Socket library</a> provides an
60 implementation of <tt>retrive_filehandle(FileHandle handle)</tt>. If you want to support
61 some other handle type, just define an apropriate \c retrieve_filehandle function <em>in
62 that types namespace</em>.
64 It is important to note, that for every combination of file descriptor and event, only a \e
65 single handler may be installed. Installing more handlers does not make sense. If you need
66 to distribute data to serveral interested parties, you must take care of this yourself.
68 \todo Fix EventId parameter (probably to int) to allow |-ing without casting ...
74 ///////////////////////////////////////////////////////////////////////////
77 /// \brief Types of file descriptor events */
78 enum EventId { EV_NONE=0,
79 EV_READ=1, EV_PRIO=2, EV_WRITE=4, EV_HUP=8, EV_ERR=16,
82 /** \brief Template typedef for Callback type
84 This is a template typedef (which does not exist in C++) that is, a template class whose
85 sole member is a typedef symbol defining the callback type given the handle type.
87 The Callback is any callable object taking a \c Handle and an \c EventId as argument.
89 template <class Handle>
90 struct GenericCallback {
91 typedef boost::function<void (typename boost::call_traits<Handle>::param_type,
94 /** \brief Callback type for timer events */
95 typedef boost::function<void ()> TimerCallback;
97 ///////////////////////////////////////////////////////////////////////////
98 ///\name Structors and default members
101 // private default constructor
102 // no copy constructor
103 // no copy assignment
104 // default destructor
105 // no conversion constructors
107 /** \brief Return Scheduler instance
109 This static member is used to access the singleton instance. This member is save to
110 return a correctly initialized Scheduler instance even if called at global construction
113 \implementation This static member just defines the Scheduler as a static method
114 variable. The C++ standard then provides above guaratee. The instance will be
115 initialized the first time, the code flow passes the variable declaration found in
118 static Scheduler & instance();
121 ///////////////////////////////////////////////////////////////////////////
123 template <class Handle>
124 void add(Handle const & handle,
125 typename GenericCallback<Handle>::Callback const & cb,
126 int eventMask = EV_ALL); ///< Add file handle event callback
127 /**< add() will add a callback to the Scheduler. The
128 callbeck will be called for the given type of event on
129 the given arbitrary file-descriptor or
130 handle-like object. If there already is a Callback
131 register ed for one of the events requested, the new
132 handler will replace the old one.
133 \param[in] handle file descriptor or handle providing
134 the Handle interface defined above.
135 \param[in] cb callback
136 \param[in] eventMask arbitrary combination via '|'
137 operator of EventId designators. */
138 template <class Handle>
139 void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
140 /**< remove() will remove any callback registered for any of
141 the given events on the given file descriptor or handle
143 \param[in] handle file descriptor or handle providing
144 the Handle interface defined above.
145 \param[in] eventMask arbitrary combination via '|'
146 operator of EventId designators. */
148 void timeout(unsigned long timeout, TimerCallback const & cb); ///< Add timeout event
149 /**< \param[in] timeout timeout in milliseconds
150 \param[in] cb callback to call after \a timeout
152 \todo Return some kind of handle/pointer and add
153 support to update or revoke a timeout */
155 void process(); ///< Event handler main loop
156 /**< This member must be called at some time to enter the
157 event handler main loop. Only while this function is
158 running any events are handled. The call will return
159 only, if any callback calls terminate(). */
160 void terminate(); ///< Called by callbacks to terminate the main loop
161 /**< This member may be called by any callback to tell the
162 main loop to terminate. The main loop will return to
163 it's caller after the currently running callback
169 typedef boost::function<void (EventId)> SimpleCallback;
173 void do_add(int fd, SimpleCallback const & cb, int eventMask = EV_ALL);
174 void do_remove(int fd, int eventMask = EV_ALL);
176 /** \brief Descriptor event specification
180 SimpleCallback cb_read;
181 SimpleCallback cb_prio;
182 SimpleCallback cb_write;
183 SimpleCallback cb_hup;
184 SimpleCallback cb_err;
186 int epollMask() const;
189 /** \brief Timer event specification
193 TimerSpec() : timeout(), cb() {}
194 TimerSpec(unsigned long long timeout_, TimerCallback cb_)
195 : timeout(timeout_), cb(cb_) {}
197 bool operator< (TimerSpec const & other) const
198 { return timeout > other.timeout; }
200 unsigned long long timeout;
204 typedef std::map<int,EventSpec> FdTable;
205 typedef std::priority_queue<TimerSpec> TimerQueue;
208 TimerQueue timerQueue_;
213 /** \brief Default file descriptor accessor
215 retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
216 file handle argument.
220 int retrieve_filehandle(int fd);
224 ///////////////////////////////hh.e////////////////////////////////////////
225 #include "Scheduler.cci"
226 //#include "Scheduler.ct"
227 #include "Scheduler.cti"
233 // c-file-style: "senf"