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
   6     abstraction of the BSD socket API. The abstraction is based on
   7     several concepts:
   8
   9     \li The basic visible interface is a \link handle_group handle
  10         object \endlink
  11     \li The socket interface relies on a \link policy_group policy
  12         framework \endlink to configure it's functionality
  13     \li The rest of the socket API is accessible using a classic
  14         inheritance hierarchy of \link protocol_group protocol classes
  15         \endlink
  16
  17     The handle/body architecture provides automatic reference counted
  18     management of socket instances, the policy framework provides
  19     highly efficient access to the most important socket functions
  20     (like reading and writing) and the inheritance hierarchy provides
  21     convenient access to the multitude of special and protocol
  22     dependent options.
  23
  24     \see \ref usage \n
  25          \ref handle_group \n
  26          \ref policy_group \n
  27          \ref protocol_group \n
  28          \ref extend \n
  29          \ref implementation
  30  */
  31
  32 /** \page usage Using the Socket Library
  33
  34     Whenever you use the socket library, what you will be dealing with
  35     are FileHandle derived instances. The socket library relies
  36     on reference counting to automatically manage the underlying
  37     socket representation. This frees you of having to manage the
  38     socket lifetime explicitly.
  39
  40     \section usage_create Creating a Socket Handle
  41
  42     To create a new socket handle (opening a socket), you will need to
  43     use ProtocolClientSocketHandle or
  44     ProtocolServerSocketHandle. You will probably not use these
  45     templates as is but use proper typedefs (for example
  46     TCPv4ClientSocketHandle or PacketSocketHandle). The
  47     documentation for these socket handles are found in the protocol
  48     class (for example TCPv4SocketProtocol or
  49     PacketProtocol).
  50
  51     \section usage_reusable Writing Reusable Components
  52
  53     To make your code more flexible, you should not pass around your
  54     socket in this form. Most of your code will be using only a small
  55     subset of the ProtocolClientSocketHandle or
  56     ProtocolServerSocketHandle API. If instead of using the
  57     fully specified handle type you use a more incomplete type, you
  58     allow your code to be used with all socket which fulfill the
  59     minimal requirements of your code.
  60
  61     This works, by defining a special reduced policy or handle for
  62     your code:
  63
  64     \code
  65       typedef ClientSocketHandle<
  66           MakeSocketPolicy<
  67               ReadablePolicy,
  68               StreamFramingPolicy,
  69               ConnectedCommunicationPolicy > > MyReadableHandle;
  70
  71     \endcode
  72
  73     This defines \c MyReadableHandle as a ClientSocketHandle
  74     which will have only read functionality. Your code expects a
  75     stream interface (in contrast to a packet or datagram based
  76     interface). You will not have \c write or \c readfrom members. \c
  77     write will be disabled since the WritePolicy is unknown, \c
  78     readfrom will be disabled since a socket with the
  79     ConnectedCommunicationPolicy does not have a \c readfrom
  80     member.
  81  */
  82
  83
  84
  85 /** \page extend Extending the Library
  86
  87     There are two layers, on which the socket library can be
  88     extended: On the protocol layer and on the policy layer. Extending
  89     the protocol layer is quite simple and works as long as the
  90     desired protocol does use the same BSD API used by the standard
  91     internet protocols as implemented in the standard policies
  92     (i.e. it uses ordinary read() and write() or rcvfrom() or sendto()
  93     calls and so on).
  94
  95     If however the implementation of a policy feature needs to be
  96     changed, a new policy class has to be written. This also is not
  97     very complicated however the integration is more complex.
  98
  99     \section extend_protocol Writing a new protocol class
 100
 101     Most protocols can be implemented by just implementing a new
 102     protocol class. The protocol class must be derived from
 103     ConcreteSocketProtocol and takes the socket policy (as
 104     created by MakeSocketPolicy) as a template argument. See the
 105     documentation of this class for the interface.
 106
 107     \attention You may want to use multiple inheritance as it is used
 108     in the implementation of the standard protocols (See \ref
 109     protocol_group). You must however be extra careful to ensure, that
 110     every class ultimately has SocketPolicy as a public \e
 111     virtual base.
 112
 113     After the protocol class has been defined, you will probably want to
 114     provide typedefs for the new protocol sockets. If the new protocol
 115     is connection oriented, this will be like
 116     \code
 117     typedef ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
 118     typedef ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
 119     \endcode
 120
 121     \section extend_policy Extending the policy framework
 122
 123     If you have to extend the policy framework, you will need to be
 124     aware of some important limitations of the socket library:
 125
 126     \li When you define a new policy for some axis, this new policy
 127         <em>must not</em> be derived from one of the existing concrete
 128         policy classes (except of course the respective policy axis
 129         base class). This is important since the policy type is \e not
 130         polymorphic. The policy to be used is selected by the compiler
 131         using the \e static type, which is exactly what is desired,
 132         since this allows calls to be efficiently inlined.
 133
 134     \li Therefore, extending the policy framework will make the new
 135         socket probably \e incompatible with generic code which relies
 136         on the policy axis which is extended. Example: If you write a
 137         new write policy because your protocol does not use ordinary
 138         write() system calls but some protocol specific API, Then any
 139         generic function relying on WritablePolicy will \e not
 140         work with the new socket, since the socket does \e not have
 141         this policy, it has some other kind of write policy.
 142
 143     Therefore you need to be careful of what you are doing. The first
 144     step is to find out, which policy you will have to implement. For
 145     this, find the ClientSocketHandle and/or
 146     ServerSocketHandle members you want to change (see \ref
 147     ClientSocketHandle and \ref ServerSocketHandle).  Not
 148     all policy axis directly contribute to the SocketHandle
 149     interface. However, some policy members additionally depend on
 150     other policy axis (example: AddressingPolicy::connect is only
 151     defined if the communication policy is
 152     ConnectedCommunication).
 153
 154     \see policy_group
 155  */
 156
 157 /** \page glossary Glossary
 158
 159     <table class="glossary">
 160
 161     <tr><td>policy</td> <td>collection of policy classes, one for each
 162     policy axis, instantiation of the SocketPolicy template</td></tr>
 163
 164     <tr><td>policy axis</td> <td>one aspect defined in the socket
 165     policy, typedef and member of the SocketPolicy template</td></tr>
 166
 167     <tr><td>policy class</td> <td>implementation of a single policy
 168     axis, class derived from the axis base class</td></tr>
 169
 170     <tr><td>complete policy</td> <td>socket policy where each
 171     axis is specified completely</td></tr>
 172
 173     <tr><td>incomplete policy</td> <td>socket policy, where at
 174     least one axis is not fully specified</td></tr>
 175
 176     <tr><td>protocol class</td> <td>definition of a protocol as a
 177     class, class inheriting from ConcreteSocketProtocol.</td></tr>
 178
 179     <tr><td>protocol facet</td> <td>a class providing some subset of
 180     the protocol interface, class derived from SocketProtocol but not
 181     from ConcreteSocketProtocol</td></tr>
 182
 183     <tr><td>policy interface</td> <td>interface directly provided by
 184     ClientSocketHandle/ServerSocketHandle and defined through the
 185     policy</td>
 186
 187     <tr><td>protocol interface</td> <td>interface provided by the
 188     protocol class and accessible via the
 189     ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol()
 190     member</td></tr>
 191
 192     </table>
 193  */
 194
 195 /** \page implementation Implementation notes
 196
 197     \section class_diagram Class Diagram
 198
 199     \image html SocketLibrary-classes.png
 200
 201     \section impl_notes Arbitrary Implementation Notes
 202
 203     \li The implementation tries to isolate the library user as much
 204         as possible from the system header files since those headers
 205         define a lot of define symbols and introduce a host of symbols
 206         into the global namespace. This is, why some classes define
 207         their own \c enum types to replace system defined define
 208         constants. This also precludes inlining some functionality.
 209
 210     \li To reduce overhead, template functions/members which are
 211         more than one-liners are often implemented in terms of a
 212         non-template function/member. This is also used to further the
 213         isolation from system headers as defined above (template code
 214         must always be included into every compilation unit together
 215         with all headers need for the implementation).
 216  */
 217
 218 }
 219
 220 \f
 221 // Local Variables:
 222 // mode: c++
 223 // fill-column: 100
 224 // c-file-style: "senf"
 225 // indent-tabs-mode: nil
 226 // ispell-local-dictionary: "american"
 227 // mode: flyspell
 228 // mode: auto-fill
 229 // End: