-// $Id$
+// $Id:SocketPolicy.hh 218 2007-03-20 14:39:32Z tho $
//
// Copyright (C) 2006
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
+// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
/** \file
\brief Policy Framework public header
- \todo We should probably remove BufferingPolicy from the interface, it does not make much sense
- (how did I come to include it ??)
-
- \todo Do we want to support separate read and write policies. This allows to treat pipes within
- this framework however, is this worth the effort?
-
- \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.
+ \idea Creating a new Socket will create 3 new instances (The handle, the body, the policy) of
+ which 2 (argh) (body, policy) 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 one (which is
+ already optimized using the pool_alloc_mixin)
*/
/** \defgroup policy_group The Policy Framework
- \image html SocketPolicy.png
-
+ <div class="diamap" name="SocketPolicy">
+ <span coords="39,229,182,257">\ref WritePolicyBase</span>
+ <span coords="17,76,210,105">\ref AddressingPolicyBase</span>
+ <span coords="29,114,194,143">\ref FramingPolicyBase</span>
+ <span coords="368,0,463,28">\ref PolicyBase</span>
+ <span coords="275,2,691,185">\ref SocketPolicy</span>
+ <span coords="0,152,227,181">\ref CommunicationPolicyBase</span>
+ <span coords="41,191,180,219">\ref ReadPolicyBase</span>
+ </div>
+ \htmlonly <img src="SocketPolicy.png" border="0" alt="SocketPolicy" usemap="#SocketPolicy"> \endhtmlonly
+
\section policy_group_introduction Introduction to the Policy Framework
The policy framework conceptually implements a list of parallel inheritance hierarchies each
<dt><em>writePolicy</em></dt><dd>configures the writability of the socket</dd>
- <dt><em>bufferingPolicy</em></dt><dd>configures, if and how buffering is configured for a
- socket</dd> </dl>
-
The template senf::SocketPolicy combines these policy axis to form a concrete socket policy. In
a concrete policy, each of these policy axis is assigned a value, the policy value. This value
is identified by a class type, a policy class. E.g. possible values for <em>framingPolicy</em>
this Unspecified type, the axis is left unspecified, the concrete policy will be incomplete.
The senf::SocketPolicy template defines the behavior of a socket handle. The socket handle
- instances do not implement any socket functionality themselves instead defering the
+ instances do not implement any socket functionality themselves instead deferring the
implementation to the policy classes. The SocketHandle interface is therefore \e not implemented
using virtual members, all important socket functions can be inlined by the compiler to create
highly efficient code.
A senf::SocketPolicy instance can be incomplete. In this case it does \e not completely specify
the socket interface, it leaves some aspects open by assigning the Unspecified value to one or
more of the policy axis. A senf::SocketHandle based on such a policy will have a reduced
- interface: It will only support those members for wich the corresponding policies are defined.
+ interface: It will only support those members for which the corresponding policies are defined.
To build a senf::SocketPolicy instance the senf::MakeSocketPolicy helper is provided. This
helper template takes any number (it is really limited to 6 Arguments but more arguments don't
separately but at the same time for each policy axis:
\code
- // This defines an incomplete policy where addressingPolicy, writePolicy and bufferingPolicy
+ // This defines an incomplete policy where addressingPolicy and writePolicy
// are unspecified
typedef senf::MakeSocketPolicy<
senf::StreamFramingPolicy,
// StreamFramingPolicy,
// ConnectedCommunicationPolicy,
// ReadablePolicy,
- // WritablePolicy,
- // SocketBufferingPolicy>::policy
+ // WritablePolicy>::policy
senf::TCPv4ClientSocketHandle tcpHandle (...);
MyReadableHandle myHandle (tcpHandle); // Conversion to more basic socket handle
\section policy_group_details The Policy Framework Classes
In the following discussion, deeper insight into C++ and especially the concepts of template
- meta-programming are needed. Hoewever, this information is only needed if you want to write new
+ meta-programming are needed. However, this information is only needed if you want to write new
policy classes or want to use the policy framework explicitly for your own involved
optimizations ... or if you are just plain curious :-)
In the following discussion we will use the following conventions:
\li \e Axis is one or \c AddressingPolicy, \c FramingPolicy, \c CommunicationPolicy, \c
- ReadPolicy, \c WritePolicy or \c BufferingPolicy
+ ReadPolicy or \c WritePolicy
\li \e socketPolicy is any socket policy (that is, an instantiation of the SocketPolicy
template)
\li \e trait is an any policy class (that is, any class derived from one of the axis base
<dl><dt>\c class \c SocketPolicyBase</dt> <dd>This class is the base class of the SocketPolicy
template. It is used to validate, that a class is really a SocketPolicy (by checking, that it
- derives from SocketPolicyBase. This is simpler than chacking the template directly).</dd>
+ derives from SocketPolicyBase. This is simpler than checking the template directly).</dd>
<dt>\c template \c SocketPolicy < \e addressingPolicy, \e framingPolicy, \e communicationPolicy,
- \e readPolicy, \e writePolicy, \e bufferingPolicy ></dt> <dd>This is the central SocketPolicy
+ \e readPolicy, \e writePolicy ></dt> <dd>This is the central SocketPolicy
template. It combines a complete set of policy classes, one for each axis.</dd>
<dt>\c template \c MakeSocketPolicy < \e args ></dt> <dd>\c MakeSocketPolicy is a template
arbitrary SocketPolicy. It will provide default values for unspecified axis</dd>
<dt>\c template \c SocketPolicyIsBaseOf < \e base, \e derived ></dt> <dd>This template
- metafunction will check, wether the socket policy \e derived is convertible to \e base. This
+ metafunction will check, whether the socket policy \e derived is convertible to \e base. This
means, that for each axis, the corresponding policy class in \e derived must be derived or be
the same as the one on \e base.</dd> </dl>
- \implementation All these classes are created automatically. The \c SENF_SOCKET_POLICIES makro
+ \implementation All these classes are created automatically. The \c SENF_SOCKET_POLICIES macro
is a Boost.Preprocessor style sequence listing all policy axis. The Boost.Preprocessor library
is then used to generate the respective classes.
\section policy_implement Implementing Policy Classes
- To define a new policy class, derive from the corresponding base class for your policy
- axies. The only policy axis which might possibly need to be extended are the addressing policy
- (AddressingPolicyBase) and the buffering policy (BufferingPolicyBase). See the Documentation of
- these classes for more information on which members can be implemented.
+ To define a new policy class, derive from the corresponding base class for your policy axes. The
+ only policy axis which might possibly need to be extended is the addressing policy
+ (AddressingPolicyBase). See the Documentation of these classes for more information on which
+ members can be implemented.
All members you define must be static. For any of the policy classes, you must only define those
members which are supported by your implementation. If you leave out a member you automatically
\code
struct ExampleAddressingPolicy
{
- template <class Policy>
- void connect(senf::SocketHandle<Policy> handle, Address & addr,
+ template <class SPolicy>
+ void connect(senf::SocketHandle<SPolicy> handle, Address & addr,
typename senf::IfCommmunicationPolicyIs<
- Policy, senf::ConnectedCommunicationPolicy>::type * = 0);
+ SPolicy, senf::ConnectedCommunicationPolicy>::type * = 0);
};
\endcode
template).
\see \ref extend_policy \n
- <a class="ext" href="http://www.boost.org/libs/utility/enable_if.html">The Boost enable_if utility</a> \n
- <a class="ext" href="http://www.boost.org/libs/mpl/doc/index.html">The Boost.MPL library</a> \n
- <a class="ext" href="http://www.boost.org/libs/preprocessor/doc/index.html">The Boost.Preprocessor library</a>
+ <a href="http://www.boost.org/libs/utility/enable_if.html">The Boost enable_if utility</a> \n
+ <a href="http://www.boost.org/libs/mpl/doc/index.html">The Boost.MPL library</a> \n
+ <a href="http://www.boost.org/libs/preprocessor/doc/index.html">The Boost.Preprocessor library</a>
\idea We could combine all the \e Axis \c Is templates into a single template. Since the \e
trait argument will automatically specify the axis to be used, it is not necessary to specify
- that axis in the tempalte functor's name. We could even combine this with \c
+ that axis in the template functor's name. We could even combine this with \c
SocketPolicyIsBaseOf.
*/
/** \defgroup policy_impl_group Policy Implementation classes
\ingroup policy_group
- Here you will find all policy classes. Also included are some
- supporting classes which are used as base classes to build other
- policy classes.
+ Here you will find all policy classes. Also included are some supporting classes which are used
+ as base classes to build other policy classes.
*/
#ifndef HH_SocketPolicy_
// Custom includes
-#include "GenericSockAddr.hh"
-
//#include "SocketPolicy.mpp"
///////////////////////////////hh.p////////////////////////////////////////
\internal
- This define symbol is used to configure the policy axis. The
- base class for each of these axis must be defined explicitly
- (e.g. AddressingPolicyBase). The implementation files will
- then automatically generate all the other classes from this
- list.
+ This define symbol is used to configure the policy axis. The base class for each of these
+ axis must be defined explicitly (e.g. AddressingPolicyBase). The implementation files will
+ then automatically generate all the other classes from this list.
\see policy_group
*/
(FramingPolicy) \
(CommunicationPolicy) \
(ReadPolicy) \
- (WritePolicy) \
- (BufferingPolicy)
+ (WritePolicy)
// Wer define these classes explicitly (and not with some macro
// magic) because
/** \brief Policy defining socket addressing
- AddressingPolicyBase is the baseclass of all addressing policy
- classes. When defining a new addressing policy, the following
- members can be defined. All methods must be static.
+ AddressingPolicyBase is the baseclass of all addressing policy classes. When defining a new
+ addressing policy, the following members can be defined. All methods must be static.
<table class="senf">
<tr><td>typedef</td> <td><tt>Address</tt></td> <td>Address type</td></tr>
{
virtual ~AddressingPolicyBase() {}
- typedef GenericSockAddr Address;
+ class Address { Address(); };
};
/** \brief Policy defining the framing format
- This policy does not define any operations since it does have
- no influence on any method signature. It does however affect
- the semantics of the \c read() and \c write() operations.
+ This policy does not define any operations since it does have no influence on any method
+ signature. It does however affect the semantics of the \c read() and \c write() operations.
- \note This policy axis probably only has two sensible statess:
- StreamFramingPolicy and DatagramFramingPolicy.
+ \note This policy axis probably only has two sensible states: StreamFramingPolicy and
+ DatagramFramingPolicy.
\see policy_group
*/
<table class="senf">
<tr><td>method</td> <td><tt>void listen(FileHandle, unsigned backlog)</tt></td> <td>Switch socket into listening state</td></tr>
<tr><td>method</td> <td><tt>int accept(FileHandle, Address &)</tt></td> <td>Accept a new connection</td></tr>
+ <tr><td>method</td> <td><tt>int accept(FileHandle)</tt></td> <td>Accept a new connection</td></tr>
</table>
- The \c listen member is straight forward. The \c accept() member
- must return a new file descriptor (which will be used to
- create a new SocketHandle of the correct type). Additionally,
- accept() should only be defined, if the Addressing policy is
- not \c NoAddressingPolicy (which together with
- ConnectedCommunicationPolicy would identify a point-to-point
- link with fixed communication partners).
+ The \c listen member is straight forward. The \c accept() member must return a new file
+ descriptor (which will be used to create a new SocketHandle of the correct
+ type).
- \note This Policy only has two meaningful states:
- ConnectedCommunicationPolicy and
- UnconnectedCommunicationPolicy. It is probably not sensible to
- define a new CommunicationPolicy type.
+ \note This Policy only has two meaningful states: ConnectedCommunicationPolicy and
+ UnconnectedCommunicationPolicy. It is probably not sensible to define a new
+ CommunicationPolicy type.
\see policy_group
*/
/** \brief Policy defining the readability
- The ReadPolicy defines, wether the socket is readable. It
- may define two members:
+ The ReadPolicy defines, whether the socket is readable. It may define two members:
<table class="senf">
<tr><td>method</td> <td><tt>unsigned read(FileHandle, char * buffer, unsigned size)</tt></td> <td>read data from socket</td></tr>
<tr><td>method</td> <td><tt>unsigned readfrom(FileHandle, char * buffer, unsigned size, Address &)</tt></td> <td>read data from unconnected socket</td></tr>
</table>
- The second member should only be enabled if the communication
- policy is UnconnectedCommunication (otherwise it does not make
- sense since the communication partner is fixed) (see
- AddressingPolicyBase on how to do this).
+ The second member should only be enabled if the communication policy is
+ UnconnectedCommunicationPolicy (otherwise it does not make sense since the communication partner
+ is fixed) (see AddressingPolicyBase on how to do this).
- \note This Policy only has two meaningful states:
- ReadablePolicy and NotReadablePolicy. It probably does not
- make sense to define new read policy types.
+ \note This Policy only has two meaningful states: ReadablePolicy and NotReadablePolicy. It
+ probably does not make sense to define new read policy types.
\see policy_group
*/
/** \brief Policy defining the writability
- The WritePolicy defines, wether the socket is writable. It may
- define two members:
+ The WritePolicy defines, whether the socket is writable. It may define two members:
<table class="senf">
<tr><td>method</td> <td><tt>unsigned write(FileHandle, char * buffer, unsigned size)</tt></td> <td>read data from socket</td></tr>
<tr><td>method</td> <td><tt>unsigned writeto(FileHandle, char * buffer, unsigned size, Address &)</tt></td> <td>read data from unconnected socket</td></tr>
</table>
- The second member should only be enabled if the communication
- policy is UnconnectedCommunication (otherwise it does not make
- sense since the communication partner is fixed) (see
- AddressingPolicyBase on how to do this).
+ The second member should only be enabled if the communication policy is
+ UnconnectedCommunicationPolicy (otherwise it does not make sense since the communication partner
+ is fixed) (see AddressingPolicyBase on how to do this).
- \note This Policy only has two meaningful states:
- WritablePolicy and NotWritablePolicy. It probably does not
- make sense to define new write policy types.
+ \note This Policy only has two meaningful states: WritablePolicy and NotWritablePolicy. It
+ probably does not make sense to define new write policy types.
\see policy_group
*/
virtual ~WritePolicyBase() {}
};
- /** \brief Policy defining the buffering interface
-
- The BufferingPolicy defines the buffer handling of the
- socket. It may provide the follogin members:
-
- \see policy_group
- */
- struct BufferingPolicyBase
- {
- virtual ~BufferingPolicyBase() {}
- };
-
// The implementation file will for each Policy declared above
// define the following (SomePolicy is one of the above):
//
/** \brief Check single policy axis
- This template is an example of the \e Axis \c Is family of
- tempalte metafunctions. It will check, wether \c Trait is a
- valid compatible Policy class of \c SocketPolicy. \c Trait
- must be derived from AddressingPolicyBase (respectively \i
- Policy \c Base).
+ This template is an example of the \e Axis \c Is family of template metafunctions. It will
+ check, whether \c Trait is a valid compatible Policy class of \c SocketPolicy. \c Trait must
+ be derived from AddressingPolicyBase (respectively \c Policy \c Base).
\see \ref policy_group
*/
/** \brief Enable template overload depending on policy value
- This template is an exmaple of the \c If \e Axis \c Is
- family of templates. It is used like <a class="ext"
- href="http://www.boost.org/libs/utility/enable_if.html">Boost.enable_if</a>
- to enable a templated overload only, if the AddressingPolicy
- of \e Axis is compatible with \c Trait (that is the
- AddressingPolicy of \c Policy is derived from \c Trait).
+ This template is an example of the \c If \e Axis \c Is family of templates. It is used like
+ <a href="http://www.boost.org/libs/utility/enable_if.html">Boost.enable_if</a> to enable a
+ templated overload only, if the AddressingPolicy of \e Axis is compatible with \c Trait
+ (that is the AddressingPolicy of \c Policy is derived from \c Trait).
\see policy_group
*/
\internal
- This class provides the baseclass of all socket policies
- (bundles). It serves two purposes:
- \li It allows us to easily identify a socket policy bundle by
- checking a classes baseclass.
- \li It provides an abstract (virtual) interface to access the
- policy axes
+ This class provides the baseclass of all socket policies (bundles). It serves two purposes:
+ \li It allows us to easily identify a socket policy bundle by checking a classes baseclass.
+ \li It provides an abstract (virtual) interface to access the policy axes
\see policy_group
*/
{
/** \brief Polymorphic access to policy axes
- This is an example of a policy axes accessor. It returns a
- reference to the policy axes used by the conrecte protocol
- bundle. This reference can then be checked using RTTI
+ This is an example of a policy axes accessor. It returns a reference to the policy axes
+ used by the concrete protocol bundle. This reference can then be checked using RTTI
information.
*/
AddressingPolicyBase const & theAddressingPolicy() const = 0;
/** \brief Collection of policy classes
- The SocketPolicy template defines the complete Policy used by
- the socket library. It contains one policy class for each
- policy axis. This template takes one policy from each axis as
- it's template arguments (this example implementation only has
- AddressingPolicy as an argument).
+ The SocketPolicy template defines the complete Policy used by the socket library. It
+ contains one policy class for each policy axis. This template takes one policy from each
+ axis as it's template arguments (this example implementation only has AddressingPolicy as an
+ argument).
- A SocketPolicy can be complete or incomplete. An incomplete
- SocketPolicy will have at least one axis set to \c Undefined
- \e Axis (or a generic derived class which is used to group
- some other policies but does not (completely) define the
- policy behavior). A complete SocketPolicy will have a
- concrete definition of the desired behavior for each policy
- axis.
+ A SocketPolicy can be complete or incomplete. An incomplete SocketPolicy will have at least
+ one axis set to \c Undefined \e Axis (or a generic derived class which is used to group some
+ other policies but does not (completely) define the policy behavior). A complete
+ SocketPolicy will have a concrete definition of the desired behavior for each policy axis.
\see policy_group
*/
{
/** \brief Check dynamic policy compatibility
- This method will check the socket policy \a other against
- this policy. It will check, wether \a other is a base
- policy (or the same) of this policy. This check is done
- against the \e dynamic type of \a other using RTTI. It
- will throw \c std::bad_cast, if the policy is not
- compatible.
+ This check will validate, that a socket with \a other as it's policy is convertible to a
+ socket with the current SocketPolicy as it's policy. This is true, if for each policy
+ axis, the policy class of that axis as defined in the \a other policy is convertible to
+ the policy class of that same axis in the current SocketPolicy instance (as is defined
+ by the template arguments). This again is true, if the \a other policy class is derived
+ from (or is the same as) the policy class taken from the current SocketPolicy instance.
+
+ In other words, this call checks, that the current SocketPolicy (as defined via the
+ template arguments) is more generic than the \a other socket policy.
\param[in] other SocketPolicy to check
- \throws std::bad_cast if \a other is not a compatible
- policy
+ \throws std::bad_cast if \a other is not a compatible policy
*/
static void checkBaseOf(SocketPolicyBase const & other);
};
/** \brief Metafunction to create SocketPolicy
- This template metafunction simplifies the creation of a
- SocketPolicy instantiation. It takes any number (that is up to
- 6) of Policy classes as arguments in any Order. It will create
- a SocketPolicy from these policy classes. Any axis not
- specified will be left as \c Unspecified \e Axis.
+ This template metafunction simplifies the creation of a SocketPolicy instantiation. It takes
+ any number (that is up to 6) of Policy classes as arguments in any Order. It will create a
+ SocketPolicy from these policy classes. Any axis not specified will be left as \c
+ Unspecified \e Axis.
\see policy_group
*/
/** \brief Check policy compatibility
- This tempalte metafunction checks, wether the SocketPolicy \c
- Derived is more specialized than \c Base (and therefore a
- SocketHandle with policy \c Derived is convertible to a
+ This template metafunction checks, whether the SocketPolicy \c Derived is more specialized
+ than \c Base (and therefore a SocketHandle with policy \c Derived is convertible to a
SocketHandle with policy \c Base).
- The metafunction will return true (that is inherits from \c
- boost::true_type, see the <a class="ext"
- href="http://www.boost.org/libs/mpl/doc/index.html">Boost.MPL</a>
- library documentation for more information) if each policy
- class in \c Base is a baseclass of (or the same as) the
+ The metafunction will return true (that is inherits from \c boost::true_type, see the <a
+ href="http://www.boost.org/libs/mpl/doc/index.html">Boost.MPL</a> library documentation for
+ more information) if each policy class in \c Base is a baseclass of (or the same as) the
corresponding policy class in \c Derived.
\see policy_group
// c-file-style: "senf"
// indent-tabs-mode: nil
// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// comment-column: 40
// End:
projects / senf.git / blobdiff