// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief FileHandle public header
+ */
+
+/** \defgroup handle_group The Handle Hierarchy
+
+ \image html FhHierarchy.png
+
+ 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_
#define HH_FileHandle_ 1
#include "FileHandle.ih"
namespace senf {
-
+
+ /// \addtogroup handle_group
+ /// @{
/** \brief Basic file handle wrapper
bool eof() const; ///< Check EOF condition
/**< Depending on the socket type, this might never return \p
- true */
+ 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 */
bool boolean_test() const; ///< Short for valid() && ! eof()
/**< This is called when using a FileHandle instance in a boolen
- context */
+ context
+
+ See the performance comments for the eof() member */
int fd() const; ///< Return the raw FileHandle
- static FileHandle cast_static(FileHandle handle); ///< \internal
- static FileHandle cast_dynamic(FileHandle handle); ///< \internal
+ static FileHandle cast_static(FileHandle handle); /**< \internal */
+ static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
protected:
explicit FileHandle(std::auto_ptr<FileBody> body);
FileBody::ptr body_;
};
+ /** \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////////////////////////////////////////