Skip to content
Snippets Groups Projects
Commit 75df0151 authored by g0dil's avatar g0dil
Browse files

Added further Policy Framework clarification 

More layout fixes using XSLT
parent b3fbb1c7
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Mainpage.dox
+ 3
− 3
View file @ 75df0151
......@@ -278,9 +278,9 @@
</pre>
\see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
<a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
<a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
<a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
<a href="http://www.scons.org/documentation.php">SCons documentation</a> \n
<a href="http://svnbook.red-bean.com">Subversion online book</a> \n
<a href="http://subversion.tigris.org">Subversion Homepage</a>
*/
/** \page overview Introduction to the framework
......
Socket/ClientSocketHandle.hh
+ 3
− 2
View file @ 75df0151
......@@ -100,8 +100,9 @@ namespace senf {
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>
const &</tt>. See <a
href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
the Boost.Utility library\endlink.</a>
*/
typedef typename boost::call_traits<Address>::param_type AddressParam;
/// Corresponding server socket handle with the same policy
......
Socket/Mainpage.dox
+ 17
− 9
View file @ 75df0151
......@@ -70,13 +70,20 @@ namespace senf {
defined match those defined in that Socket's protocol. Using such a generic handle decouples the
implementation parts using this handle from the other socket aspects (e.g. you may define a
generic socket handle for TCP based communication leaving the addressingPolicy undefined which
makes your code independent of the type of addressing, IPv4 or IPv6).
makes your code independent of the type of addressing, IPv4 or IPv6).
This can be described as generalized compile-time polymorphism: A base class reference to some
derived class will only give access to a reduced interface (the base class interface) of a
class. The class still is of it's derived type (and inherently has the complete interface) but
only part of it is accessible via the base class reference. Likewise a generic handle (aka base
class reference) will only provide a reduced interface (aka base class interface) to the derived
class instance (aka socket).
\section over_protocol The Protocol Interface
The protocol interface is provided by a set of <em>protocol facets</em>. Each facet provides a
part of the interface. Whereas the policy interface is strictly defined (the number and type of
policy axis is fixed and also the possible members provided by the policy interface is fixed),
policy axis is fixed and also the possible members provided by the policy interface are fixed),
the protocol interface is much more flexible. Any member needed to provide a complete API for
the specific protocol may be defined, the number and type of facets combined to provide the
complete interface is up to the Protocol implementor. This flexibility is necessary to provide a
......@@ -84,9 +91,9 @@ namespace senf {
However this flexibility comes at a cost: To access the protocol interface the user must know
the exact protocol of the socket. With other words, the protocol is only accessible if the
handle you use is a protocol specific handle. A protocol specific Handle differs from a generic
Handle in two ways: It always \e must have a complete policy and it has an additional reference
to the protocol type of the socket. This reference gives access to the complete policy
handle you use is a <em>protocol specific</em> handle. A protocol specific Handle differs from a
generic Handle in two ways: It always has a complete policy and it knows the exact protocol type
of the socket (which generic handles don't). This allows to access to the complete protocol
interface.
\section over_impl Implementation of the Socket Libarary Structure
......@@ -96,13 +103,14 @@ namespace senf {
outside visible. The Handle is provided by a hierarchy of handle templates. Each Handle template
uses template arguments for the policy and/or protocol as needed (see \ref handle_group).
The Handle hierarchy divides the interface into two separate strains: the client interface
(senf::ClientSocketHandle and senf::ProtocolClientSocketHandle) provides the interface of a
client socket whereas the server interface (senf::ServerSocketHandle and
senf::ProtocolServerSocketHandle) provides the interface as used by server sockets.
The protocol interface is implemented using inheritance: The Protocol class inherits from each
protocol facet using multiple (virtual public) inheritance. The Protocol class therefore
provides the complete protocol API in a unified (see \ref protocol_group).
The Handle references the policy and the protocol only via it's template argument, the
information is part of the type. This information is not available as a data member in the
Handle object.
*/
/** \page usage Using the Socket Library
......
Socket/ServerSocketHandle.hh
+ 5
− 5
View file @ 75df0151
......@@ -84,8 +84,9 @@ namespace senf {
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>
const &</tt>. See <a
href="http://www.boost.org/libs/utility/call_traits.htm">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
......@@ -158,9 +159,8 @@ namespace senf {
/** \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()
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
......
Socket/SocketPolicy.hh
+ 70
− 103
View file @ 75df0151
......@@ -221,9 +221,9 @@
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
......@@ -234,9 +234,8 @@
/** \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_
......@@ -261,11 +260,9 @@ namespace senf {
\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
*/
......@@ -284,9 +281,8 @@ namespace senf {
/** \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>
......@@ -307,12 +303,11 @@ namespace senf {
/** \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 statess: StreamFramingPolicy and
DatagramFramingPolicy.
\see policy_group
*/
......@@ -330,18 +325,15 @@ namespace senf {
<tr><td>method</td> <td><tt>int accept(FileHandle, Address &)</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). 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).
\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
*/
......@@ -352,22 +344,19 @@ namespace senf {
/** \brief Policy defining the readability
The ReadPolicy defines, wether the socket is readable. It
may define two members:
The ReadPolicy defines, wether 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
UnconnectedCommunication (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
*/
......@@ -378,22 +367,19 @@ namespace senf {
/** \brief Policy defining the writability
The WritePolicy defines, wether the socket is writable. It may
define two members:
The WritePolicy defines, wether 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
UnconnectedCommunication (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
*/
......@@ -404,8 +390,8 @@ namespace senf {
/** \brief Policy defining the buffering interface
The BufferingPolicy defines the buffer handling of the
socket. It may provide the follogin members:
The BufferingPolicy defines the buffer handling of the socket. It may provide the follogin
members:
\see policy_group
*/
......@@ -441,11 +427,9 @@ namespace senf {
/** \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 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).
\see \ref policy_group
*/
......@@ -455,12 +439,10 @@ namespace senf {
/** \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 exmaple 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
*/
......@@ -479,12 +461,9 @@ namespace senf {
\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
*/
......@@ -492,9 +471,8 @@ namespace senf {
{
/** \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 conrecte protocol bundle. This reference can then be checked using RTTI
information.
*/
AddressingPolicyBase const & theAddressingPolicy() const = 0;
......@@ -502,19 +480,15 @@ namespace senf {
/** \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
*/
......@@ -523,27 +497,23 @@ namespace senf {
{
/** \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 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
\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
*/
......@@ -553,16 +523,13 @@ namespace senf {
/** \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 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
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
......
doclib/doxy-header-overview.html
+ 3
− 3
View file @ 75df0151
......@@ -31,8 +31,8 @@ div.tabs ul li.$projectname a { background-color: #EDE497; }
<div class="tabs">
<ul>
<li><a href="xref.html">Open Issues</a></li>
<li><a class="ext" href="http://svn.berlios.de/wsvn/senf/?op=log&rev=0&sc=0&isdir=1">SVN ChangeLog</a></li>
<li><a class="ext" href="http://developer.berlios.de/projects/senf">SENF @ BerliOS</a></li>
<li><a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">Wiki</a></li>
<li><a href="http://svn.berlios.de/wsvn/senf/?op=log&rev=0&sc=0&isdir=1">SVN ChangeLog</a></li>
<li><a href="http://developer.berlios.de/projects/senf">SENF @ BerliOS</a></li>
<li><a href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">Wiki</a></li>
</ul>
</div>
\ No newline at end of file
doclib/html-munge.xsl
+ 18
− 0
View file @ 75df0151
......@@ -57,4 +57,22 @@
</xsl:call-template>
</xsl:template>
<xsl:template match="a[@href=string(current())]" priority="1">
<xsl:call-template name="add-class">
<xsl:with-param name="class">literal</xsl:with-param>
</xsl:call-template>
</xsl:template>
<xsl:template match="a[contains(@href,'http://')]">
<xsl:call-template name="add-class">
<xsl:with-param name="class">ext</xsl:with-param>
</xsl:call-template>
</xsl:template>
<xsl:template match="a[not(@href)]">
<xsl:call-template name="add-class">
<xsl:with-param name="class">anchor</xsl:with-param>
</xsl:call-template>
</xsl:template>
</xsl:stylesheet>
doclib/senf.css
+ 6
− 1
View file @ 75df0151
......@@ -52,7 +52,7 @@ a {
text-decoration: none;
}
a:contains("http://") {
a.literal {
font-weight: normal;
}
......@@ -60,6 +60,11 @@ a.ext {
font-style: italic;
}
a.anchor {
color: inherit;
background-color: white !important;
}
div.tabs {
display: inline; /* IE double margin fix */
float: left;
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Datenschutz und Impressum