X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FFileHandle.ih;h=02c6b71e82ee2555ad46a4a601e80741eff407c2;hb=1ad3873b372da6187b1fbc645bf276287d2efb54;hp=8e59737689a24d396f0cd4c307fea22ec801bccb;hpb=c52cd7d87dbb525c1267aad27391b8b7365dbb57;p=senf.git

diff --git a/Socket/FileHandle.ih b/Socket/FileHandle.ih
index 8e59737..02c6b71 100644
--- a/Socket/FileHandle.ih
+++ b/Socket/FileHandle.ih
@@ -1,6 +1,6 @@
 // $Id$
 //
-// Copyright (C) 2006 
+// Copyright (C) 2006
 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
 //     Stefan Bund <stefan.bund@fokus.fraunhofer.de>
@@ -20,34 +20,69 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief FileHandle internal header
+ */
+
 #ifndef IH_FileHandle_
 #define IH_FileHandle_ 1
 
 // Custom includes
 #include <boost/intrusive_ptr.hpp>
-#include "Utils/intrusive_refcount.hh"
+#include "../Utils/intrusive_refcount.hh"
+#include "../Utils/pool_alloc_mixin.hh"
 
 ///////////////////////////////ih.p////////////////////////////////////////
 
-namespace satcom {
-namespace lib {
+namespace senf {
+
+    class FileHandle;
+
+    /** \brief FileHandle referenced body
+
+        \internal
+
+        The senf::FileBody class forms the body part of the handle/body structure of the FileHandle
+        interface. It manages the FileHandle data and is referenced by senf::FileHandle. It is
+        automatically managed using reference counting.
+
+        Since the senf::FileHandle class forwards most calls directly to the underlying
+        senf::FileBody instance, most members are documented in senf::FileHandle.
+
+        \section filebody_new Writing senf::FileBody derived classes
 
-    /** \brief
+        It is possible to write customized senf::FileBody derived body implementations. This
+        implementation can then be used be a senf::FileHandle derived class to customize the
+        FileHandle behavior. Handling the body directly by the handle class ensures, that no invalid
+        handles can be created (a senf::FileHandle derived handle expecting a specific body type but
+        pointing to a different body type).
+
+        To customize the behavior, a virtual interface is provided. This interface only covers some
+        basic functionality which is only used infrequently during the lifetime of a FileHandle
+        instance.
+
+        \attention Whenever a new class is derived from FileBody which adds new members, this class
+            \e must also derive from senf::pool_alloc_mixin
       */
     class FileBody
-        : public satcom::lib::intrusive_refcount
+        : public senf::intrusive_refcount, 
+          public senf::pool_alloc_mixin<FileBody>
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
         // Types
-        
+
         typedef boost::intrusive_ptr<FileBody> ptr;
 
         ///////////////////////////////////////////////////////////////////////////
         ///\name Structors and default members
         ///@{
-        
-        explicit FileBody(int fd=-1);
+
+        explicit FileBody(int fd=-1);   ///< Create new instance
+                                        /**< You need to pass a real file descriptor to this
+                                           constructor not some arbitrary id even if you overload
+                                           all the virtual members. If the file descriptor is -1 the
+                                           resulting body/handle is not valid() */
         virtual ~FileBody();
 
         // no copy
@@ -56,6 +91,8 @@ namespace lib {
         ///@}
         ///////////////////////////////////////////////////////////////////////////
 
+        FileHandle handle();
+
         int fd() const;
         void fd(int fd);
 
@@ -72,26 +109,38 @@ namespace lib {
 
         bool eof() const;
         bool valid() const;
-        
+
     private:
         ///////////////////////////////////////////////////////////////////////////
         // Virtual interface for subclasses to override
 
-        virtual void v_close();
-        virtual void v_terminate();
-        virtual bool v_eof() const;
-        virtual bool v_valid() const;
-        
+        virtual void v_close();         ///< Called to close the file descriptor
+                                        /**< You should probably always call the global ::close()
+                                           function in this member, however you might want to do
+                                           some additional cleanup here. If the operation fails, you
+                                           are allowed to throw (preferably a
+                                           senf::SystemException).
+
+                                        \throws senf::SystemException */
+        virtual void v_terminate();     ///< Called to forcibly close the file descriptor
+                                        /**< This member is called by the destructor (and by
+                                           terminate()) to close the descriptor. This member must \e
+                                           never throw, it should probably just ignore error
+                                           conditions (there's not much else you can do) */
+        virtual bool v_eof() const;     ///< Called by eof()
+        virtual bool v_valid() const;   ///< Called by valid()
+                                        /**< This member is only called, if the file descriptor is
+                                           not -1 */
 
     protected:
-        
+
     private:
         bool pollCheck(int fd, bool incoming, bool block=false) const;
 
         int fd_;
     };
 
-}}
+}
 
 ///////////////////////////////ih.e////////////////////////////////////////
 #endif
@@ -99,5 +148,10 @@ namespace lib {
 
 // Local Variables:
 // mode: c++
-// c-file-style: "satcom"
+// fill-column: 100
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// comment-column: 40
 // End: