1 /** \mainpage The SENF Socket Library
3 The Socket library provides a high level and object oriented
4 abstraction of the BSD socket API. The abstraction is based on
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
11 \li The rest of the socket API is accessible using a classic
12 inheritance hierarchy of protocol classes
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
26 /** \page usage Using the Socket Library
28 \section socket_handle The socket handle
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.
36 \section socket_hierarchy The FileHandle hierarchy
38 \image html FhHierarchy.png
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
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).
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.
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.
70 \section policy_framework The policy framework
72 \image html SocketPolicy.png
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
82 <dt><em>addressingPolicy</em></dt>
83 <dd>configures, whether a socket is
84 addressable and if so, configures the address type</dd>
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>
90 <dt><em>communicationPolicy</em></dt>
91 <dd>configures,if and how the communication partner is
94 <dt><em>readPolicy</em></dt>
95 <dd>configures the readability of the socket</dd>
97 <dt><em>writePolicy</em></dt>
98 <dd>configures the writability of the socket</dd>
100 <dt><em>bufferingPolicy</em></dt>
101 <dd>configures, if and how buffering is configured for a socket</dd>
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).
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
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.
127 \section protocol_interface The protocol interface
129 \image html Protocols.png
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.
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.
153 /** \page extend Extending the Library
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()
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.
167 \section extend_protocol Writing a new protocol class
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.
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
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
186 typedef senf::ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
187 typedef senf::ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
190 \section extend_policy Extending the policy framework
192 If you have to extend the policy framework, you will need to be
193 aware of some important limitations of the socket library:
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.
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.
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.
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>
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).
246 /** \page implementation Implementation notes
248 \image html SocketLibrary-classes.png
256 // ispell-local-dictionary: "american"