4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at
9 // http://senf.berlios.de/license.html
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
15 // Software distributed under the License is distributed on an "AS IS" basis,
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17 // for the specific language governing rights and limitations under the License.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
23 // All Rights Reserved.
26 // Stefan Bund <g0dil@berlios.de>
29 \brief FdDispatcher public header */
31 #ifndef HH_SENF_Scheduler_FdEvent_
32 #define HH_SENF_Scheduler_FdEvent_ 1
35 #include <senf/boost_intrusive/iset_hook.hpp>
36 #include <senf/Utils/Exception.hh>
37 #include "FdManager.hh"
38 #include "FIFORunner.hh"
40 //#include "FdEvent.mpp"
41 //-/////////////////////////////////////////////////////////////////////////////////////////////////
48 typedef boost::intrusive::iset_base_hook<FdSetTag> FdSetBase;
55 /** \brief File descriptor event
57 The FdEvent class registers a file descriptor for read or write events.
59 There are a number of different event types supported for file descriptors. Those are
60 specified using a bit mask. Possible events are
62 \li \c EV_READ: File descriptor is readable (or at EOF)
63 \li \c EV_PRIO: There is out-of-band data available to be read on the file descriptor
64 \li \c EV_WRITE: File descriptor is writable
66 The callback will be called with one additional argument. This argument is the event mask of
67 type int. This mask will tell, which of the registered events are signaled. There are some
68 additional flags which can be set when calling the handler callback:
70 \li \c EV_HUP: The other end has closed the connection
71 \li \c EV_ERR: Transport error
73 Only a single handler may be registered for any combination of file descriptor and event
74 otherwise a DuplicateEventRegistrationException is thrown.
76 The file descriptor is specified using an arbitrary handle type which supports the \c
77 retrieve_filehandle() protocol: There must be a global function \c retrieve_filehandle
78 callable with the handle type. This function must return the file descriptor associated with
79 the handle. Implementations for integer numbers (explicit file descriptors) and senf socket
82 The FdEvent class is an implementation of the RAII idiom: The event will be automatically
83 unregistered in the FdEvent destructor. The FdEvent instance should be created within the
84 same scope or on a scope below where the callback is defined (e.g. if the callback is a
85 member function it should be defined as a class member).
88 : public detail::FIFORunner::TaskInfo,
89 public detail::FdSetBase,
90 public detail::FdManager::Event
93 //-////////////////////////////////////////////////////////////////////////
96 typedef boost::function<void (int)> Callback;
99 EV_NONE = 0 ///< No event
100 , EV_READ = detail::FdManager::EV_READ ///< fd readable (or EOF)
101 , EV_PRIO = detail::FdManager::EV_PRIO ///< OOB data available for read
102 , EV_WRITE = detail::FdManager::EV_WRITE ///< fd writable
103 , EV_HUP = detail::FdManager::EV_HUP ///< remote end closed connection
104 , EV_ERR = detail::FdManager::EV_ERR ///< transport error
105 , EV_ALL = (detail::FdManager::EV_READ
106 | detail::FdManager::EV_WRITE
107 | detail::FdManager::EV_PRIO) ///< register all events (read, prio and write)
110 //-////////////////////////////////////////////////////////////////////////
111 ///\name Structors and default members
114 template <class Handle>
115 FdEvent(std::string const & name, Callback const & cb, Handle const & handle, int events,
116 bool initiallyEnabled = true);
117 ///< Register a file descriptor event
118 /**< Registers \a cb to be called when any of the \a events
119 occurs on \a handle. If \a initiallyEnabled is set \c
120 false, the callback will not be enabled
121 automatically. Use enable() to do so.
122 \param[in] name Descriptive event name (purely
124 \param[in] cb Callback to call
125 \param[in] handle Handle (file descriptor) to watch
126 \param[in] events Events to watch for (see Events enum)
127 \param[in] initiallyEnabled if set \c false, do not
128 enable callback automatically. */
129 FdEvent(std::string const & name, Callback const & cb);
130 ///< Create a file descriptor event
131 /**< Creates a file descriptor event for callback \a cb. The
132 event is initially disabled. Use the other members to
133 set the missing parameters and enable the event.
134 \param[in] name Descriptive event name (purely
136 \param[in] cb Callback to call. This callback may \e
137 explicitly be set to \c 0 if the value cannot be
142 //-////////////////////////////////////////////////////////////////////////
144 void disable(); ///< Disable event
145 void enable(); ///< Enable event
147 FdEvent & action(Callback const & cb); ///< Change event callback
149 FdEvent & events(int events); ///< Change event mask
150 FdEvent & addEvents(int events); ///< Add additional events to event mask
151 FdEvent & removeEvents(int events); ///< Remove events from event mask
152 int events(); ///< Current event mask
154 template <class Handle>
155 FdEvent & handle(Handle const & handle); ///< Change event file handle
157 struct DuplicateEventRegistrationException : public Exception
158 { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
163 virtual void signal(int events);
164 virtual void v_run();
165 virtual char const * v_type() const;
166 virtual std::string v_info() const;
174 friend class detail::FdSetCompare;
175 friend class detail::FindFd;
176 friend class detail::FdDispatcher;
177 friend class detail::FileDispatcher;
180 /** \brief Get file descriptor from handle object
182 This function will query the \a handle for it's file descriptor. The real implementation
183 must be provided by a freestanding function \c retrieve_filehandle(Handle const & h) within
184 the namespace of \a Handle.
186 template <class Handle>
187 int get_descriptor(Handle const & handle);
190 //-/////////////////////////////////////////////////////////////////////////////////////////////////
191 #include "FdEvent.cci"
192 #include "FdEvent.ct"
193 #include "FdEvent.cti"
200 // comment-column: 40
201 // c-file-style: "senf"
202 // indent-tabs-mode: nil
203 // ispell-local-dictionary: "american"
204 // compile-command: "scons -u test"