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 policy_interface The policy interface
 128
 129     The socket handle classes and templates only implement the most
 130     important socket API methods. To access the complete API, the
 131     protocol interface is provided. Access to the protocol interface
 132     is only possible via senf::ProtocolClientSocketHandle and
 133     senf::ProtocolServerSocketHandle which have the necessary \c
 134     protocol() member. This member returns a reference to the protocol
 135     class instance which contains members covering all the API
 136     function snot found in the SocketHandle interface. The protocol
 137     interface is specific to the protocol. It's implementation is
 138     quite free. Every protocol class will define the complete and
 139     specific socket policy of it's socket handle.
 140  */
 141
 142 /** \page extend Extending the Library
 143  */
 144
 145 /** \page implementation Implementation notes
 146
 147     \image html SocketLibrary-classes.png
 148  */
 149
 150 \f
 151 // Local Variables:
 152 // mode: c++
 153 // mode: flyspell
 154 // mode: auto-fill
 155 // ispell-local-dictionary: "american"
 156 // End: