4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
24 \brief FileHandle internal header
27 #ifndef IH_SENF_Socket_FileHandle_
28 #define IH_SENF_Socket_FileHandle_ 1
31 #include <boost/intrusive_ptr.hpp>
32 #include "../Utils/intrusive_refcount.hh"
33 #include "../Utils/pool_alloc_mixin.hh"
35 ///////////////////////////////ih.p////////////////////////////////////////
41 /** \brief FileHandle referenced body
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.
49 Since the senf::FileHandle class forwards most calls directly to the underlying
50 senf::FileBody instance, most members are documented in senf::FileHandle.
52 \section filebody_new Writing senf::FileBody derived classes
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).
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
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
68 : public senf::intrusive_refcount,
69 public senf::pool_alloc_mixin<FileBody>
72 ///////////////////////////////////////////////////////////////////////////
75 typedef boost::intrusive_ptr<FileBody> ptr;
77 ///////////////////////////////////////////////////////////////////////////
78 ///\name Structors and default members
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() */
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.
93 // no conversion constructors
96 ///////////////////////////////////////////////////////////////////////////
107 bool readable() const;
108 void waitReadable() const;
109 bool writeable() const;
110 void waitWriteable() const;
112 bool blocking() const;
113 void blocking(bool status);
119 ///////////////////////////////////////////////////////////////////////////
120 // Virtual interface for subclasses to override
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).
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
143 bool pollCheck(int fd, bool incoming, bool block=false) const;
150 ///////////////////////////////ih.e////////////////////////////////////////
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