Socket/FileHandle.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   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.
  12 //
  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.
  17 //
  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.
  22
  23 /** \file
  24     \brief FileHandle public header
  25  */
  26
  27 /** \defgroup handle_group The Handle Hierarchy
  28
  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>
  36     </div>
  37     \htmlonly <img src="FhHierarchy.png" border="0" alt="FhHierarchy" usemap="#FhHierarchy"> \endhtmlonly
  38
  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.
  42
  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).
  48
  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.
  55
  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.
  59
  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.
  63  */
  64
  65 #ifndef HH_SENF_Socket_FileHandle_
  66 #define HH_SENF_Socket_FileHandle_ 1
  67
  68 // Custom includes
  69 #include <memory> // std::auto_ptr
  70 #include "../Utils/safe_bool.hh"
  71 #include "../Scheduler/ClockService.hh"
  72
  73 //#include "FileHandle.mpp"
  74 ///////////////////////////////hh.p////////////////////////////////////////
  75 #include "FileHandle.ih"
  76
  77 namespace senf {
  78
  79     /// \addtogroup handle_group
  80     /// @{
  81
  82     /** \brief Basic file handle wrapper
  83
  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).
  87
  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
  90         built-in type.
  91
  92         \attention You should mostly pass around senf::FileHandle objects by \e value and not by
  93         reference.
  94
  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.
  99
 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
 102         the socket library.
 103
 104         \section filehandle_new Writing senf::FileHandle derived classes
 105
 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
 109         senf::FileBody.
 110      */
 111     class FileHandle
 112         : public safe_bool<FileHandle>
 113     {
 114     public:
 115         ///////////////////////////////////////////////////////////////////////////
 116         // Types
 117
 118         ///////////////////////////////////////////////////////////////////////////
 119         ///\name Structors and default members
 120         ///@{
 121
 122         FileHandle();
 123         ~FileHandle();
 124
 125         // my default constructor
 126         // default copy constructor
 127         // default copy assignment
 128         // default destructor
 129
 130         // no conversion constructors
 131
 132         ///@}
 133         ///////////////////////////////////////////////////////////////////////////
 134
 135         void close();                ///< Close filehandle
 136                                      /**< \throws senf::SystemException */
 137         void terminate();            ///< Close filehandle ignoring error conditions
 138
 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
 143                                      ///< blocking state)
 144                                      /**< \param[in] timeout max time to wait, default is to wait
 145                                               forever.
 146                                           \returns \c true, if handle became readable or \c false on
 147                                               timeout. */
 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
 154                                               forever.
 155                                           \returns \c true, if handle became writable or \c false on
 156                                               timeout. */
 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
 163                                               forever.
 164                                           \returns \c true, if handle became readable for
 165                                               out-of-band data or \c false on timeout. */
 166
 167         bool blocking() const;       ///< Return current blocking state
 168         void blocking(bool status);  ///< Set blocking state
 169
 170         bool eof() const;            ///< Check EOF condition
 171                                      /**< Depending on the socket type, this might never return \p
 172                                         true.
 173
 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
 178                                         seam feasible. */
 179         bool valid() const;          ///< Check filehandle validity
 180                                      /**< Any operation besides valid() will fail on an invalid
 181                                         FileHandle */
 182
 183         bool boolean_test() const;  ///< Short for valid() && ! eof()
 184                                     /**< This is called when using a FileHandle instance in a boolean
 185                                        context
 186
 187                                        See the performance comments for the eof() member */
 188
 189         int fd() const;             ///< Return the raw FileHandle
 190
 191         static FileHandle cast_static(FileHandle handle);  /**< \internal */
 192         static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
 193
 194     protected:
 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. */
 201
 202         explicit FileHandle(FileBody::ptr body);
 203
 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
 209
 210         void fd(int fd);            ///< Set raw filehandle
 211
 212     private:
 213         FileBody::ptr body_;
 214
 215         friend class FileBody;
 216     };
 217
 218     /** \brief Adapt FileHandle to senf::scheduler
 219         \related senf::FileHandle
 220
 221         \internal
 222
 223         This function will be called by the Scheduler to retrieve the file descriptor of the
 224         FileHandle.
 225      */
 226     int retrieve_filehandle(FileHandle handle);
 227
 228     /// @}
 229
 230 }
 231
 232 ///////////////////////////////hh.e////////////////////////////////////////
 233 #include "FileHandle.cci"
 234 //#include "FileHandle.ct"
 235 //#include "FileHandle.cti"
 236 #endif
 237
 238 \f
 239 // Local Variables:
 240 // mode: c++
 241 // fill-column: 100
 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
 247 // End: