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 copy
  89         // no conversion constructors
  90
  91         ///@}
  92         ///////////////////////////////////////////////////////////////////////////
  93
  94         FileHandle handle();
  95
  96         int fd() const;
  97         void fd(int fd);
  98
  99         void close();
 100         void terminate();
 101
 102         bool readable() const;
 103         void waitReadable() const;
 104         bool writeable() const;
 105         void waitWriteable() const;
 106
 107         bool blocking() const;
 108         void blocking(bool status);
 109
 110         bool eof() const;
 111         bool valid() const;
 112
 113     private:
 114         ///////////////////////////////////////////////////////////////////////////
 115         // Virtual interface for subclasses to override
 116
 117         virtual void v_close();         ///< Called to close the file descriptor
 118                                         /**< You should probably always call the global ::close()
 119                                            function in this member, however you might want to do
 120                                            some additional cleanup here. If the operation fails, you
 121                                            are allowed to throw (preferably a
 122                                            senf::SystemException).
 123
 124                                         \throws senf::SystemException */
 125         virtual void v_terminate();     ///< Called to forcibly close the file descriptor
 126                                         /**< This member is called by the destructor (and by
 127                                            terminate()) to close the descriptor. This member must \e
 128                                            never throw, it should probably just ignore error
 129                                            conditions (there's not much else you can do) */
 130         virtual bool v_eof() const;     ///< Called by eof()
 131         virtual bool v_valid() const;   ///< Called by valid()
 132                                         /**< This member is only called, if the file descriptor is
 133                                            not -1 */
 134
 135     protected:
 136
 137     private:
 138         bool pollCheck(int fd, bool incoming, bool block=false) const;
 139
 140         int fd_;
 141     };
 142
 143 }
 144
 145 ///////////////////////////////ih.e////////////////////////////////////////
 146 #endif
 147
 148 \f
 149 // Local Variables:
 150 // mode: c++
 151 // fill-column: 100
 152 // c-file-style: "senf"
 153 // indent-tabs-mode: nil
 154 // ispell-local-dictionary: "american"
 155 // compile-command: "scons -u test"
 156 // comment-column: 40
 157 // End: