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 FileHandle public header
27 /** \defgroup handle_group The Handle Hierarchy
29 <div class="diamap" name="FhHierarchy">
30 <span coords="233,47,438,89">\ref SocketHandle</span>
31 <span coords="32,126,281,168">\ref ClientSocketHandle</span>
32 <span coords="0,187,326,229">\ref ProtocolClientSocketHandle</span>
33 <span coords="350,187,684,229">\ref ProtocolServerSocketHandle</span>
34 <span coords="243,0,343,28">\ref FileHandle</span>
35 <span coords="382,126,638,168">\ref ServerSocketHandle</span>
37 \htmlonly <img src="FhHierarchy.png" border="0" alt="FhHierarchy" usemap="#FhHierarchy"> \endhtmlonly
39 The senf::FileHandle class is the base of a hierarchy of socket handle classes (realized as
40 templates). These classes provide an interface to the complete socket API. While going down the
41 inheritance hierarchy, the interface will be more and more complete.
43 The most complete interface is provided by senf::ProtocolClientSocketHandle and
44 senf::ProtocolServerSocketHandle. The template Arguments specifies the Protocol class of the
45 underlying socket type. These are the \e only classes having public constructors and are
46 therefore the only classes, which may be created by the library user. You will normally use
47 these classes by naming a specific socket typedef (e.g. senf::TCPv4ClientSocketHandle).
49 However, to aid writing flexible and generic code, the socket library provides the
50 senf::ClientSocketHandle and senf::ServerSocketHandle class templates. These templates implement
51 a family of closely related classes based on the specification of the socket policy. This policy
52 specification may be \e incomplete (see below). Instances of
53 senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned and converted to different
54 ClientSocketHandle/ServerSocketHandle types as long as the policy specifications are compatible.
56 \attention It is very important, to (almost) always pass the socket handle <em>by
57 value</em>. The socket handle is a very lightweight class and designed to be used like an
58 ordinary built-in type. This is very important in combination with the policy interface.
60 \note The FileHandle hierarchy below the SocketHandle template is \e not meant to be user
61 extensible. To add new socket types, you should introduce new protocol and/or policy classes,
62 the SocketHandle classes should not be changed.
65 #ifndef HH_SENF_Socket_FileHandle_
66 #define HH_SENF_Socket_FileHandle_ 1
69 #include <memory> // std::auto_ptr
70 #include <senf/Utils/safe_bool.hh>
71 #include <senf/Scheduler/ClockService.hh>
73 //#include "FileHandle.mpp"
74 ///////////////////////////////hh.p////////////////////////////////////////
75 #include "FileHandle.ih"
79 /// \addtogroup handle_group
82 /** \brief Basic file handle wrapper
84 senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
85 minimal interface which does \e not include reading or writing (since some filehandles are
86 not readable or writable or only using special function calls like sendto).
88 The FileHandle class provides handle/body handling and uses automatic reference
89 counting. The senf::FileHandle instance is very lightweight and should be used like a
92 \attention You should mostly pass around senf::FileHandle objects by \e value and not by
95 The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
96 wrap any provider or consumer into a filehandle like interface using this wrapper. The
97 wrapper will forward some calls directly to the underlying API without relying on virtual
98 methods. This allows important members to be inlined.
100 It is not possible to use the senf::FileHandle class directly since it does not have any
101 public constructor. The FileHandle class is however the baseclass of all handle classes of
104 \section filehandle_new Writing senf::FileHandle derived classes
106 To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
107 will have to call the protected FileHandle constructor passing a new senf::FileBody
108 instance. This instance may either be a simple senf::FileBody or a class derived from
112 : public safe_bool<FileHandle>
115 ///////////////////////////////////////////////////////////////////////////
118 ///////////////////////////////////////////////////////////////////////////
119 ///\name Structors and default members
125 // my default constructor
126 // default copy constructor
127 // default copy assignment
128 // default destructor
130 // no conversion constructors
133 ///////////////////////////////////////////////////////////////////////////
135 void close(); ///< Close filehandle
136 /**< \throws senf::SystemException */
137 void terminate(); ///< Close filehandle ignoring error conditions
139 bool readable() const; ///< Check, whether a read on the handle would not block
140 ///< (ignoring blocking state)
141 bool waitReadable(senf::ClockService::clock_type timeout = -1) const;
142 ///< Wait, until read on the handle would not block (ignoring
144 /**< \param[in] timeout max time to wait, default is to wait
146 \returns \c true, if handle became readable or \c false on
148 bool writeable() const; ///< Check, whether a write on the handle would not block
149 ///< (ignoring blocking state)
150 bool waitWriteable(senf::ClockService::clock_type timeout = -1) const;
151 ///< Wait, until a write on the handle would not block
152 ///< (ignoring blocking state)
153 /**< \param[in] timeout max time to wait, default is to wait
155 \returns \c true, if handle became writable or \c false on
157 bool oobReadable() const; ///< Check, whether a read of prioritized data on the handle
158 ///< would not block (ignoring blocking state)
159 bool waitOOBReadable(senf::ClockService::clock_type timeout = -1) const;
160 ///< Wait, until read of prioritized data on the handle does
161 ///< not block (ignoring blocking state)
162 /**< \param[in] timeout max time to wait, default is to wait
164 \returns \c true, if handle became readable for
165 out-of-band data or \c false on timeout. */
167 bool blocking() const; ///< Return current blocking state
168 void blocking(bool status); ///< Set blocking state
170 bool eof() const; ///< Check EOF condition
171 /**< Depending on the socket type, this might never return \p
174 This member is somewhat problematic performance wise if
175 called frequently since it relies on virtual
176 functions. However, since the eof() handling is extremely
177 protocol dependent, a policy based implementation does not
179 bool valid() const; ///< Check filehandle validity
180 /**< Any operation besides valid() will fail on an invalid
183 bool boolean_test() const; ///< Short for valid() && ! eof()
184 /**< This is called when using a FileHandle instance in a boolean
187 See the performance comments for the eof() member */
189 int fd() const; ///< Return the raw FileHandle
191 static FileHandle cast_static(FileHandle handle); /**< \internal */
192 static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
195 explicit FileHandle(std::auto_ptr<FileBody> body);
196 ///< create new FileHandle instance
197 /**< The FileHandle instance will take over ownership over the
198 given FileBody instance which must have been allocated using
199 \c new. To configure the FileHandle behavior, A derived class
200 may provide any class derived from FileBody here. */
202 explicit FileHandle(FileBody::ptr body);
204 FileBody & body(); ///< Access body
205 FileBody const & body() const; ///< Access body in const context
206 static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
207 static FileBody const & body(FileHandle const & handle); ///< Access body of another
208 ///< FileHandle instance in const context
210 void fd(int fd); ///< Set raw filehandle
215 friend class FileBody;
218 /** \brief Adapt FileHandle to senf::scheduler
219 \related senf::FileHandle
223 This function will be called by the Scheduler to retrieve the file descriptor of the
226 int retrieve_filehandle(FileHandle handle);
232 ///////////////////////////////hh.e////////////////////////////////////////
233 #include "FileHandle.cci"
234 //#include "FileHandle.ct"
235 //#include "FileHandle.cti"
242 // c-file-style: "senf"
243 // indent-tabs-mode: nil
244 // ispell-local-dictionary: "american"
245 // compile-command: "scons -u test"
246 // comment-column: 40