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;
54 /** \brief File descriptor event
56 The FdEvent class registers a file descriptor for read or write events.
58 There are a number of different event types supported for file descriptors. Those are
59 specified using a bit mask. Possible events are
61 \li \c EV_READ: File descriptor is readable (or at EOF)
62 \li \c EV_PRIO: There is out-of-band data available to be read on the file descriptor
63 \li \c EV_WRITE: File descriptor is writable
65 The callback will be called with one additional argument. This argument is the event mask of
66 type int. This mask will tell, which of the registered events are signaled. There are some
67 additional flags which can be set when calling the handler callback:
69 \li \c EV_HUP: The other end has closed the connection
70 \li \c EV_ERR: Transport error
72 Only a single handler may be registered for any combination of file descriptor and event
73 otherwise a DuplicateEventRegistrationException is thrown.
75 The file descriptor is specified using an arbitrary handle type which supports the \c
76 retrieve_filehandle() protocol: There must be a global function \c retrieve_filehandle
77 callable with the handle type. This function must return the file descriptor associated with
78 the handle. Implementations for integer numbers (explicit file descriptors) and senf socket
81 The FdEvent class is an implementation of the RAII idiom: The event will be automatically
82 unregistered in the FdEvent destructor. The FdEvent instance should be created within the
83 same scope or on a scope below where the callback is defined (e.g. if the callback is a
84 member function it should be defined as a class member).
87 : public detail::FIFORunner::TaskInfo,
88 public detail::FdSetBase,
89 public detail::FdManager::Event
92 //-////////////////////////////////////////////////////////////////////////
95 typedef boost::function<void (int)> Callback;
98 EV_NONE = 0 ///< No event
99 , EV_READ = detail::FdManager::EV_READ ///< fd readable (or EOF)
100 , EV_PRIO = detail::FdManager::EV_PRIO ///< OOB data available for read
101 , EV_WRITE = detail::FdManager::EV_WRITE ///< fd writable
102 , EV_HUP = detail::FdManager::EV_HUP ///< remote end closed connection
103 , EV_ERR = detail::FdManager::EV_ERR ///< transport error
104 , EV_ALL = (detail::FdManager::EV_READ
105 | detail::FdManager::EV_WRITE
106 | detail::FdManager::EV_PRIO) ///< register all events (read, prio and write)
109 //-////////////////////////////////////////////////////////////////////////
110 ///\name Structors and default members
113 template <class Handle>
114 FdEvent(std::string const & name, Callback const & cb, Handle const & handle, int events,
115 bool initiallyEnabled = true);
116 ///< Register a file descriptor event
117 /**< Registers \a cb to be called when any of the \a events
118 occurs on \a handle. If \a initiallyEnabled is set \c
119 false, the callback will not be enabled
120 automatically. Use enable() to do so.
121 \param[in] name Descriptive event name (purely
123 \param[in] cb Callback to call
124 \param[in] handle Handle (file descriptor) to watch
125 \param[in] events Events to watch for (see Events enum)
126 \param[in] initiallyEnabled if set \c false, do not
127 enable callback automatically. */
128 FdEvent(std::string const & name, Callback const & cb);
129 ///< Create a file descriptor event
130 /**< Creates a file descriptor event for callback \a cb. The
131 event is initially disabled. Use the other members to
132 set the missing parameters and enable the event.
133 \param[in] name Descriptive event name (purely
135 \param[in] cb Callback to call. This callback may \e
136 explicitly be set to \c 0 if the value cannot be
141 //-////////////////////////////////////////////////////////////////////////
143 void disable(); ///< Disable event
144 void enable(); ///< Enable event
146 FdEvent & action(Callback const & cb); ///< Change event callback
148 FdEvent & events(int events); ///< Change event mask
149 FdEvent & addEvents(int events); ///< Add additional events to event mask
150 FdEvent & removeEvents(int events); ///< Remove events from event mask
151 int events(); ///< Current event mask
153 template <class Handle>
154 FdEvent & handle(Handle const & handle); ///< Change event file handle
156 struct DuplicateEventRegistrationException : public Exception
157 { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
162 virtual void signal(int events);
163 virtual void v_run();
164 virtual char const * v_type() const;
165 virtual std::string v_info() const;
173 friend struct detail::FdSetCompare;
174 friend class detail::FdDispatcher;
175 friend class detail::FileDispatcher;
178 /** \brief Get file descriptor from handle object
180 This function will query the \a handle for it's file descriptor. The real implementation
181 must be provided by a freestanding function \c retrieve_filehandle(Handle const & h) within
182 the namespace of \a Handle.
184 template <class Handle>
185 int get_descriptor(Handle const & handle);
188 //-/////////////////////////////////////////////////////////////////////////////////////////////////
189 #include "FdEvent.cci"
190 #include "FdEvent.ct"
191 #include "FdEvent.cti"
198 // comment-column: 40
199 // c-file-style: "senf"
200 // indent-tabs-mode: nil
201 // ispell-local-dictionary: "american"
202 // compile-command: "scons -u test"