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_FileHandle_
28 #define IH_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() */
87 // NO DESTRUCTOR HERE - destructors and virtual functions don't mix. What would be in the
88 // the destructor is in 'destroyClose()' which is called from FileHandle::~FileHandle()
89 // *before* the last handle dies.
92 // no conversion constructors
95 ///////////////////////////////////////////////////////////////////////////
106 bool readable() const;
107 void waitReadable() const;
108 bool writeable() const;
109 void waitWriteable() const;
111 bool blocking() const;
112 void blocking(bool status);
118 ///////////////////////////////////////////////////////////////////////////
119 // Virtual interface for subclasses to override
121 virtual void v_close(); ///< Called to close the file descriptor
122 /**< You should probably always call the global ::close()
123 function in this member, however you might want to do
124 some additional cleanup here. If the operation fails, you
125 are allowed to throw (preferably a
126 senf::SystemException).
128 \throws senf::SystemException */
129 virtual void v_terminate(); ///< Called to forcibly close the file descriptor
130 /**< This member is called by the destructor (and by
131 terminate()) to close the descriptor. This member must \e
132 never throw, it should probably just ignore error
133 conditions (there's not much else you can do) */
134 virtual bool v_eof() const; ///< Called by eof()
135 virtual bool v_valid() const; ///< Called by valid()
136 /**< This member is only called, if the file descriptor is
142 bool pollCheck(int fd, bool incoming, bool block=false) const;
149 ///////////////////////////////ih.e////////////////////////////////////////
156 // c-file-style: "senf"
157 // indent-tabs-mode: nil
158 // ispell-local-dictionary: "american"
159 // compile-command: "scons -u test"
160 // comment-column: 40