Implemented IpV6Packet and added raw-data constructor to INet6Address

[senf.git] / Socket / FileHandle.hh

diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh
index 9a8c7e7..a0b2de5 100644 (file)
--- 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 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////////////////////////////////////////