// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief SocketPolicy public header
+ \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 ??)
+ 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?
+ 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.
*/
/** \defgroup policy_group The Policy Framework
Every Policy value is identified by a class type. The policy
classes themselves built an inheritance hierarchy for each policy
axis. For each policy axis, the root of this tree is the class
- named \i Policy \c Base (e.g. \p AddressingPolicyBase).
+ named \e Policy \c Base (e.g. \p AddressingPolicyBase).
The senf::SocketPolicy defines the complete policy of a socket. It
combines a set of policy classes, one for each policy
checking, that it derives from SocketPolicyBase. This is simpler
than chacking the template directly).</dd>
- <dt>\c template \c SocketPolicy < \e addressingPolicy, \e framingPolicy, \e communicationPolicy, \e readPolicy, \e writePolicy, \e bufferingPolicy ></dt>
+ <dt>\c template \c SocketPolicy < \e addressingPolicy, \e
+ framingPolicy, \e communicationPolicy, \e readPolicy, \e
+ writePolicy, \e bufferingPolicy ></dt>
<dd>This is the central SocketPolicy template. It combines a
complete set of policy classes, one for each axis.</dd>
senf::ConnectedCommunicationPolicyIs is based on the \c
boost::enable_if template).
- \see \ref policy_framework \n
- \ref extend_policy \n
+ \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>
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.
+ */
+
#ifndef HH_SocketPolicy_
#define HH_SocketPolicy_ 1
/** \brief Check single policy axis
- This template is an example of the \i Policy \c Is family of
+ This template is an example of the \e Policy \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
/** \brief Enable template overload depending on policy value
- This template is an exmaple of the \c If \i Policy \c Is
+ This template is an exmaple of the \c If \e Policy \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 \i Policy is compatible with \c Trait (that is the
+ of \e Policy is compatible with \c Trait (that is the
AddressingPolicy of \c Policy is derived from \c Trait).
\see policy_group
\internal
- This class is used to
+ 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
*/
struct SocketPolicyBase
- {};
+ {
+ /** \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
+ 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.
+ 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
- \i Policy (or a generic derived class which is used to group
+ \e Policy (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
\see policy_group
*/
- template <
- class AddressingPolicy,
- class FramingPolicy,
- class CommunicationPolicy,
- class ReadPolicy,
- class WritePolicy,
- class BufferingPolicy >
+ template < class AddressingPolicy >
struct SocketPolicy
- {};
+ {
+ /** \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.
+
+ \param[in] other SocketPolicy to check
+ \throws std::bad_cast if \a other is not a compatible
+ policy
+ */
+ static void checkBaseOf(SocketPolicyBase const & other);
+ };
/** \brief Metafunction to create SocketPolicy
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 \i Policy.
+ specified will be left as \c Unspecified \e Policy.
\see policy_group
*/
projects / senf.git / blobdiff