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_FileHandle_
  28 #define IH_FileHandle_ 1
  29
  30 // Custom includes
  31 #include <boost/intrusive_ptr.hpp>
  32 #include "../Utils/intrusive_refcount.hh"
  33 #include "../Utils/pool_alloc_mixin.hh"
  34
  35 ///////////////////////////////ih.p////////////////////////////////////////
  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         void waitReadable() const;
 109         bool writeable() const;
 110         void waitWriteable() const;
 111
 112         bool blocking() const;
 113         void blocking(bool status);
 114
 115         bool eof() const;
 116         bool valid() const;
 117
 118     private:
 119         ///////////////////////////////////////////////////////////////////////////
 120         // Virtual interface for subclasses to override
 121
 122         virtual void v_close();         ///< Called to close the file descriptor
 123                                         /**< You should probably always call the global ::close()
 124                                            function in this member, however you might want to do
 125                                            some additional cleanup here. If the operation fails, you
 126                                            are allowed to throw (preferably a
 127                                            senf::SystemException).
 128
 129                                         \throws senf::SystemException */
 130         virtual void v_terminate();     ///< Called to forcibly close the file descriptor
 131                                         /**< This member is called by the destructor (and by
 132                                            terminate()) to close the descriptor. This member must \e
 133                                            never throw, it should probably just ignore error
 134                                            conditions (there's not much else you can do) */
 135         virtual bool v_eof() const;     ///< Called by eof()
 136         virtual bool v_valid() const;   ///< Called by valid()
 137                                         /**< This member is only called, if the file descriptor is
 138                                            not -1 */
 139
 140     protected:
 141
 142     private:
 143         bool pollCheck(int fd, bool incoming, bool block=false) const;
 144
 145         int fd_;
 146     };
 147
 148 }
 149
 150 ///////////////////////////////ih.e////////////////////////////////////////
 151 #endif
 152
 153 \f
 154 // Local Variables:
 155 // mode: c++
 156 // fill-column: 100
 157 // c-file-style: "senf"
 158 // indent-tabs-mode: nil
 159 // ispell-local-dictionary: "american"
 160 // compile-command: "scons -u test"
 161 // comment-column: 40
 162 // End: