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