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 FdDispatcher public header */
26 #ifndef HH_SENF_Scheduler_FdEvent_
27 #define HH_SENF_Scheduler_FdEvent_ 1
30 #include <boost/intrusive/iset_hook.hpp>
31 #include "../Utils/Exception.hh"
32 #include "FdManager.hh"
33 #include "FIFORunner.hh"
35 //#include "FdEvent.mpp"
36 ///////////////////////////////hh.p////////////////////////////////////////
43 typedef boost::intrusive::iset_base_hook<FdSetTag> FdSetBase;
50 /** \brief File descriptor event
52 The FdEvent class registers a file descriptor for read or write events.
54 There are a number of different event types supported for file descriptors. Those are
55 specified using a bit mask. Possible events are
57 \li \c EV_READ: File descriptor is readable (or at EOF)
58 \li \c EV_PRIO: There is out-of-band data available to be read on the file descriptor
59 \li \c EV_WRITE: File descriptor is writable
61 The callback will be called with one additional argument. This argument is the event mask of
62 type int. This mask will tell, which of the registered events are signaled. There are some
63 additional flags which can be set when calling the handler callback:
65 \li \c EV_HUP: The other end has closed the connection
66 \li \c EV_ERR: Transport error
68 Only a single handler may be registered for any combination of file descriptor and event
69 otherwise a DuplicateEventRegistrationException is thrown.
71 The file descriptor is specified using an arbitrary handle type which supports the \c
72 retrieve_filehandle() protocol: There must be a global function \c retrieve_filehandle
73 callable with the handle type. This function must return the file descriptor associated with
74 the handle. Implementations for integer numbers (explicit file descriptors) and senf socket
77 The FdEvent class is an implementation of the RAII idiom: The event will be automatically
78 unregistered in the FdEvent destructor. The FdEvent instance should be created within the
79 same scope or on a scope below where the callback is defined (e.g. if the callback is a
80 member function it should be defined as a class member).
83 : public detail::FIFORunner::TaskInfo,
84 public detail::FdSetBase,
85 public detail::FdManager::Event
88 ///////////////////////////////////////////////////////////////////////////
91 typedef boost::function<void (int)> Callback;
94 EV_NONE = 0 ///< No event
95 , EV_READ = detail::FdManager::EV_READ ///< fd readable (or EOF)
96 , EV_PRIO = detail::FdManager::EV_PRIO ///< OOB data available for read
97 , EV_WRITE = detail::FdManager::EV_WRITE ///< fd writable
98 , EV_HUP = detail::FdManager::EV_HUP ///< remote end closed connection
99 , EV_ERR = detail::FdManager::EV_ERR ///< transport error
100 , EV_ALL = (detail::FdManager::EV_READ
101 | detail::FdManager::EV_WRITE
102 | detail::FdManager::EV_PRIO) ///< register all events (read, prio and write)
105 ///////////////////////////////////////////////////////////////////////////
106 ///\name Structors and default members
109 template <class Handle>
110 FdEvent(std::string const & name, Callback const & cb, Handle const & handle, int events,
111 bool initiallyEnabled = true);
112 ///< Register a file descriptor event
113 /**< Registers \a cb to be called when any of the \a events
114 occurs on \a handle. If \a initiallyEnabled is set \c
115 false, the callback will not be enabled
116 automatically. Use enable() to do so.
117 \param[in] name Descriptive event name (purely
119 \param[in] cb Callback to call
120 \param[in] handle Handle (file descriptor) to watch
121 \param[in] events Events to watch for (see Events enum)
122 \param[in] initiallyEnabled if set \c false, do not
123 enable callback automatically. */
124 FdEvent(std::string const & name, Callback const & cb);
125 ///< Create a file descriptor event
126 /**< Creates a file descriptor event for callback \a cb. The
127 event is initially disabled. Use the other members to
128 set the missing parameters and enable the event.
129 \param[in] name Descriptive event name (purely
131 \param[in] cb Callback to call. This callback may \e
132 explicitly be set to \c 0 if the value cannot be
137 ///////////////////////////////////////////////////////////////////////////
139 void disable(); ///< Disable event
140 void enable(); ///< Enable event
142 FdEvent & action(Callback const & cb); ///< Change event callback
144 FdEvent & events(int events); ///< Change event mask
145 FdEvent & addEvents(int events); ///< Add additional events to event mask
146 FdEvent & removeEvents(int events); ///< Remove events from event mask
147 int events(); ///< Current event mask
149 template <class Handle>
150 FdEvent & handle(Handle const & handle); ///< Change event file handle
152 struct DuplicateEventRegistrationException : public Exception
153 { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
158 virtual void signal(int events);
159 virtual void v_run();
160 virtual char const * v_type() const;
161 virtual std::string v_info() const;
169 friend class detail::FdSetCompare;
170 friend class detail::FindFd;
171 friend class detail::FdDispatcher;
172 friend class detail::FileDispatcher;
175 /** \brief Get file descriptor from handle object
177 This function will query the \a handle for it's file descriptor. The real implementation
178 must be provided by a freestanding function \c retrieve_filehandle(Handle const & h) within
179 the namespace of \a Handle.
181 template <class Handle>
182 int get_descriptor(Handle const & handle);
185 ///////////////////////////////hh.e////////////////////////////////////////
186 #include "FdEvent.cci"
187 #include "FdEvent.ct"
188 #include "FdEvent.cti"
195 // comment-column: 40
196 // c-file-style: "senf"
197 // indent-tabs-mode: nil
198 // ispell-local-dictionary: "american"
199 // compile-command: "scons -u test"