Socket/Mainpage.dox

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