X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FFileHandle.hh;h=5f82eaf103c5bb175999b8a842017dab3ef3b3a2;hb=f11bb3f5a7eeb232a74d13b7d7ddc6746ca2c2d2;hp=9a8c7e7d5b7d015353e74589b9f57094729cc40b;hpb=032707d24b1059febe83ce56b11fd79df106c6e2;p=senf.git

diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh
index 9a8c7e7..5f82eaf 100644
--- a/Socket/FileHandle.hh
+++ b/Socket/FileHandle.hh
@@ -20,6 +20,50 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file 
+    \brief senf::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
 
@@ -32,7 +76,9 @@
 #include "FileHandle.ih"
 
 namespace senf {
-
+    
+    /// \addtogroup handle_group
+    /// @{
     
     /** \brief Basic file handle wrapper
 
@@ -105,19 +151,27 @@ namespace senf {
 
         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);
@@ -139,8 +193,18 @@ namespace senf {
         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////////////////////////////////////////