// $Id$
//
-// Copyright (C) 2006
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// Copyright (C) 2006
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
+// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-/** \file
- \brief senf::FileHandle public header
+/** \file
+ \brief FileHandle public header
+ */
+
+/** \defgroup handle_group The Handle Hierarchy
+
+ \htmlonly
+ <map name="FhHierarchy">
+ <area shape="rect" alt="FileHandle" href="classsenf_1_1FileHandle.html" title="FileHandle" coords="247,1,345,27" />
+ <area shape="rect" alt="SocketHandle" href="classsenf_1_1SocketHandle.html" title="SocketHandle" coords="235,61,355,87" />
+ <area shape="rect" alt="ClientSocketHandle" href="classsenf_1_1ClientSocketHandle.html" title="ClientSocketHandle" coords="32,140,198,167" />
+ <area shape="rect" alt="ServerSocketHandle" href="classsenf_1_1ServerSocketHandle.html" title="ServerSocketHandle" coords="386,140,558,168" />
+ <area shape="rect" alt="ProtocolServerSocketHandle" href="classsenf_1_1ProtocolServerSocketHandle.html" title="ProtocolServerSocketHandle" coords="354,202,590,228" />
+ <area shape="rect" alt="ProtocolClientSocketHandle" href="classsenf_1_1ProtocolClientSocketHandle.html" title="ProtocolClientSocketHandle" coords="1,202,230,228" />
+ </map>
+ <center>
+ <img src="FhHierarchy.png" border="0" alt="FhHierarchy" usemap="#FhHierarchy">
+ </center>
+ \endhtmlonly
+
+ The senf::FileHandle class is the base of a hierarchy of socket handle classes (realized as
+ templates). These classes provide an interface to the complete socket API. While going down the
+ inheritance hierarchy, the interface will be more and more complete.
+
+ The most complete interface is provided by senf::ProtocolClientSocketHandle and
+ senf::ProtocolServerSocketHandle. The template Arguments specifies the Protocol class of the
+ underlying socket type. These are the \e only classes having public constructors and are
+ therefore the only classes, which may be created by the library user. You will normally use
+ these classes by naming a specific socket typedef (e.g. senf::TCPv4ClientSocketHandle).
+
+ However, to aid writing flexible and generic code, the socket library provides the
+ senf::ClientSocketHandle and senf::ServerSocketHandle class templates. These templates implement
+ a family of closely related classes based on the specification of the socket policy. This policy
+ specification may be \e incomplete (see below). Instances of
+ senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned and converted to different
+ ClientSocketHandle/ServerSocketHandle types as long as the policy specifications are compatible.
+
+ \attention It is very important, to (almost) always pass the socket handle <em>by
+ value</em>. The socket handle is a very lightweight class and designed to be used like an
+ ordinary built-in type. This is very important in combination with the policy interface.
+
+ \note The FileHandle hierarchy below the SocketHandle template is \e not meant to be user
+ extensible. To add new socket types, you should introduce new protocol and/or policy classes,
+ the SocketHandle classes should not be changed.
*/
#ifndef HH_FileHandle_
// Custom includes
#include <memory> // std::auto_ptr
-#include "Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
//#include "FileHandle.mpp"
///////////////////////////////hh.p////////////////////////////////////////
namespace senf {
-
+ /// \addtogroup handle_group
+ /// @{
+
/** \brief Basic file handle wrapper
- senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
- minimal interface which does \e not include reading or writing (since some filehandles are
- not readable or writable or only using special function calls like sendto).
-
- The FileHandle class provides handle/body handling and uses automatic reference
- counting. The senf::FileHandle istance is very lightweight and should be used like a
- built-in type.
-
- \attention You should mostly pass around senf::FileHandle objects by \e value und not by
- reference.
-
- The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
- wrap any provider or consumer into a filehandle like interface using this wrapper. The
- wrapper will forward some calls directly to the underlying API without relying on virtual
- methods. This allows important members to be inlined.
-
- It is not possible to use the senf::FileHandle class directly since it does not have any
- public constructor. The FileHandle class is however the baseclass of all handle classes of
- the socket library.
-
- \section filehandle_new Writing senf::FileHandle derived classes
-
- To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
- will have to call the protocted FileHandle constructor passing a new senf::FileBody
- instance. This instance may either be a simple senf::FileBody or a class derived from
- senf::FileBody.
-
- \todo Add public default constructor to allow declaration of (empty) senf::FileHandle
- variables.
+ senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
+ minimal interface which does \e not include reading or writing (since some filehandles are
+ not readable or writable or only using special function calls like sendto).
+
+ The FileHandle class provides handle/body handling and uses automatic reference
+ counting. The senf::FileHandle instance is very lightweight and should be used like a
+ built-in type.
+
+ \attention You should mostly pass around senf::FileHandle objects by \e value and not by
+ reference.
+
+ The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
+ wrap any provider or consumer into a filehandle like interface using this wrapper. The
+ wrapper will forward some calls directly to the underlying API without relying on virtual
+ methods. This allows important members to be inlined.
+
+ It is not possible to use the senf::FileHandle class directly since it does not have any
+ public constructor. The FileHandle class is however the baseclass of all handle classes of
+ the socket library.
+
+ \section filehandle_new Writing senf::FileHandle derived classes
+
+ To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
+ will have to call the protected FileHandle constructor passing a new senf::FileBody
+ instance. This instance may either be a simple senf::FileBody or a class derived from
+ senf::FileBody.
*/
class FileHandle
- : public SafeBool<FileHandle>
+ : public safe_bool<FileHandle>
{
public:
///////////////////////////////////////////////////////////////////////////
///\name Structors and default members
///@{
- // protected default constructor
+ FileHandle();
+
+ // my default constructor
// default copy constructor
// default copy assignment
// default destructor
///////////////////////////////////////////////////////////////////////////
void close(); ///< Close filehandle
- /**< \throws senf::SystemException */
+ /**< \throws senf::SystemException */
void terminate(); ///< Close filehandle ignoring error conditions
- bool readable() const; ///< Check, wether a read on the handle would not block
- ///< (ignoring blocking state)
+ bool readable() const; ///< Check, whether a read on the handle would not block
+ ///< (ignoring blocking state)
void waitReadable() const; ///< Wait, until read on the handle would not block (ignoring
- ///< blocking state)
- bool writeable() const; ///< Check, wether a write on the handle would not block
- ///< (ignoring blocking state)
+ ///< blocking state)
+ bool writeable() const; ///< Check, whether a write on the handle would not block
+ ///< (ignoring blocking state)
void waitWriteable() const; ///< Wait, until a write on the handle would not block
- ///< (ignoring blocking state)
+ ///< (ignoring blocking state)
bool blocking() const; ///< Return current blocking state
void blocking(bool status); ///< Set blocking state
bool eof() const; ///< Check EOF condition
- /**< Depending on the socket type, this might never return \p
- true.
-
- This member is somewhat problematic performance wise if
- called frequently since it relies on virtual
- functions. However, since the eof() handling is extremely
- protocol dependent, a policy based implementation does not
- seam feasible. */
+ /**< Depending on the socket type, this might never return \p
+ true.
+
+ This member is somewhat problematic performance wise if
+ called frequently since it relies on virtual
+ functions. However, since the eof() handling is extremely
+ protocol dependent, a policy based implementation does not
+ seam feasible. */
bool valid() const; ///< Check filehandle validity
- /**< Any operation besides valid() will fail on an invalid
- FileHandle */
+ /**< Any operation besides valid() will fail on an invalid
+ FileHandle */
- bool boolean_test() const; ///< Short for valid() && ! eof()
- /**< This is called when using a FileHandle instance in a boolen
- context
+ bool boolean_test() const; ///< Short for valid() && ! eof()
+ /**< This is called when using a FileHandle instance in a boolean
+ context
- See the performance comments for the eof() member */
+ See the performance comments for the eof() member */
int fd() const; ///< Return the raw FileHandle
protected:
explicit FileHandle(std::auto_ptr<FileBody> body);
- ///< create new FileHandle instance
- /**< The FileHandle instance will take over ownership over the
- given FileBody instance which must have been allocated using
- \c new. To configure the FileHandle behavior, A derived class
- may provide any class derived from FileBody here. */
+ ///< create new FileHandle instance
+ /**< The FileHandle instance will take over ownership over the
+ given FileBody instance which must have been allocated using
+ \c new. To configure the FileHandle behavior, A derived class
+ may provide any class derived from FileBody here. */
+
+ explicit FileHandle(FileBody::ptr body);
FileBody & body(); ///< Access body
FileBody const & body() const; ///< Access body in const context
static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
static FileBody const & body(FileHandle const & handle); ///< Access body of another
- ///< FileHandle instance in const context
+ ///< FileHandle instance in const context
- void fd(int fd); ///< Set raw filehandle
+ void fd(int fd); ///< Set raw filehandle
private:
FileBody::ptr body_;
+
+ friend class FileBody;
};
+ /** \brief Adapt FileHandle to senf::Scheduler
+ \related senf::FileHandle
+
+ \internal
+
+ This function will be called by the Scheduler to retrieve the file descriptor of the
+ FileHandle.
+ */
int retrieve_filehandle(FileHandle handle);
+ /// @}
+
}
///////////////////////////////hh.e////////////////////////////////////////
\f
// Local Variables:
// mode: c++
-// c-file-style: "senf"
// fill-column: 100
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// comment-column: 40
// End:
projects / senf.git / blobdiff