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);
///@}
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);
// 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"
// 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
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
///////////////////////////////////////////////////////////////////////////
// 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))
///@}
///////////////////////////////////////////////////////////////////////////
- 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);
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
// 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////////////////////////////////////////
\f
// Local Variables:
// 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"
// 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
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
///////////////////////////////////////////////////////////////////////////
// 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))
///@}
///////////////////////////////////////////////////////////////////////////
- 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();
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
// 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_
// 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"
// 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
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
///////////////////////////////////////////////////////////////////////////
// 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;
///////////////////////////////////////////////////////////////////////////
///\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() */
///@}
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
public:
static SocketHandle cast_static(FileHandle handle);
+ /**< \internal */
static SocketHandle cast_dynamic(FileHandle handle);
+ /**< \internal */
private:
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
// 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
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 = .
projects / senf.git / commitdiff