Socket/FileHandle.ih

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