diff --git a/Socket/ClientSocketHandle.hh b/Socket/ClientSocketHandle.hh index 9e552104f3e809d5c9352c02cb2c9001142f1d3f..3c836a4b6d36571980129d30455b8219b0c38d5f 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 98d722ae435162309ca6a958401ef61187ce1230..1b20fdbcaa10ba4915bf603e2845d594319a9f98 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 54a32d0d7052e82603150ab8e88e3a0f6e06d062..43e81346d0088ddf0041f3edc4ea1ceed63405fe 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 Protocol> 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 SocketProtocol> 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 df539796a3505712130f5bea746fc4ca0b434a85..a7b463ac6aa20a5ce25f90ff80d8f91c9f0db853 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 <boost/preprocessor/iteration/iterate.hpp> #include <boost/preprocessor/enum.hpp> #include <boost/preprocessor/cat.hpp> -//////////////////////////////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<SocketProtocol>:: // 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<SocketProtocol>:: // ProtocolClientSocketHandle (constructor) implementation template <class SocketProtocol> -template < mpp_PCSH_TemplateParameters() > +template < mpp_TemplateParameters() > prefix_ senf::ProtocolClientSocketHandle<SocketProtocol>:: -ProtocolClientSocketHandle( mpp_PCSH_MethodParameters() ) +ProtocolClientSocketHandle( mpp_MethodParameters() ) : ClientSocketHandle<typename SocketProtocol::Policy>( std::auto_ptr<senf::SocketProtocol>(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 45be81f361d74c245aff68b7ee8692c70314beb1..2fd0720b31f485e808c5e81b6952b0415f3fe521 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 002e2097006d64e524ad3f6146d01f3a5a23a9a2..a60c6c12aa787f375e0e87531392752664904640 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 Protocol> 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 SocketProtocol> 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<SocketProtocol> 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 101d41b59e5f662145330fe97745c18f3f10913c..40a8e565bceeec234bba59cc925c5153fef58d4e 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 37bbe4486c034c0aed9ab78cb1d308143194891d..643e477deb4ab4a003b55d205a9e8429a25a0f2b 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 40ce4bb85d5868ec28983c210ad1b1443733a6fb..0c58c00ebfeef4685afa3d55b0f53dd58e17f48d 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 Policy> 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: - <table> + <table class="senf"> <tr><td>senf::ServerSocketHandle::bind</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr> <tr><td>senf::ServerSocketHandle::listen</td> <td>CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)</td></tr> <tr><td>senf::ServerSocketHandle::local</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr> <tr><td>senf::ServerSocketHandle::accept</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr> <tr><td>senf::ServerSocketHandle::acceptfrom</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr> </table> - + + 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 Policy> 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 <tt>Address</tt> or <tt>Address + const &</tt>. See <a href="http://www.boost.org/libs/utility/call_traits.htm" + class="ext">call_traits documentation in the Boost.Utility library\endlink.</a> + */ typedef typename boost::call_traits<Address>::param_type AddressParam; + /// Corresponding client socket handle with the same policy typedef ClientSocketHandle<Policy> 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<ClientSocketHandle, Address> - 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 25225c71b91501ea8a09ba330920df999437666d..3bce2a31ca13769f83338998bec1d58468b4d1e8 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 708f18a3125fb7eabe23b48e228139efc6d6b335..8dba18b1c02f00daaa2c1c7dcd10b2e2a282f5d4 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 0335412b41cfd504de9b7318c40733554ebb87f6..7b4b48780556138707a7472f8d33bb4fe208b482 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 2e805893b13df54fb92f717ffe5c66a24d1475cb..900f6f00ba6ee27a6675ee6c1581e15cf3d9a2b2 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 = .