From: g0dil Date: Thu, 1 Feb 2007 11:32:08 +0000 (+0000) Subject: Finished Socket library file handle hierarchy documentation X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=aec1302f91b51edb58f8a97985ab2e0aa9c8db66;p=senf.git Finished Socket library file handle hierarchy documentation git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@191 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Socket/ClientSocketHandle.hh b/Socket/ClientSocketHandle.hh index 9e55210..3c836a4 100644 --- a/Socket/ClientSocketHandle.hh +++ b/Socket/ClientSocketHandle.hh @@ -333,6 +333,7 @@ namespace senf { There are two Variants of this member, one will return the address by value, the other takes a reference argument to elide the copy operation. + \throws senf::SystemException */ Address local (); void local (Address & addr); @@ -360,9 +361,7 @@ namespace senf { ///@} static ClientSocketHandle cast_static(FileHandle handle); - /**< \internal */ static ClientSocketHandle cast_dynamic(FileHandle handle); - /**< \internal */ // we need to override both since SocketHandle is *not* polymorphic void state(SocketStateMap & map, unsigned lod=0); diff --git a/Socket/ProtocolClientSocketHandle.cti b/Socket/ProtocolClientSocketHandle.cti index 98d722a..1b20fdb 100644 --- a/Socket/ProtocolClientSocketHandle.cti +++ b/Socket/ProtocolClientSocketHandle.cti @@ -20,6 +20,11 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief senf::ProtocolClientSocketHandle inline template + implementation + */ + // Definition of inline template functions //#include "ProtocolClientSocketHandle.ih" diff --git a/Socket/ProtocolClientSocketHandle.hh b/Socket/ProtocolClientSocketHandle.hh index 54a32d0..43e8134 100644 --- a/Socket/ProtocolClientSocketHandle.hh +++ b/Socket/ProtocolClientSocketHandle.hh @@ -20,6 +20,10 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief senf::ProtocolClientSocketHandle public header + */ + #ifndef HH_ProtocolClientSocketHandle_ #define HH_ProtocolClientSocketHandle_ 1 @@ -36,7 +40,21 @@ namespace senf { template class ProtocolServerSocketHandle; - /** \brief + /** \brief Protocol specific socket handle (client interface) + + The ProtocolClientSocketHandle is the client interface leaf class of the handle + hierarchy. This is the class to instantiate to open a new socket. This is also the \e only + class, which can be used to open a client socket. + + The \a Protocol template argument defines the protocol of the socket. This protocol provides + the protocol interface of the socket as well as the complete socket policy of this protocol. + + The ProtocolClientSocketHandle adds the protocol interface as an additional interface to the + socket handle. This interface is only accessible via the protocol class. All socket + functionality not available through the policy interface (see ClientSocketHandle) is + accessible via the protocol() member. + + \see \ref protocol_group */ template class ProtocolClientSocketHandle @@ -46,12 +64,21 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// // Types - typedef SocketProtocol Protocol; + typedef SocketProtocol Protocol; ///< The sockets protocol /////////////////////////////////////////////////////////////////////////// ///\name Structors and default members ///@{ + /** \brief Create new client socket + + This constructor is one of the possible constructors. The exact Signature of the + constructor (or constructors) is defined by the \c init_client() member (or members) of + the \a Protocol class. ProtocolClientSocketHandle defines a number of constructors + taking up to 9 arguments which just forward to a corresponding \a Protocol\c + ::init_client() member. See the documentation of the respective Protocol class for a + detailed documentation of that protocols constructors. + */ ProtocolClientSocketHandle(); # define BOOST_PP_ITERATION_PARAMS_1 (4, (1, 9, "Socket/ProtocolClientSocketHandle.mpp", 1)) @@ -60,7 +87,11 @@ namespace senf { ///@} /////////////////////////////////////////////////////////////////////////// - Protocol const & protocol(); + Protocol const & protocol(); ///< Access the protocol interface + /**< The returned protocol class reference gives access to + the complete protocol interface as defined by that + class. See the respective protocol class documentation. + \returns \a Protocol class reference */ static ProtocolClientSocketHandle cast_static(FileHandle handle); static ProtocolClientSocketHandle cast_dynamic(FileHandle handle); @@ -89,4 +120,5 @@ namespace senf { // Local Variables: // mode: c++ // c-file-style: "senf" +// fill-column: 100 // End: diff --git a/Socket/ProtocolClientSocketHandle.mpp b/Socket/ProtocolClientSocketHandle.mpp index df53979..a7b463a 100644 --- a/Socket/ProtocolClientSocketHandle.mpp +++ b/Socket/ProtocolClientSocketHandle.mpp @@ -20,71 +20,67 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -#if !BOOST_PP_IS_ITERATING -#ifndef MPP_ProtocolClientSocketHandle_ +/** \file + \brief senf::ProtocolClientSocketHandle Boost.Preprocessor external iteration include + */ + +#if !BOOST_PP_IS_ITERATING && !defined(MPP_ProtocolClientSocketHandle_) +#define MPP_ProtocolClientSocketHandle_ 1 // Custom includes #include #include #include -//////////////////////////////mpp.p//////////////////////////////////////// +// ///////////////////////////mpp.p//////////////////////////////////////// +#endif // ///////////////////////////////////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// // Local Macros -#define mpp_PCSH_Arg(z,n,data) BOOST_PP_CAT(A,n) const & BOOST_PP_CAT(a,n) - -#define mpp_PCSH_TemplateParameters() BOOST_PP_ENUM_PARAMS(BOOST_PP_ITERATION(), class A ) -#define mpp_PCSH_MethodParameters() BOOST_PP_ENUM(BOOST_PP_ITERATION(), mpp_PCSH_Arg, ) -#define mpp_PCSH_CallParameters() BOOST_PP_ENUM_PARAMS(BOOST_PP_ITERATION(), a ) - -////// -#endif -#else -/////////////////////////////////////////////////////////////////////////// +#define mpp_Arg(z,n,data) BOOST_PP_CAT(A,n) const & BOOST_PP_CAT(a,n) +#define mpp_TemplateParameters() BOOST_PP_ENUM_PARAMS(BOOST_PP_ITERATION(), class A ) +#define mpp_MethodParameters() BOOST_PP_ENUM(BOOST_PP_ITERATION(), mpp_Arg, ) +#define mpp_CallParameters() BOOST_PP_ENUM_PARAMS(BOOST_PP_ITERATION(), a ) -////// -#if BOOST_PP_ITERATION_FLAGS()==1 -/////////////////////////////////////////////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// +#if BOOST_PP_IS_ITERATING // ////////////////////////////////////////////// +#if BOOST_PP_ITERATION_FLAGS()==1 // ////////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// // senf::ProtocolClientSocketHandle:: // ProtocolClientSocketHandle (constructor) declaration -template < mpp_PCSH_TemplateParameters() > -ProtocolClientSocketHandle( mpp_PCSH_MethodParameters() ); +template < mpp_TemplateParameters() > +ProtocolClientSocketHandle( mpp_MethodParameters() ); -////// -#elif BOOST_PP_ITERATION_FLAGS()==2 -/////////////////////////////////////////////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// +#elif BOOST_PP_ITERATION_FLAGS()==2 // //////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// // senf::ProtocolClientSocketHandle:: // ProtocolClientSocketHandle (constructor) implementation template -template < mpp_PCSH_TemplateParameters() > +template < mpp_TemplateParameters() > prefix_ senf::ProtocolClientSocketHandle:: -ProtocolClientSocketHandle( mpp_PCSH_MethodParameters() ) +ProtocolClientSocketHandle( mpp_MethodParameters() ) : ClientSocketHandle( std::auto_ptr(new SocketProtocol())) { - this->protocol().init_client( mpp_PCSH_CallParameters() ); + this->protocol().init_client( mpp_CallParameters() ); } -////// -#endif -#endif -#if !BOOST_PP_IS_ITERATING -#ifdef MPP_PCSH__ProtocolClientSocketHandle_ -/////////////////////////////////////////////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// +#endif // ///////////////////////////////////////////////////////////////// +#endif // ///////////////////////////////////////////////////////////////// +// //////////////////////////////////////////////////////////////////////// // Undefine local Macros -#undef mpp_PCSH_Arg -#undef mpp_PCSH_TemplateParameters -#undef mpp_PCSH_MethodParameters -#undef mpp_PCSH_CallParameters +#undef mpp_Arg +#undef mpp_TemplateParameters +#undef mpp_MethodParameters +#undef mpp_CallParameters -//////////////////////////////mpp_PCSH_.e//////////////////////////////////////// -#else -#define MPP_PCSH__ProtocolClientSocketHandle_ 1 -#endif -#endif +// //////////////////////////////////////////////////////////////////////// +// ///////////////////////////mpp.e//////////////////////////////////////// // Local Variables: diff --git a/Socket/ProtocolServerSocketHandle.cti b/Socket/ProtocolServerSocketHandle.cti index 45be81f..2fd0720 100644 --- a/Socket/ProtocolServerSocketHandle.cti +++ b/Socket/ProtocolServerSocketHandle.cti @@ -20,6 +20,10 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief senf::ProtocolServerSocketHandle inline template implementation + */ + // Definition of inline template functions //#include "ProtocolServerSocketHandle.ih" diff --git a/Socket/ProtocolServerSocketHandle.hh b/Socket/ProtocolServerSocketHandle.hh index 002e209..a60c6c1 100644 --- a/Socket/ProtocolServerSocketHandle.hh +++ b/Socket/ProtocolServerSocketHandle.hh @@ -20,6 +20,10 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief senf::ProtocolServerSocketHandle public header + */ + #ifndef HH_ProtocolServerSocketHandle_ #define HH_ProtocolServerSocketHandle_ 1 @@ -36,7 +40,25 @@ namespace senf { template class ProtocolClientSocketHandle; - /** \brief + /** \brief Protocol specific socket handle (server interface) + + The ProtocolServerSocketHandle is the server interface leaf class of the handle + hierarchy. This is the class to instantiate to open a new socket. This is also the \e only + class, which can be used to open a server socket. + + The \a Protocol template argument defines the protocol of the socket. This protocol provides + the protocol interface of the socket as well as the complete socket policy of this protocol. + + The ProtocolServerSocketHandle adds the protocol interface as an additional interface to the + socket handle. This interface is only accessible via the protocol class. All socket + functionality not available through the policy interface (see ServerSocketHandle) is + accessible via the protocol() member. + + A ProtocolServerSocketHandle is only meaningful for connection oriented addressable + protocols (CommunicationPolicy is ConnectedCommunicationPolicy and AddressingPolicy is not + NoAddressingPolicy). + + \see \ref protocol_group */ template class ProtocolServerSocketHandle @@ -46,12 +68,22 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// // Types - typedef SocketProtocol Protocol; + typedef SocketProtocol Protocol; ///< The socket protocol /////////////////////////////////////////////////////////////////////////// ///\name Structors and default members ///@{ + /** \brief Create new server socket + + This constructor is one of the possible constructors. The exact Signature of the + constructor (or constructors) is defined by the \c init_server() member (or members) of + the \a Protocol class. ProtocolClientSocketHandle defines a number of constructors + taking up to 9 arguments which just forward to a corresponding \a Protocol\c + ::init_server() member. See the documentation of the respective Protocol class for a + detailed documentation of that protocols constructors. + */ + ProtocolServerSocketHandle(); # define BOOST_PP_ITERATION_PARAMS_1 (4, (1, 9, "Socket/ProtocolServerSocketHandle.mpp", 1)) @@ -60,7 +92,11 @@ namespace senf { ///@} /////////////////////////////////////////////////////////////////////////// - Protocol const & protocol(); + Protocol const & protocol(); ///< Access the protocol interface + /**< The returned protocol class reference gives access to + the complete protocol interface as defined by that + class. See the respective protocol class documentation. + \returns \a Protocol class reference */ ProtocolClientSocketHandle accept(); @@ -90,4 +126,5 @@ namespace senf { // Local Variables: // mode: c++ // c-file-style: "senf" +// fill-column: 100 // End: diff --git a/Socket/ProtocolServerSocketHandle.mpp b/Socket/ProtocolServerSocketHandle.mpp index 101d41b..40a8e56 100644 --- a/Socket/ProtocolServerSocketHandle.mpp +++ b/Socket/ProtocolServerSocketHandle.mpp @@ -20,6 +20,10 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ssenf::ProtocolServerSocketHandle Boost.Preprocessor external iteration include + */ + #if !BOOST_PP_IS_ITERATING #ifndef MPP_PSSH__ProtocolServerSocketHandle_ diff --git a/Socket/ServerSocketHandle.cti b/Socket/ServerSocketHandle.cti index 37bbe44..643e477 100644 --- a/Socket/ServerSocketHandle.cti +++ b/Socket/ServerSocketHandle.cti @@ -20,6 +20,10 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief senf::ServerSocketHandle inline template implementation + */ + // Definition of inline template functions //#include "ServerSocketHandle.ih" diff --git a/Socket/ServerSocketHandle.hh b/Socket/ServerSocketHandle.hh index 40ce4bb..0c58c00 100644 --- a/Socket/ServerSocketHandle.hh +++ b/Socket/ServerSocketHandle.hh @@ -20,6 +20,10 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief senf::ServerSocketHandle public header + */ + #ifndef HH_ServerSocketHandle_ #define HH_ServerSocketHandle_ 1 @@ -40,16 +44,33 @@ namespace senf { template class ClientSocketHandle; - /** \brief + /** \brief Generic SocketHandle with server interface + + This class provides the server side policy interface of the socket abstraction. + ServerSocketHandle defines the complete policy interface. It does not implement any + functionality itself however. All calls are forwarded to the following policy classes: - +
senf::ServerSocketHandle::bind AddressingPolicy::bind (\ref senf::AddressingPolicyBase)
senf::ServerSocketHandle::listen CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)
senf::ServerSocketHandle::local AddressingPolicy::local (\ref senf::AddressingPolicyBase)
senf::ServerSocketHandle::accept CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)
senf::ServerSocketHandle::acceptfrom CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)
- + + A ServerSocketHandle is only meaningful for connection oriented addressable protocols + (CommunicationPolicy is ConnectedCommunicationPolicy and AddressingPolicy is not + NoAddressingPolicy). + + It is important to note, that not all members are always accessible. Which are depends on + the \c Policy template argument. If any of the policy axis is left unspecified the + corresponding members will not be callable (you will get a compile time error). Even if + every policy axis is defined, some members might (and will) not exist if they are + meaningless for the protocol of the socket. This depends on the exact policy. + + To find out, which members are available, you have to check the documentation of the policy + classes. You can also find a summary of all members available in the leaf protocol class + documentation. */ template class ServerSocketHandle @@ -59,8 +80,15 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// // Types + /// Address type from the addressing policy typedef typename Policy::AddressingPolicy::Address Address; + /// 'Best' type for passing address as parameter + /** Depending on the type of \c Address, this will be either Address or Address + const &. See call_traits documentation in the Boost.Utility library\endlink. + */ typedef typename boost::call_traits
::param_type AddressParam; + /// Corresponding client socket handle with the same policy typedef ClientSocketHandle ClientSocketHandle; /////////////////////////////////////////////////////////////////////////// @@ -88,21 +116,75 @@ namespace senf { ///\name Server socket interface ///@{ + /** \brief Set local address + + For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set + the local address of the socket. + + \parm[in] addr Local socket address to asign + + \throws senf::SystemException + */ void bind (AddressParam addr); + + /** \brief Allow clients to connect to this server socket + + \todo This is very protocol specific, I don't want it in the policy + interface. Especially the backlog argument seems quite protocol specific to + me. However, we cannot listen() before we bind() so listen() cannot reside in the + constructor. We need to find a good solution here. + + \throws senf::SystemException + */ + // Possible solution: Make listen() an abstract method of the protocol interface, make the + // backlog parameter into a member living in the body or protocol class and set it using + // some accessor. Hmm ... this all seems somehow futile ... void listen (unsigned backlog=0); + /** \brief Query local address + + This member will return the address of the local socket in addressable protocols + (AddressingPolicy is not NoAddressingPolicy). + + There are two Variants of this member, one will return the address by value, the other + takes a reference argument to elide the copy operation. + + \throws senf::SystemException + */ Address local (); void local (Address & addr); + ///< Query local address + /**< \see \ref local() */ + + /** \brief Accept new connection + + If the handle is non-blocking, accept will NOT block. If no connection + is available to be returned, accept will return a ClientSocketHandle + which is not valid() + + \throws senf::SystemException + + This variant ... - // If the handle is non-blocking, accept will NOT block. If no connection - // is available to be returned, accept will return a ClientSocketHandle - // which is not valid() + \returns handle of new client connection + */ ClientSocketHandle accept (); std::pair - acceptfrom (); + acceptfrom (); ///< Accept new connection + /**< This variant will additionally return the remote + address of the client + \returns \c std::pair with client handle and client + address. + \see \ref accept() */ ClientSocketHandle acceptfrom (Address & addr); + ///< Accept new connection + /**< This variant will additionally return the remote + address of the client + \params[out] client address + \returns handle of new client connection + \see \ref accept() */ ///@} @@ -134,4 +216,5 @@ namespace senf { // Local Variables: // mode: c++ // c-file-style: "senf" +// fill-column: 100 // End: diff --git a/Socket/SocketHandle.hh b/Socket/SocketHandle.hh index 25225c7..3bce2a3 100644 --- a/Socket/SocketHandle.hh +++ b/Socket/SocketHandle.hh @@ -177,7 +177,9 @@ namespace senf { public: static SocketHandle cast_static(FileHandle handle); + /**< \internal */ static SocketHandle cast_dynamic(FileHandle handle); + /**< \internal */ private: diff --git a/Socket/SocketPolicy.hh b/Socket/SocketPolicy.hh index 708f18a..8dba18b 100644 --- a/Socket/SocketPolicy.hh +++ b/Socket/SocketPolicy.hh @@ -31,13 +31,13 @@ allows to treat pipes within this framework however, is this worth the effort? - \idea Creating a new Socket will create three new instances (The - handle, the body and the policy) of which two (body and - policy) live on the heap. This is expensive. We should check, - wether we can make all the policy classes to singletons and - assign the same instance to all socket bodies with the same - policy. This would reduce the number of allocations per socket - handle to one. + \idea Creating a new Socket will create 4 (!) new instances (The + handle, the body, the policy and the protocol) of which 3 + (argh) (body, policy and protocol) live on the heap. This is + expensive. We should convert all the policy classes to + singletons and assign the same instance to all socket bodies + with the same policy. This would reduce the number of heap + allocations per socket handle to two. */ /** \defgroup policy_group The Policy Framework diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh index 0335412..7b4b487 100644 --- a/Socket/SocketProtocol.hh +++ b/Socket/SocketProtocol.hh @@ -21,6 +21,18 @@ // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. /** \file + + \idea We should optimize the protocol handling. Allocating a + protocol instance for every socket body seems quite + wasteful. However I have no idea, how to access the socket + handle from within the protocol interface if the protocol + class is a singleton. Maybe, we'll have some other idea to + reduce the number of heap allocations (like deriving the + SocketProtocol class (private? protected?) from the + SocketBody. (private inheritance is a form of 'has-a' instead + of 'is-a' which would fit very well here). This would allow to + reduce the number of heap-allocations per socket to one which + is good. */ /** \defgroup protocol_group The Protocol Classes diff --git a/doclib/Doxyfile.global b/doclib/Doxyfile.global index 2e80589..900f6f0 100644 --- a/doclib/Doxyfile.global +++ b/doclib/Doxyfile.global @@ -1,6 +1,6 @@ OUTPUT_DIRECTORY = doc INPUT = . -FILE_PATTERNS = *.c *.cc *.cci *.ct *.cti *.h *.hh *.ih *.mmc *.dox +FILE_PATTERNS = *.c *.cc *.cci *.ct *.cti *.h *.hh *.ih *.mpp *.dox EXCLUDE_PATTERNS = *.test.cc *.test.hh .* *~ "#*#" IMAGE_PATH = .