Socket/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 namespace senf {
  24
  25 /** \mainpage The SENF Socket Library
  26
  27     The Socket library provides a high level and object oriented abstraction of the BSD socket
  28     API. The abstraction is based on several concepts:
  29
  30     \li The basic visible interface is a \link handle_group handle object \endlink
  31     \li The socket interface relies on a \link policy_group policy framework \endlink to configure
  32         it's functionality
  33     \li The rest of the socket API is accessible using a classic inheritance hierarchy of \link
  34         protocol_group protocol classes \endlink
  35
  36     The handle/body architecture provides automatic reference counted management of socket
  37     instances, the policy framework provides highly efficient access to the most important socket
  38     functions (like reading and writing) and the inheritance hierarchy provides convenient access to
  39     the multitude of special and protocol dependent options.
  40
  41     \see
  42         \ref structure \n
  43         \ref usage \n
  44         \ref handle_group \n
  45         \ref policy_group \n
  46         \ref protocol_group \n
  47         \ref addr_group \n
  48         \ref extend \n
  49         \ref implementation
  50  */
  51
  52 /** \page structure Overview of the Socket Library Structure
  53
  54     \image html Handle.png
  55
  56     This diagram tries to give a structural overview of the Socket Library, it does \e not directly
  57     show, how the library is implemented. This will be explained later.
  58
  59     The outside interface to the library is a Handle object. This is the only object, the library
  60     user directly interacts with. Every handle references some socket. This is like the ordinary
  61     POSIX API: the file descriptor (also called file handle, an integer number) references a socket
  62     structure which lives in kernel space. In this library, the Handle object (which is not a simple
  63     integer any more but an object) references the Socket (which is part of the
  64     implementation). Several handles may reference the same Socket. In contrast to the kernel API,
  65     the library employs reference counting to release a socket when the last Handle to it goes out
  66     of scope.
  67
  68     The behavior of a Socket is defined by it's Protocol. It is divided into two parts: the
  69     <em>policy interface</em> and the <em>protocol interface</em>. Together they provide the
  70     complete API for a specific type of Socket as defined by the Protocol. The <em>policy
  71     interface</em> provides highly efficient access to the most frequently used operations whereas
  72     the <em>protocol interface</em> completes the interface by providing a complete set of all
  73     protocol specific operations not found in the policy interface. This structure allows us to
  74     combine the benefits of two design methodologies: The policy interface utilizes a policy based
  75     design technique and is highly efficient albeit more complex to implement, whereas the protocol
  76     interface is based on a more common inheritance architecture which is not as optimized for
  77     performance but much simpler to implement. We reduce the complexity of the implementation by
  78     reducing the policy interface to a minimal sensible subset of the complete API.
  79
  80     \section over_policy The Policy Interface
  81
  82     The policy of a Socket consists of several parts, called <em>policy axis</em>. Each axis
  83     corresponds to one specific interface aspect of the Socket. The exact meaning of the policy axis
  84     are defined elsewhere (see \ref policy_group). The Protocol will always provide a complete set
  85     of <em>policy classes</em>, one for each axis.
  86
  87     This <em>complete socket policy</em> defines the policy interface of the protocol. This
  88     interface is carried over into the Handle. The socket policy as defined in the Handle however
  89     may be <em>incomplete</em>. This mans, that the \e accessible interface of the Socket depends on
  90     the type of Handle used. The inherent interface does not change but the view of this interface
  91     does if the Handle does not provide the \e complete policy interface. This feature is very
  92     important. It allows to define generic Handle types. A generic Handle with an incompletely
  93     defined policy can point to an arbitrary Socket as long as all those policy axis which \e are
  94     defined match those defined in that Socket's protocol. Using such a generic handle decouples the
  95     implementation parts using this handle from the other socket aspects (e.g. you may define a
  96     generic socket handle for TCP based communication leaving the addressingPolicy undefined which
  97     makes your code independent of the type of addressing, IPv4 or IPv6).
  98
  99     This can be described as generalized compile-time polymorphism: A base class reference to some
 100     derived class will only give access to a reduced interface (the base class interface) of a
 101     class. The class still is of it's derived type (and inherently has the complete interface) but
 102     only part of it is accessible via the base class reference. Likewise a generic handle (aka base
 103     class reference) will only provide a reduced interface (aka base class interface) to the derived
 104     class instance (aka socket).
 105
 106     \section over_protocol The Protocol Interface
 107
 108     The protocol interface is provided by a set of <em>protocol facets</em>. Each facet provides a
 109     part of the interface. Whereas the policy interface is strictly defined (the number and type of
 110     policy axis is fixed and also the possible members provided by the policy interface are fixed),
 111     the protocol interface is much more flexible. Any member needed to provide a complete API for
 112     the specific protocol may be defined, the number and type of facets combined to provide the
 113     complete interface is up to the Protocol implementor. This flexibility is necessary to provide a
 114     complete API for every possible protocol.
 115
 116     However this flexibility comes at a cost: To access the protocol interface the user must know
 117     the exact protocol of the socket. With other words, the protocol is only accessible if the
 118     handle you use is a <em>protocol specific</em> handle. A protocol specific Handle differs from a
 119     generic Handle in two ways: It always has a complete policy and it knows the exact protocol type
 120     of the socket (which generic handles don't). This allows to access to the complete protocol
 121     interface.
 122
 123     \section over_impl Implementation of the Socket Libarary Structure
 124
 125     In the Implementation, the socket policy is identified by an instance of the senf::SocketPolicy
 126     template. The Socket representation is internally represented in a senf::SocketBody which is not
 127     outside visible. The Handle is provided by a hierarchy of handle templates. Each Handle template
 128     uses template arguments for the policy and/or protocol as needed (see \ref handle_group).
 129
 130     The Handle hierarchy divides the interface into two separate strains: the client interface
 131     (senf::ClientSocketHandle and senf::ProtocolClientSocketHandle) provides the interface of a
 132     client socket whereas the server interface (senf::ServerSocketHandle and
 133     senf::ProtocolServerSocketHandle) provides the interface as used by server sockets.
 134
 135     The protocol interface is implemented using inheritance: The Protocol class inherits from each
 136     protocol facet using multiple (virtual public) inheritance. The Protocol class therefore
 137     provides the complete protocol API in a unified (see \ref protocol_group).
 138  */
 139
 140 /** \page usage Using the Socket Library
 141
 142     Whenever you use the socket library, what you will be dealing with are FileHandle derived
 143     instances. The socket library relies on reference counting to automatically manage the
 144     underlying socket representation. This frees you of having to manage the socket lifetime
 145     explicitly.
 146
 147     \section usage_create Creating a Socket Handle
 148
 149     To create a new socket handle (opening a socket), you will need to use
 150     ProtocolClientSocketHandle or ProtocolServerSocketHandle. You will probably not use these
 151     templates as is but use proper typedefs (for example TCPv4ClientSocketHandle or
 152     PacketSocketHandle). The documentation for these socket handles are found in the protocol class
 153     (for example TCPv4SocketProtocol or PacketProtocol).
 154
 155     \section usage_reusable Writing Reusable Components
 156
 157     To make your code more flexible, you should not pass around your socket in this form. Most of
 158     your code will be using only a small subset of the ProtocolClientSocketHandle or
 159     ProtocolServerSocketHandle API.
 160
 161     If instead of using the fully specified handle type you use a more incomplete type, you allow
 162     your code to be used with all sockets which fulfill the minimal requirements of your code. These
 163     types are based on the ClientSocketHandle and ServerSocketHandle templates which implement the
 164     policy interface without providing the concrete protocol interface.  To use those templates you
 165     may define a special reduced policy or handle for your code. By giving only an incomplete policy
 166     you thereby reduce the interface to that required by your module:
 167
 168     \code
 169       typedef ClientSocketHandle<
 170           MakeSocketPolicy<
 171               ReadablePolicy,
 172               StreamFramingPolicy,
 173               ConnectedCommunicationPolicy > > MyReadableHandle;
 174
 175     \endcode
 176
 177     This defines \c MyReadableHandle as a ClientSocketHandle which will have only read
 178     functionality. Your code expects a stream interface (in contrast to a packet or datagram based
 179     interface). You will not have \c write or \c readfrom members. \c write will be disabled since
 180     the WritePolicy is unknown, \c readfrom will be disabled since a socket with the
 181     ConnectedCommunicationPolicy does not have a \c readfrom member.
 182
 183     \see
 184         \ref policy_group \n
 185         \ref handle_group \n
 186         \ref protocol_group
 187  */
 188
 189 /** \page extend Extending the Library
 190
 191     There are two layers, on which the socket library can be extended: On the protocol layer and on
 192     the policy layer. Extending the protocol layer is quite simple and works as long as the desired
 193     protocol does use the same BSD API used by the standard internet protocols as implemented in the
 194     standard policies (i.e. it uses ordinary read() and write() or rcvfrom() or sendto() calls and
 195     so on).
 196
 197     If however the implementation of a policy feature needs to be changed, a new policy class has to
 198     be written. This also is not very complicated however the integration is more complex.
 199
 200     \section extend_protocol Writing a new protocol class
 201
 202     Most protocols can be implemented by just implementing a new protocol class. The protocol class
 203     must be derived from ConcreteSocketProtocol and takes the socket policy (as created by
 204     MakeSocketPolicy) as a template argument. See the documentation of this class for the interface.
 205
 206     \attention You may want to use multiple inheritance as it is used in the implementation of the
 207     standard protocols (See \ref protocol_group). You must however be extra careful to ensure, that
 208     every class ultimately has SocketPolicy as a public \e virtual base.
 209
 210     After the protocol class has been defined, you will probably want to provide typedefs for the
 211     new protocol sockets. If the new protocol is connection oriented, this will be like
 212     \code
 213     typedef ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
 214     typedef ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
 215     \endcode
 216
 217     \section extend_policy Extending the policy framework
 218
 219     If you have to extend the policy framework, you will need to be aware of some important
 220     limitations of the socket library:
 221
 222     \li When you define a new policy for some axis, this new policy <em>must not</em> be derived
 223         from one of the existing concrete policy classes (except of course the respective policy
 224         axis base class). This is important since the policy type is \e not polymorphic. The policy
 225         to be used is selected by the compiler using the \e static type, which is exactly what is
 226         desired, since this allows calls to be efficiently inlined.
 227
 228     \li Therefore, extending the policy framework will make the new socket probably \e incompatible
 229         with generic code which relies on the policy axis which is extended. Example: If you write a
 230         new write policy because your protocol does not use ordinary write() system calls but some
 231         protocol specific API, Then any generic function relying on WritablePolicy will \e not work
 232         with the new socket, since the socket does \e not have this policy, it has some other kind
 233         of write policy.
 234
 235     Therefore you need to be careful of what you are doing. The first step is to find out, which
 236     policy you will have to implement. For this, find the ClientSocketHandle and/or
 237     ServerSocketHandle members you want to change (see \ref ClientSocketHandle and \ref
 238     ServerSocketHandle).  Not all policy axis directly contribute to the SocketHandle
 239     interface. However, some policy members additionally depend on other policy axis (example:
 240     AddressingPolicy::connect is only defined if the communication policy is
 241     ConnectedCommunication).
 242
 243     \see policy_group
 244  */
 245
 246 /** \page glossary Glossary
 247
 248     <table class="glossary">
 249
 250     <tr><td>policy</td> <td>collection of policy classes, one for each policy axis, instantiation of
 251     the SocketPolicy template</td></tr>
 252
 253     <tr><td>policy axis</td> <td>one aspect defined in the socket policy, typedef and member of the
 254     SocketPolicy template</td></tr>
 255
 256     <tr><td>policy class</td> <td>implementation of a single policy axis, class derived from the
 257     axis base class</td></tr>
 258
 259     <tr><td>complete policy</td> <td>socket policy where each axis is specified completely</td></tr>
 260
 261     <tr><td>incomplete policy</td> <td>socket policy, where at least one axis is not fully
 262     specified</td></tr>
 263
 264     <tr><td>protocol class</td> <td>definition of a protocol as a class, class inheriting from
 265     ConcreteSocketProtocol.</td></tr>
 266
 267     <tr><td>protocol facet</td> <td>a class providing some subset of the protocol interface, class
 268     derived from SocketProtocol but not from ConcreteSocketProtocol</td></tr>
 269
 270     <tr><td>policy interface</td> <td>interface directly provided by
 271     ClientSocketHandle/ServerSocketHandle and defined through the policy</td>
 272
 273     <tr><td>protocol interface</td> <td>interface provided by the protocol class and accessible via
 274     the ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol()
 275     member</td></tr>
 276
 277     </table>
 278  */
 279
 280 /** \page implementation Implementation notes
 281
 282     \section class_diagram Class Diagram
 283
 284     \image html SocketLibrary-classes.png
 285
 286     \section impl_notes Arbitrary Implementation Notes
 287
 288     \li The implementation tries to isolate the library user as much as possible from the system
 289         header files since those headers define a lot of define symbols and introduce a host of
 290         symbols into the global namespace. This is, why some classes define their own \c enum types
 291         to replace system defined define constants. This also precludes inlining some functionality.
 292
 293     \li To reduce overhead, template functions/members which are more than one-liners are often
 294         implemented in terms of a non-template function/member. This is also used to further the
 295         isolation from system headers as defined above (template code must always be included into
 296         every compilation unit together with all headers need for the implementation).
 297  */
 298
 299 }
 300
 301 \f
 302 // Local Variables:
 303 // mode: c++
 304 // fill-column: 100
 305 // c-file-style: "senf"
 306 // indent-tabs-mode: nil
 307 // ispell-local-dictionary: "american"
 308 // mode: flyspell
 309 // mode: auto-fill
 310 // End: