senf/Socket/FileHandle.ih

   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 internal header
  25  */
  26
  27 #ifndef IH_SENF_Socket_FileHandle_
  28 #define IH_SENF_Socket_FileHandle_ 1
  29
  30 // Custom includes
  31 #include <boost/intrusive_ptr.hpp>
  32 #include <senf/Utils/intrusive_refcount.hh>
  33 #include <senf/Utils/pool_alloc_mixin.hh>
  34
  35 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  36
  37 namespace senf {
  38
  39     class FileHandle;
  40
  41     /** \brief FileHandle referenced body
  42
  43         \internal
  44
  45         The senf::FileBody class forms the body part of the handle/body structure of the FileHandle
  46         interface. It manages the FileHandle data and is referenced by senf::FileHandle. It is
  47         automatically managed using reference counting.
  48
  49         Since the senf::FileHandle class forwards most calls directly to the underlying
  50         senf::FileBody instance, most members are documented in senf::FileHandle.
  51
  52         \section filebody_new Writing senf::FileBody derived classes
  53
  54         It is possible to write customized senf::FileBody derived body implementations. This
  55         implementation can then be used be a senf::FileHandle derived class to customize the
  56         FileHandle behavior. Handling the body directly by the handle class ensures, that no invalid
  57         handles can be created (a senf::FileHandle derived handle expecting a specific body type but
  58         pointing to a different body type).
  59
  60         To customize the behavior, a virtual interface is provided. This interface only covers some
  61         basic functionality which is only used infrequently during the lifetime of a FileHandle
  62         instance.
  63
  64         \attention Whenever a new class is derived from FileBody which adds new members, this class
  65             \e must also derive from senf::pool_alloc_mixin
  66       */
  67     class FileBody
  68         : public senf::intrusive_refcount,
  69           public senf::pool_alloc_mixin<FileBody>
  70     {
  71     public:
  72         //-/////////////////////////////////////////////////////////////////////////////////////////
  73         // Types
  74
  75         typedef boost::intrusive_ptr<FileBody> ptr;
  76
  77         //-/////////////////////////////////////////////////////////////////////////////////////////
  78         ///\name Structors and default members
  79         //\{
  80
  81         explicit FileBody(int fd=-1);   ///< Create new instance
  82                                         /**< You need to pass a real file descriptor to this
  83                                            constructor not some arbitrary id even if you overload
  84                                            all the virtual members. If the file descriptor is -1 the
  85                                            resulting body/handle is not valid() */
  86         virtual ~FileBody();
  87
  88         // NO DESTRUCTOR HERE (that is, only an empty virtual destructor) - destructors and virtual
  89         // functions don't mix. What would be in the the destructor is in 'destroyClose()' which is
  90         // called from FileHandle::~FileHandle() *before* the last handle dies.
  91
  92         // no copy
  93         // no conversion constructors
  94
  95         //\}
  96         //-/////////////////////////////////////////////////////////////////////////////////////////
  97
  98         FileHandle handle();
  99
 100         int fd() const;
 101         void fd(int fd);
 102
 103         void close();
 104         void terminate();
 105         void destroyClose();
 106
 107         bool readable() const;
 108         bool waitReadable(senf::ClockService::clock_type timeout) const;
 109         bool writeable() const;
 110         bool waitWriteable(senf::ClockService::clock_type timeout) const;
 111         bool oobReadable() const;
 112         bool waitOOBReadable(senf::ClockService::clock_type timeout) const;
 113
 114         bool blocking() const;
 115         void blocking(bool status);
 116
 117         bool eof() const;
 118         bool valid() const;
 119
 120     private:
 121         //-/////////////////////////////////////////////////////////////////////////////////////////
 122         // Virtual interface for subclasses to override
 123
 124         virtual void v_close();         ///< Called to close the file descriptor
 125                                         /**< You should probably always call the global ::close()
 126                                            function in this member, however you might want to do
 127                                            some additional cleanup here. If the operation fails, you
 128                                            are allowed to throw (preferably a
 129                                            senf::SystemException).
 130
 131                                         \throws senf::SystemException */
 132         virtual void v_terminate();     ///< Called to forcibly close the file descriptor
 133                                         /**< This member is called by the destructor (and by
 134                                            terminate()) to close the descriptor. This member must \e
 135                                            never throw, it should probably just ignore error
 136                                            conditions (there's not much else you can do) */
 137         virtual bool v_eof() const;     ///< Called by eof()
 138         virtual bool v_valid() const;   ///< Called by valid()
 139                                         /**< This member is only called, if the file descriptor is
 140                                            not -1 */
 141
 142     protected:
 143
 144     private:
 145         bool pollCheck(int fd, bool incoming, int timeout, bool oob=false) const;
 146
 147         int fd_;
 148     };
 149
 150 }
 151
 152 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 153 #endif
 154
 155 \f
 156 // Local Variables:
 157 // mode: c++
 158 // fill-column: 100
 159 // c-file-style: "senf"
 160 // indent-tabs-mode: nil
 161 // ispell-local-dictionary: "american"
 162 // compile-command: "scons -u test"
 163 // comment-column: 40
 164 // End: