+namespace senf {
+
/** \mainpage The SENF Socket Library
The Socket library provides a high level and object oriented
several concepts:
\li The basic visible interface is a \link handle_group handle
- object \endlink
+ object \endlink
\li The socket interface relies on a \link policy_group policy
- framework \endlink to configure it's functionality
+ framework \endlink to configure it's functionality
\li The rest of the socket API is accessible using a classic
- inheritance hierarchy of \link protocol_group protocol classes
- \endlink
+ inheritance hierarchy of \link protocol_group protocol classes
+ \endlink
The handle/body architecture provides automatic reference counted
management of socket instances, the policy framework provides
\ref handle_group \n
\ref policy_group \n
\ref protocol_group \n
- \ref extend \n
+ \ref extend \n
\ref implementation
*/
/** \page usage Using the Socket Library
Whenever you use the socket library, what you will be dealing with
- are senf::FileHandle derived instances. The socket library relies
+ are FileHandle derived instances. The socket library relies
on reference counting to automatically manage the underlying
socket representation. This frees you of having to manage the
socket lifetime explicitly.
\section usage_create Creating a Socket Handle
To create a new socket handle (opening a socket), you will need to
- use senf::ProtocolClientSocketHandle or
- senf::ProtocolServerSocketHandle. You will probably not use these
+ use ProtocolClientSocketHandle or
+ ProtocolServerSocketHandle. You will probably not use these
templates as is but use proper typedefs (for example
- senf::TCPv4ClientSocketHandle or senf::PacketSocketHandle). The
+ TCPv4ClientSocketHandle or PacketSocketHandle). The
documentation for these socket handles are found in the protocol
- class (for example senf::TCPv4SocketProtocol or
- senf::PacketProtocol).
+ class (for example TCPv4SocketProtocol or
+ PacketProtocol).
\section usage_reusable Writing Reusable Components
To make your code more flexible, you should not pass around your
socket in this form. Most of your code will be using only a small
- subset of the senf::ProtocolClientSocketHandle or
- senf::ProtocolServerSocketHandle API. If instead of using the
+ subset of the ProtocolClientSocketHandle or
+ ProtocolServerSocketHandle API. If instead of using the
fully specified handle type you use a more incomplete type, you
allow your code to be used with all socket which fulfill the
minimal requirements of your code.
your code:
\code
- typedef senf::ClientSocketHandle<
- senf::MakeSocketPolicy<
- senf::ReadablePolicy,
- senf::StreamFramingPolicy,
- senf::ConnectedCommunicationPolicy > > MyReadableHandle;
-
+ typedef ClientSocketHandle<
+ MakeSocketPolicy<
+ ReadablePolicy,
+ StreamFramingPolicy,
+ ConnectedCommunicationPolicy > > MyReadableHandle;
+
\endcode
- This defines \c MyReadableHandle as a senf::ClientSocketHandle
+ This defines \c MyReadableHandle as a ClientSocketHandle
which will have only read functionality. Your code expects a
stream interface (in contrast to a packet or datagram based
interface). You will not have \c write or \c readfrom members. \c
write will be disabled since the WritePolicy is unknown, \c
readfrom will be disabled since a socket with the
- senf::ConnectedCommunicationPolicy does not have a \c readfrom
+ ConnectedCommunicationPolicy does not have a \c readfrom
member.
*/
-
+
/** \page extend Extending the Library
-
+
There are two layers, on which the socket library can be
extended: On the protocol layer and on the policy layer. Extending
the protocol layer is quite simple and works as long as the
very complicated however the integration is more complex.
\section extend_protocol Writing a new protocol class
-
+
Most protocols can be implemented by just implementing a new
protocol class. The protocol class must be derived from
- senf::ConcreteSocketProtocol and takes the socket policy (as
- created by senf::MakeSocketPolicy) as a template argument. See the
+ ConcreteSocketProtocol and takes the socket policy (as
+ created by MakeSocketPolicy) as a template argument. See the
documentation of this class for the interface.
- \attention
- You may want to use multiple inheritance as it is used in the
- implementation of the standard protocols (See \ref
- protocol_interface). You must however be extra careful to ensure,
- that every class ultimately has senf::SocketPolicy as a public
- \e virtual base.
+ \attention You may want to use multiple inheritance as it is used
+ in the implementation of the standard protocols (See \ref
+ protocol_group). You must however be extra careful to ensure, that
+ every class ultimately has SocketPolicy as a public \e
+ virtual base.
After the protocol class has been defined, you will probably want to
provide typedefs for the new protocol sockets. If the new protocol
is connection oriented, this will be like
- <code>
- typedef senf::ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
- typedef senf::ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
- </code>
+ \code
+ typedef ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
+ typedef ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
+ \endcode
\section extend_policy Extending the policy framework
aware of some important limitations of the socket library:
\li When you define a new policy for some axis, this new policy
- <em>must not</em> be derived from one of the existing concrete
- policy classes (except of course the respective policy axis
- base class). This is important since the policy type is \e not
- polymorphic. The policy to be used is selected by the compiler
- using the \e static type, which is exactly what is desired,
- since this allows calls to be efficiently inlined.
+ <em>must not</em> be derived from one of the existing concrete
+ policy classes (except of course the respective policy axis
+ base class). This is important since the policy type is \e not
+ polymorphic. The policy to be used is selected by the compiler
+ using the \e static type, which is exactly what is desired,
+ since this allows calls to be efficiently inlined.
\li Therefore, extending the policy framework will make the new
- socket probably \e incompatible with generic code which relies
- on the policy axis which is extended. Example: If you write a
- new write policy because your protocol does not use ordinary
- write() system calls but some protocol specific API, Then any
- generic function relying on senf::WritablePolicy will \e not
- work with the new socket, since the socket does \e not have
- this policy, it has some other kind of write policy.
+ socket probably \e incompatible with generic code which relies
+ on the policy axis which is extended. Example: If you write a
+ new write policy because your protocol does not use ordinary
+ write() system calls but some protocol specific API, Then any
+ generic function relying on WritablePolicy will \e not
+ work with the new socket, since the socket does \e not have
+ this policy, it has some other kind of write policy.
Therefore you need to be careful of what you are doing. The first
step is to find out, which policy you will have to implement. For
- this, find the senf::ClientSocketHandle and/or
- senf::ServerSocketHandle members you want to change (see \ref
- senf::ClientSocketHandle and \ref senf::ServerSocketHandle). Not
+ this, find the ClientSocketHandle and/or
+ ServerSocketHandle members you want to change (see \ref
+ ClientSocketHandle and \ref ServerSocketHandle). Not
all policy axis directly contribute to the SocketHandle
interface. However, some policy members additionally depend on
other policy axis (example: AddressingPolicy::connect is only
\see policy_group
*/
+/** \page glossary Glossary
+
+ <table class="glossary">
+
+ <tr><td>policy</td> <td>collection of policy classes, one for each
+ policy axis, instantiation of the SocketPolicy template</td></tr>
+
+ <tr><td>policy axis</td> <td>one aspect defined in the socket
+ policy, typedef and member of the SocketPolicy template</td></tr>
+
+ <tr><td>policy class</td> <td>implementation of a single policy
+ axis, class derived from the axis base class</td></tr>
+
+ <tr><td>complete policy</td> <td>socket policy where each
+ axis is specified completely</td></tr>
+
+ <tr><td>incomplete policy</td> <td>socket policy, where at
+ least one axis is not fully specified</td></tr>
+
+ <tr><td>protocol class</td> <td>definition of a protocol as a
+ class, class inheriting from ConcreteSocketProtocol.</td></tr>
+
+ <tr><td>protocol facet</td> <td>a class providing some subset of
+ the protocol interface, class derived from SocketProtocol but not
+ from ConcreteSocketProtocol</td></tr>
+
+ <tr><td>policy interface</td> <td>interface directly provided by
+ ClientSocketHandle/ServerSocketHandle and defined through the
+ policy</td>
+
+ <tr><td>protocol interface</td> <td>interface provided by the
+ protocol class and accessible via the
+ ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol()
+ member</td></tr>
+
+ </table>
+ */
+
/** \page implementation Implementation notes
+ \section class_diagram Class Diagram
+
\image html SocketLibrary-classes.png
+
+ \section impl_notes Arbitrary Implementation Notes
+
+ \li The implementation tries to isolate the library user as much
+ as possible from the system header files since those headers
+ define a lot of define symbols and introduce a host of symbols
+ into the global namespace. This is, why some classes define
+ their own \c enum types to replace system defined define
+ constants. This also precludes inlining some functionality.
+
+ \li To reduce overhead, template functions/members which are
+ more than one-liners are often implemented in terms of a
+ non-template function/member. This is also used to further the
+ isolation from system headers as defined above (template code
+ must always be included into every compilation unit together
+ with all headers need for the implementation).
*/
+}
+
\f
// Local Variables:
// mode: c++
+// fill-column: 100
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
// mode: flyspell
// mode: auto-fill
-// ispell-local-dictionary: "american"
// End:
projects / senf.git / blobdiff