senf/Socket/Mainpage.dox

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