X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FFileHandle.hh;h=8afbd486fb1af09a0b2ded49a62998cc75b3caf8;hb=1ad3873b372da6187b1fbc645bf276287d2efb54;hp=79985c473eea8d10e0c7489c447832da92a11649;hpb=0232acda50ed45ee5c7014e887267b64e8f1979b;p=senf.git diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh index 79985c4..8afbd48 100644 --- a/Socket/FileHandle.hh +++ b/Socket/FileHandle.hh @@ -26,42 +26,44 @@ /** \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 by value. 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. + \htmlonly + + FileHandle + SocketHandle + ClientSocketHandle + ServerSocketHandle + ProtocolServerSocketHandle + ProtocolClientSocketHandle + +
+ FhHierarchy +
+ \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 by + value. 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_ @@ -69,7 +71,7 @@ // Custom includes #include // std::auto_ptr -#include "Utils/SafeBool.hh" +#include "../Utils/safe_bool.hh" //#include "FileHandle.mpp" ///////////////////////////////hh.p//////////////////////////////////////// @@ -87,10 +89,10 @@ namespace senf { 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 + 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 und not by + \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 @@ -105,15 +107,12 @@ namespace senf { \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 + 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. - - \fixme Add public default constructor to allow declaration of (empty) senf::FileHandle - variables. */ class FileHandle - : public SafeBool + : public safe_bool { public: /////////////////////////////////////////////////////////////////////////// @@ -123,7 +122,9 @@ namespace senf { ///\name Structors and default members ///@{ - // protected default constructor + FileHandle(); + + // my default constructor // default copy constructor // default copy assignment // default destructor @@ -137,11 +138,11 @@ namespace senf { /**< \throws senf::SystemException */ void terminate(); ///< Close filehandle ignoring error conditions - bool readable() const; ///< Check, wether a read on the handle would not block + 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 + 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) @@ -163,7 +164,7 @@ namespace senf { FileHandle */ bool boolean_test() const; ///< Short for valid() && ! eof() - /**< This is called when using a FileHandle instance in a boolen + /**< This is called when using a FileHandle instance in a boolean context See the performance comments for the eof() member */ @@ -181,6 +182,8 @@ namespace senf { \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 @@ -191,6 +194,8 @@ namespace senf { private: FileBody::ptr body_; + + friend class FileBody; }; /** \brief Adapt FileHandle to senf::Scheduler @@ -220,4 +225,6 @@ namespace senf { // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" +// compile-command: "scons -u test" +// comment-column: 40 // End: