Socket/FileHandle.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <stefan.bund@fokus.fraunhofer.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     \image html FhHierarchy.png
  30
  31     The senf::FileHandle class is the base of a hierarchy of socket handle classes (realized as
  32     templates). These classes provide an interface to the complete socket API. While going down the
  33     inheritance hierarchy, the interface will be more and more complete.
  34
  35     The most complete interface is provided by senf::ProtocolClientSocketHandle and
  36     senf::ProtocolServerSocketHandle. The template Arguments specifies the Protocol class of the
  37     underlying socket type. These are the \e only classes having public constructors and are
  38     therefore the only classes, which may be created by the library user. You will normally use
  39     these classes by naming a specific socket typedef (e.g. senf::TCPv4ClientSocketHandle).
  40
  41     However, to aid writing flexible and generic code, the socket library provides the
  42     senf::ClientSocketHandle and senf::ServerSocketHandle class templates. These templates implement
  43     a family of closely related classes based on the specification of the socket policy. This policy
  44     specification may be \e incomplete (see below). Instances of
  45     senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned and converted to different
  46     ClientSocketHandle/ServerSocketHandle types as long as the policy specifications are compatible.
  47
  48     \attention It is very important, to (almost) always pass the socket handle <em>by
  49     value</em>. The socket handle is a very lightweight class and designed to be used like an
  50     ordinary built-in type. This is very important in combination with the policy interface.
  51
  52     \note The FileHandle hierarchy below the SocketHandle template is \e not meant to be user
  53     extensible. To add new socket types, you should introduce new protocol and/or policy classes,
  54     the SocketHandle classes should not be changed.
  55  */
  56
  57 #ifndef HH_FileHandle_
  58 #define HH_FileHandle_ 1
  59
  60 // Custom includes
  61 #include <memory> // std::auto_ptr
  62 #include "../Utils/safe_bool.hh"
  63
  64 //#include "FileHandle.mpp"
  65 ///////////////////////////////hh.p////////////////////////////////////////
  66 #include "FileHandle.ih"
  67
  68 namespace senf {
  69
  70     /// \addtogroup handle_group
  71     /// @{
  72
  73     /** \brief Basic file handle wrapper
  74
  75         senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
  76         minimal interface which does \e not include reading or writing (since some filehandles are
  77         not readable or writable or only using special function calls like sendto).
  78
  79         The FileHandle class provides handle/body handling and uses automatic reference
  80         counting. The senf::FileHandle instance is very lightweight and should be used like a
  81         built-in type.
  82
  83         \attention You should mostly pass around senf::FileHandle objects by \e value and not by
  84         reference.
  85
  86         The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
  87         wrap any provider or consumer into a filehandle like interface using this wrapper. The
  88         wrapper will forward some calls directly to the underlying API without relying on virtual
  89         methods. This allows important members to be inlined.
  90
  91         It is not possible to use the senf::FileHandle class directly since it does not have any
  92         public constructor. The FileHandle class is however the baseclass of all handle classes of
  93         the socket library.
  94
  95         \section filehandle_new Writing senf::FileHandle derived classes
  96
  97         To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
  98         will have to call the protected FileHandle constructor passing a new senf::FileBody
  99         instance. This instance may either be a simple senf::FileBody or a class derived from
 100         senf::FileBody.
 101      */
 102     class FileHandle
 103         : public safe_bool<FileHandle>
 104     {
 105     public:
 106         ///////////////////////////////////////////////////////////////////////////
 107         // Types
 108
 109         ///////////////////////////////////////////////////////////////////////////
 110         ///\name Structors and default members
 111         ///@{
 112
 113         FileHandle();
 114
 115         // my default constructor
 116         // default copy constructor
 117         // default copy assignment
 118         // default destructor
 119
 120         // no conversion constructors
 121
 122         ///@}
 123         ///////////////////////////////////////////////////////////////////////////
 124
 125         void close();                ///< Close filehandle
 126                                      /**< \throws senf::SystemException */
 127         void terminate();            ///< Close filehandle ignoring error conditions
 128
 129         bool readable() const;       ///< Check, whether a read on the handle would not block
 130                                      ///< (ignoring blocking state)
 131         void waitReadable() const;   ///< Wait, until read on the handle would not block (ignoring
 132                                      ///< blocking state)
 133         bool writeable() const;      ///< Check, whether a write on the handle would not block
 134                                      ///< (ignoring blocking state)
 135         void waitWriteable() const;  ///< Wait, until a write on the handle would not block
 136                                      ///< (ignoring blocking state)
 137
 138         bool blocking() const;       ///< Return current blocking state
 139         void blocking(bool status);  ///< Set blocking state
 140
 141         bool eof() const;            ///< Check EOF condition
 142                                      /**< Depending on the socket type, this might never return \p
 143                                         true.
 144
 145                                         This member is somewhat problematic performance wise if
 146                                         called frequently since it relies on virtual
 147                                         functions. However, since the eof() handling is extremely
 148                                         protocol dependent, a policy based implementation does not
 149                                         seam feasible. */
 150         bool valid() const;          ///< Check filehandle validity
 151                                      /**< Any operation besides valid() will fail on an invalid
 152                                         FileHandle */
 153
 154         bool boolean_test() const;  ///< Short for valid() && ! eof()
 155                                     /**< This is called when using a FileHandle instance in a boolean
 156                                        context
 157
 158                                        See the performance comments for the eof() member */
 159
 160         int fd() const;             ///< Return the raw FileHandle
 161
 162         static FileHandle cast_static(FileHandle handle);  /**< \internal */
 163         static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
 164
 165     protected:
 166         explicit FileHandle(std::auto_ptr<FileBody> body);
 167                                     ///< create new FileHandle instance
 168                                     /**< The FileHandle instance will take over ownership over the
 169                                        given FileBody instance which must have been allocated using
 170                                        \c new. To configure the FileHandle behavior, A derived class
 171                                        may provide any class derived from FileBody here. */
 172
 173         FileBody & body();          ///< Access body
 174         FileBody const & body() const; ///< Access body in const context
 175         static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
 176         static FileBody const & body(FileHandle const & handle); ///< Access body of another
 177                                     ///< FileHandle instance in const context
 178
 179         void fd(int fd);            ///< Set raw filehandle
 180
 181     private:
 182         FileBody::ptr body_;
 183     };
 184
 185     /** \brief Adapt FileHandle to senf::Scheduler
 186         \related senf::FileHandle
 187
 188         \internal
 189
 190         This function will be called by the Scheduler to retrieve the file descriptor of the
 191         FileHandle.
 192      */
 193     int retrieve_filehandle(FileHandle handle);
 194
 195     /// @}
 196
 197 }
 198
 199 ///////////////////////////////hh.e////////////////////////////////////////
 200 #include "FileHandle.cci"
 201 //#include "FileHandle.ct"
 202 //#include "FileHandle.cti"
 203 #endif
 204
 205 \f
 206 // Local Variables:
 207 // mode: c++
 208 // fill-column: 100
 209 // c-file-style: "senf"
 210 // indent-tabs-mode: nil
 211 // ispell-local-dictionary: "american"
 212 // compile-command: "scons -u test"
 213 // comment-column: 40
 214 // End: