Socket/Mainpage.dox

   1 /** \mainpage The SENF Socket Library
   2
   3     The Socket library provides a high level and object oriented
   4     abstraction of the BSD socket API. The abstraction is based on
   5     several concepts:
   6
   7     \li The basic visible interface is a handle object
   8         (senf::FileHandle and it's derived classes)
   9     \li The socket interface relies on a policy framework to configure
  10         it's functionality
  11     \li The rest of the socket API is accessible using a classic
  12         inheritance hierarchy of protocol classes
  13
  14     The handle/body architecture provides automatic reference counted
  15     management of socket instances, the policy framework provides
  16     highly efficient access to the most important socket functions
  17     (like reading and writing) and the inheritance hierarchy provides
  18     convenient access to the multitude of special and protocol
  19     dependent options.
  20
  21     \see \ref usage \n
  22          \ref extend \n
  23          \ref implementation
  24  */
  25
  26 /** \page usage Using the Socket Library
  27
  28     \section socket_handle The socket handle
  29
  30     Whenever you use the socket library, what you will be dealing with
  31     are senf::FileHandle derived instances. The socket library relies
  32     on reference counting to automatically manage the underlying
  33     socket representation. This frees you of having to manage the
  34     socket lifetime explicitly.
  35
  36     \section socket_hierarchy The FileHandle hierarchy
  37
  38     \image html FhHierarchy.png
  39
  40     The senf::FileHandle class is the base of a hierarchy of socket
  41     handle classes (realized as templates). These classes provide an
  42     interface to the complete socket API. While going down the
  43     inheritance hierarchy, the interface will be more and more
  44     complete.
  45
  46     The most complete interface is provided by
  47     senf::ProtocolClientSocketHandle and
  48     senf::ProtocolServerSocketHandle. The template Arguments specifies
  49     the Protocol class of the underlying socket type. These are the
  50     \e only classes having public constructors and are therefore the
  51     only classes, which may be created by the library user. You will
  52     normally use these classes by naming a specific socket typedef
  53     (e.g. senf::TCPv4ClientSocketHandle).
  54
  55     However, to aid writing flexible and generic code, the socket
  56     library provides the senf::ClientSocketHandle and
  57     senf::ServerSocketHandle class templates. These templates
  58     implement a family of closely related classes based on the
  59     specification of the socket policy. This policy specification may
  60     be \e incomplete (see below). Instances of
  61     senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned
  62     and converted to different ClientSocketHandle/ServerSocketHandle
  63     types as long as the policy specifications are compatible.
  64
  65     \attention It is very important, to (almost) always pass the socket
  66     handle <em>by value</em>. The socket handle is a very lightweight
  67     class and designed to be used like an ordinary built-in type. This
  68     is very important in combination with the policy interface.
  69
  70     \section policy_framework The policy framework
  71
  72     \image html SocketPolicy.png
  73
  74     The policy framework conceptually implements a list of parallel
  75     inheritance hierarchies each covering a specific interface aspect
  76     of the socket handle. The socket handle itself only provides
  77     minimal functionality. All further functionality is relayed to a
  78     policy class, or more precisely, to a group of policy classes, one
  79     for each policy axis. The policy axis are
  80
  81     <dl>
  82     <dt><em>addressingPolicy</em></dt>
  83     <dd>configures, whether a socket is
  84     addressable and if so, configures the address type</dd>
  85
  86     <dt><em>framingPolicy</em></dt>
  87     <dd>configures the type of framing the socket provides: either no
  88     framing providing a simple i/o stream or packet framing</dd>
  89
  90     <dt><em>communicationPolicy</em></dt>
  91     <dd>configures,if and how the communication partner is
  92     selected</dd>
  93
  94     <dt><em>readPolicy</em></dt>
  95     <dd>configures the readability of the socket</dd>
  96
  97     <dt><em>writePolicy</em></dt>
  98     <dd>configures the writability of the socket</dd>
  99
 100     <dt><em>bufferingPolicy</em></dt>
 101     <dd>configures, if and how buffering is configured for a socket</dd>
 102     </dl>
 103
 104     Every Policy value is identified by a class type. The policy types
 105     themselves built an inheritance hierarchy for each policy
 106     axis. For each policy axis, the root of this tree is the class
 107     named '<tt>(axis name)Base</tt>' (e.g. \p FramingPolicyBase or \p
 108     CommunicationPolicyBase) which is aliased to '<tt>Unspecified(axis
 109     name)</tt>' (e.g. \p UnspecifiedFramingPolicy or \p
 110     UnspecifiedCommunicationPolicy).
 111
 112     The senf::SocketPolicy template combines a set of policy classes,
 113     one for each policy axis. Together, they define the behavior of a
 114     socket handle. The socket handle instances do net implement any
 115     socket functionality themselves, instead defering the
 116     implementation to the socket classes. The interface is therefore
 117     \e not implemented using virtual members, all important socket
 118     functions can be inlined by the compiler to create highly
 119     efficient code.
 120
 121     Two SocketPolicy instances are considered compatible, if all
 122     policy axis are compatible. A policy axis is compatible, if one
 123     policy class is either the same as the other or derived from
 124     it. Two SocketHandle instances can be converted into each other,
 125     as long as the SocketPolicies are compatible.
 126
 127     \section protocol_interface The protocol interface
 128
 129     \image html Protocols.png
 130
 131     The socket handle classes and templates only implement the most
 132     important socket API methods using the policy framework. To access
 133     the complete API, the protocol interface is provided. Access to
 134     the protocol interface is only possible via
 135     senf::ProtocolClientSocketHandle and
 136     senf::ProtocolServerSocketHandle which have the necessary \c
 137     protocol() member. This member returns a reference to the protocol
 138     class instance which contains members covering all the API
 139     function (mostly setsockopt/getsockopt related calls) not found in
 140     the SocketHandle interface. The protocol interface is specific to
 141     the protocol. It's implementation is quite free. The standard
 142     protocols are implemented using a simple multiple-inheritance
 143     hierarchy as shown above.
 144
 145     Since the protocol class is protocol specific (how intelligent
 146     ...), the protocol class also defines the complete socket policy
 147     to be used with it's protocol. Complete meaning, that every policy
 148     axis must be assigned it's the most specific (that is derived)
 149     policy class to be used with the protocol.
 150
 151  */
 152
 153 /** \page extend Extending the Library
 154
 155     There are two layers, on which the socket library can be
 156     extended: On the protocol layer and on the policy layer. Extending
 157     the protocol layer is quite simple and works as long as the
 158     desired protocol does use the same BSD API used by the standard
 159     internet protocols as implemented in the standard policies
 160     (i.e. it uses ordinere read() and write() or rcvfrom() or sendto()
 161     calls and so on).
 162
 163     If however the implementation of a policy feature needs to be
 164     changed, a new policy class has to be written. This also is not
 165     very complicated however the integration is more complex.
 166
 167     \section extend_protocol Writing a new protocol class
 168
 169     Most protocols can be implemented by just implementing a new
 170     protocol class. The protocol class must be derived from
 171     senf::ConcreteSocketProtocol and takes the socket policy (as
 172     created by senf::MakeSocketPolicy) as a template argument. See the
 173     documentation of this class for the interface.
 174
 175     \attention
 176     You may want to use multiple inheritance as it is used in the
 177     implementation of the standard protocols (See \ref
 178     protocol_interface). You must however be extra careful to ensure,
 179     that every class ultimately has senf::SocketPolicy as a public
 180     \e virtual base.
 181
 182     After the protocol class has been defined, you will probably want to
 183     provide typedefs for the new protocol sockets. If the new protocol
 184     is connection oriented, this will be like
 185     <code>
 186     typedef senf::ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
 187     typedef senf::ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
 188     </code>
 189
 190     \section extend_policy Extending the policy framework
 191
 192     If you have to extend the policy framework, you will need to be
 193     aware of some important limitations of the socket library:
 194
 195     \li When you define a new policy for some axis, this new policy
 196         <em>must not</em> be derived from one of the existing concrete
 197         policy classes (except of course the respective policy axis
 198         base class). This is important since the policy type is \e not
 199         polymorphic. The policy to be used is selected by the compiler
 200         using the \e static type, which is exactly what is desired,
 201         since this allows calls to be efficiently inlined.
 202
 203     \li Therefore, extending the policy framework will make the new
 204         socket probably \e incompatible with generic code which relies
 205         on the policy axis which is extended. Example: If you write a
 206         new write policy because your protocol does not use ordinary
 207         write() system calls but some protocol specific API, Then any
 208         generic function relying on senf::WritablePolicy will \e not
 209         work with the new socket, since the socket does \e not have
 210         this policy, it has some other kind of write policy.
 211
 212     Therefore you need to be careful of what you are doing. The first
 213     step is to find out, which policy you will have to implement. For
 214     this, find the senf::ClientSocketHandle and/or
 215     senf::ServerSocketHandle members you want to change. The following
 216     table shows, which policy axis is responsible for which
 217     members. The policy axis base class documentation contains further
 218     information on how to implement that policy.
 219
 220     <table class="senf">
 221       <tr><th>SocketHandle member</th><th>Policy member</th></tr>
 222       <tr><td>senf::ClientSocketHandle::read</td>       <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td></tr>
 223       <tr><td>senf::ClientSocketHandle::readfrom</td>   <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td></tr>
 224       <tr><td>senf::ClientSocketHandle::write</td>      <td>WritePolicy::write (\ref senf::WritePolicyBase)</td></tr>
 225       <tr><td>senf::ClientSocketHandle::writeto</td>    <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td></tr>
 226       <tr><td>senf::ClientSocketHandle::connect</td>    <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td></tr>
 227       <tr><td>senf::ClientSocketHandle::bind</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
 228       <tr><td>senf::ClientSocketHandle::peer</td>       <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td></tr>
 229       <tr><td>senf::ClientSocketHandle::local</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
 230       <tr><td>senf::ClientSocketHandle::rcvbuf</td>     <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td></tr>
 231       <tr><td>senf::ClientSocketHandle::sndbuf</td>     <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td></tr>
 232       <tr><td>senf::ServerSocketHandle::bind</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
 233       <tr><td>senf::ServerSocketHandle::listen</td>     <td>CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)</td></tr>
 234       <tr><td>senf::ServerSocketHandle::local</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
 235       <tr><td>senf::ServerSocketHandle::accept</td>     <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
 236       <tr><td>senf::ServerSocketHandle::acceptfrom</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
 237     </table>
 238
 239     As you can see from this list, not all policy axis directly
 240     contribute to the SocketHandle interface. However, some policy
 241     members additionally depend on other policy axis (example:
 242     AddressingPolicy::connect is only defined if the communication
 243     policy is ConnectedCommunication).
 244  */
 245
 246 /** \page implementation Implementation notes
 247
 248     \image html SocketLibrary-classes.png
 249  */
 250
 251 \f
 252 // Local Variables:
 253 // mode: c++
 254 // mode: flyspell
 255 // mode: auto-fill
 256 // ispell-local-dictionary: "american"
 257 // End: