4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25 /** \mainpage The SENF Socket Library
27 The Socket library provides a high level and object oriented abstraction based on the BSD socket
28 API (but not limited to it).
32 \section socket_intro Introduction
34 The socket library abstraction is based on several concepts:
36 \li The basic visible interface is a \link handle_group handle object\endlink
37 \li The socket interface relies on a \link policy_group policy framework \endlink to configure
39 \li The rest of the socket API is accessible using a classic inheritance hierarchy of \link
40 protocol_group protocol classes \endlink
41 \li There is a family of auxilliary \ref addr_group to supplement the socket library
48 \section socket_handle Socket Handles
50 The handle/body architecture provides automatic reference counted management of socket
51 instances. This is the visible interface to the socket library.
53 Each specific protocol is used primarily via a protocol specific handle (a typedef
54 symbol). However, more generic kinds of handles can be defined for more generic functionality.
58 \ref concrete_protocol_group
61 \section socket_policy The Policy interface
63 The policy framework configures the exact features, a specific type of socket handle
64 provides. This offers highly efficient access to the most important socket functions (like
65 reading and writing). The policy interface however is a \e static, non-polymorphic interface.
70 \section socket_protocol The Protocol interface
72 The protocol interface provides further protocol dependent and (possibly) polymorphic access to
73 further socket funcitonality. On the other hand, this type of interface is not as flexible,
74 generic and fast as the policy interface.
79 \section socket_addr Auxilliary Addressing classes
81 To supplement the socket library, there are a multitude of addressing classes. These come in two
83 \li Protocol specific addresses (e.g. INet4Address, MACAddress)
84 \li Socket addresses (\c sockaddr) (e.g. INet4SocketAddress, LLSocketAddress)
86 Whereas the protocol specific addresses are custom value types which represent their
87 corresponding low-level address, the socket addresses are based on the corresponding \c sockaddr
93 \section socket_further Going further
95 The socket library is highly flexible and extensible. The implementation is not restricted to
96 plain BSD sockets: Any type of read/write communication can be wrapped into the socket library
97 (one Example is the TapSocketHandle which provides access to a Linux \c tap device).
104 /** \page structure Overview of the Socket Library Structure
106 \image html Handle.png
108 This diagram tries to give a structural overview of the Socket Library, it does \e not directly
109 show, how the library is implemented. This will be explained later.
111 The outside interface to the library is a Handle object. This is the only object, the library
112 user directly interacts with. Every handle references some socket. This is like the ordinary
113 POSIX API: the file descriptor (also called file handle, an integer number) references a socket
114 structure which lives in kernel space. In this library, the Handle object (which is not a simple
115 integer any more but an object) references the Socket (which is part of the
116 implementation). Several handles may reference the same Socket. In contrast to the kernel API,
117 the library employs reference counting to release a socket when the last Handle to it goes out
120 The behavior of a Socket is defined by it's Protocol. It is divided into two parts: the
121 <em>policy interface</em> and the <em>protocol interface</em>. Together they provide the
122 complete API for a specific type of Socket as defined by the Protocol. The <em>policy
123 interface</em> provides highly efficient access to the most frequently used operations whereas
124 the <em>protocol interface</em> completes the interface by providing a complete set of all
125 protocol specific operations not found in the policy interface. This structure allows us to
126 combine the benefits of two design methodologies: The policy interface utilizes a policy based
127 design technique and is highly efficient albeit more complex to implement, whereas the protocol
128 interface is based on a more common inheritance architecture which is not as optimized for
129 performance but much simpler to implement. We reduce the complexity of the implementation by
130 reducing the policy interface to a minimal sensible subset of the complete API.
132 \section over_policy The Policy Interface
134 The policy of a Socket consists of several parts, called <em>policy axis</em>. Each axis
135 corresponds to one specific interface aspect of the Socket. The exact meaning of the policy axis
136 are defined elsewhere (see \ref policy_group). The Protocol will always provide a complete set
137 of <em>policy classes</em>, one for each axis.
139 This <em>complete socket policy</em> defines the policy interface of the protocol. This
140 interface is carried over into the Handle. The socket policy as defined in the Handle however
141 may be <em>incomplete</em>. This mans, that the \e accessible interface of the Socket depends on
142 the type of Handle used. The inherent interface does not change but the view of this interface
143 does if the Handle does not provide the \e complete policy interface. This feature is very
144 important. It allows to define generic Handle types. A generic Handle with an incompletely
145 defined policy can point to an arbitrary Socket as long as all those policy axis which \e are
146 defined match those defined in that Socket's protocol. Using such a generic handle decouples the
147 implementation parts using this handle from the other socket aspects (e.g. you may define a
148 generic socket handle for TCP based communication leaving the addressingPolicy undefined which
149 makes your code independent of the type of addressing, IPv4 or IPv6).
151 This can be described as generalized compile-time polymorphism: A base class reference to some
152 derived class will only give access to a reduced interface (the base class interface) of a
153 class. The class still is of it's derived type (and inherently has the complete interface) but
154 only part of it is accessible via the base class reference. Likewise a generic handle (aka base
155 class reference) will only provide a reduced interface (aka base class interface) to the derived
156 class instance (aka socket).
158 \section over_protocol The Protocol Interface
160 The protocol interface is provided by a set of <em>protocol facets</em>. Each facet provides a
161 part of the interface. Whereas the policy interface is strictly defined (the number and type of
162 policy axis is fixed and also the possible members provided by the policy interface are fixed),
163 the protocol interface is much more flexible. Any member needed to provide a complete API for
164 the specific protocol may be defined, the number and type of facets combined to provide the
165 complete interface is up to the Protocol implementor. This flexibility is necessary to provide a
166 complete API for every possible protocol.
168 However this flexibility comes at a cost: To access the protocol interface the user must know
169 the exact protocol of the socket. With other words, the protocol is only accessible if the
170 handle you use is a <em>protocol specific</em> handle. A protocol specific Handle differs from a
171 generic Handle in two ways: It always has a complete policy and it knows the exact protocol type
172 of the socket (which generic handles don't). This allows to access to the complete protocol
175 \section over_impl Implementation of the Socket Libarary Structure
177 In the Implementation, the socket policy is identified by an instance of the senf::SocketPolicy
178 template. The Socket representation is internally represented in a senf::SocketBody which is not
179 outside visible. The Handle is provided by a hierarchy of handle templates. Each Handle template
180 uses template arguments for the policy and/or protocol as needed (see \ref handle_group).
182 The Handle hierarchy divides the interface into two separate strains: the client interface
183 (senf::ClientSocketHandle and senf::ProtocolClientSocketHandle) provides the interface of a
184 client socket whereas the server interface (senf::ServerSocketHandle and
185 senf::ProtocolServerSocketHandle) provides the interface as used by server sockets.
187 The protocol interface is implemented using inheritance: The Protocol class inherits from each
188 protocol facet using multiple (virtual public) inheritance. The Protocol class therefore
189 provides the complete protocol API in a unified (see \ref protocol_group).
192 /** \page usage Using the Socket Library
194 Whenever you use the socket library, what you will be dealing with are FileHandle derived
195 instances. The socket library relies on reference counting to automatically manage the
196 underlying socket representation. This frees you of having to manage the socket lifetime
199 \section usage_create Creating a Socket Handle
201 To create a new socket handle (opening a socket), you will need to use
202 ProtocolClientSocketHandle or ProtocolServerSocketHandle. You will probably not use these
203 templates as is but use proper typedefs (for example TCPv4ClientSocketHandle or
204 PacketSocketHandle). The documentation for these socket handles are found in the protocol class
205 (for example TCPv4SocketProtocol or PacketSocketProtocol).
207 \section usage_reusable Writing Reusable Components
209 To make your code more flexible, you should not pass around your socket in this form. Most of
210 your code will be using only a small subset of the ProtocolClientSocketHandle or
211 ProtocolServerSocketHandle API.
213 If instead of using the fully specified handle type you use a more incomplete type, you allow
214 your code to be used with all sockets which fulfill the minimal requirements of your code. These
215 types are based on the ClientSocketHandle and ServerSocketHandle templates which implement the
216 policy interface without providing the concrete protocol interface. To use those templates you
217 may define a special reduced policy or handle for your code. By giving only an incomplete policy
218 you thereby reduce the interface to that required by your module:
221 typedef ClientSocketHandle<
225 ConnectedCommunicationPolicy > > MyReadableHandle;
229 This defines \c MyReadableHandle as a ClientSocketHandle which will have only read
230 functionality. Your code expects a stream interface (in contrast to a packet or datagram based
231 interface). You will not have \c write or \c readfrom members. \c write will be disabled since
232 the WritePolicy is unknown, \c readfrom will be disabled since a socket with the
233 ConnectedCommunicationPolicy does not have a \c readfrom member.
241 /** \page extend Extending the Library
243 There are two layers, on which the socket library can be extended: On the protocol layer and on
244 the policy layer. Extending the protocol layer is quite simple and works as long as the desired
245 protocol does use the same BSD API used by the standard internet protocols as implemented in the
246 standard policies (i.e. it uses ordinary read() and write() or rcvfrom() or sendto() calls and
249 If however the implementation of a policy feature needs to be changed, a new policy class has to
250 be written. This also is not very complicated however the integration is more complex.
252 \section extend_protocol Writing a new protocol class
254 Most protocols can be implemented by just implementing a new protocol class. The protocol class
255 must be derived from ConcreteSocketProtocol and takes the socket policy (as created by
256 MakeSocketPolicy) as a template argument. See the documentation of this class for the interface.
258 \attention You may want to use multiple inheritance as it is used in the implementation of the
259 standard protocols (See \ref protocol_group). You must however be extra careful to ensure, that
260 every class ultimately has SocketPolicy as a public \e virtual base.
262 After the protocol class has been defined, you will probably want to provide typedefs for the
263 new protocol sockets. If the new protocol is connection oriented, this will be like
265 typedef ProtocolClientSocketHandle<MySocketProtocolClass> MySocketProtocolClientSocketHandle;
266 typedef ProtocolServerSocketHandle<MySocketProtocolClass> MySocketProtocolServerSocketHandle;
269 \section extend_policy Extending the policy framework
271 If you have to extend the policy framework, you will need to be aware of some important
272 limitations of the socket library:
274 \li When you define a new policy for some axis, this new policy <em>must not</em> be derived
275 from one of the existing concrete policy classes (except of course the respective policy
276 axis base class). This is important since the policy type is \e not polymorphic. The policy
277 to be used is selected by the compiler using the \e static type, which is exactly what is
278 desired, since this allows calls to be efficiently inlined.
280 \li Therefore, extending the policy framework will make the new socket probably \e incompatible
281 with generic code which relies on the policy axis which is extended. Example: If you write a
282 new write policy because your protocol does not use ordinary write() system calls but some
283 protocol specific API, Then any generic function relying on WritablePolicy will \e not work
284 with the new socket, since the socket does \e not have this policy, it has some other kind
287 Therefore you need to be careful of what you are doing. The first step is to find out, which
288 policy you will have to implement. For this, find the ClientSocketHandle and/or
289 ServerSocketHandle members you want to change (see \ref ClientSocketHandle and \ref
290 ServerSocketHandle). Not all policy axis directly contribute to the SocketHandle
291 interface. However, some policy members additionally depend on other policy axis (example:
292 AddressingPolicy::connect is only defined if the communication policy is
293 ConnectedCommunication).
298 /** \page implementation Implementation notes
300 \section class_diagram Class Diagram
302 <div class="diamap" name="SocketLibrary-classes">
303 <span coords="472,667,559,689">\ref IPv4Protocol</span>
304 <span coords="29,773,139,794">\ref WritePolicyBase</span>
305 <span coords="97,939,238,960">\ref SocketBufferingPolicy</span>
306 <span coords="97,390,223,411">\ref NoAddressingPolicy</span>
307 <span coords="97,736,217,758">\ref NotReadablePolicy</span>
308 <span coords="418,609,613,631">\ref AdressableBSDSocketProtocol</span>
309 <span coords="18,895,153,917">\ref BufferingPolicyBase</span>
310 <span coords="22,426,148,447">\ref FramingPolicyBase</span>
311 <span coords="409,0,495,36">\ref FileBody</span>
312 <span coords="97,469,249,491">\ref DatagramFramingPolicy</span>
313 <span coords="97,317,240,339">\ref INet6AddressingPolicy</span>
314 <span coords="453,544,578,566">\ref BSDSocketProtocol</span>
315 <span coords="97,281,240,303">\ref INet4AddressingPolicy</span>
316 <span coords="452,177,706,209">\ref ProtocolServerSocketHandle</span>
317 <span coords="412,259,486,281">\ref PolicyBase</span>
318 <span coords="474,768,557,790">\ref TCPProtocol</span>
319 <span coords="97,700,197,722">\ref ReadablePolicy</span>
320 <span coords="342,249,654,411">\ref SocketPolicy</span>
321 <span coords="0,541,173,563">\ref CommunicationPolicyBase</span>
322 <span coords="640,859,736,881">\ref TCPv6Protocol</span>
323 <span coords="353,428,453,465">\ref SocketProtocol</span>
324 <span coords="97,585,297,606">\ref ConnectedCommunicationPolicy</span>
325 <span coords="172,177,420,209">\ref ProtocolClientSocketHandle</span>
326 <span coords="472,718,559,739">\ref IPv6Protocol</span>
327 <span coords="97,816,192,838">\ref WritablePolicy</span>
328 <span coords="383,62,520,98">\ref SocketBody</span>
329 <span coords="698,888,798,910">\ref PacketProtocol</span>
330 <span coords="97,852,213,874">\ref NotWritablePolicy</span>
331 <span coords="31,657,138,679">\ref ReadPolicyBase</span>
332 <span coords="213,60,369,91">\ref SocketHandle</span>
333 <span coords="197,126,385,158">\ref ClientSocketHandle</span>
334 <span coords="97,621,311,642">\ref UnconnectedCommunicationPolicy</span>
335 <span coords="567,480,786,526">\ref ConcreteSocketProtocol</span>
336 <span coords="582,830,678,852">\ref TCPv4Protocol</span>
337 <span coords="97,505,234,527">\ref StreamFramingPolicy</span>
338 <span coords="13,238,161,259">\ref AddressingPolicyBase</span>
339 <span coords="224,0,294,36">\ref FileHandle</span>
340 <span coords="97,353,222,375">\ref LLAddressingPolicy</span>
341 <span coords="476,126,671,158">\ref ServerSocketHandle</span>
343 \htmlonly <img src="SocketLibrary-classes.png" border="0" alt="SocketLibrary-classes" usemap="#SocketLibrary-classes"> \endhtmlonly
345 \section impl_notes Arbitrary Implementation Notes
347 \li The implementation tries to isolate the library user as much as possible from the system
348 header files since those headers define a lot of define symbols and introduce a host of
349 symbols into the global namespace. This is, why some classes define their own \c enum types
350 to replace system defined define constants. This also precludes inlining some functionality.
352 \li To reduce overhead, template functions/members which are more than one-liners are often
353 implemented in terms of a non-template function/member. This is also used to further the
354 isolation from system headers as defined above (template code must always be included into
355 every compilation unit together with all headers need for the implementation).
364 // c-file-style: "senf"
365 // indent-tabs-mode: nil
366 // ispell-local-dictionary: "american"
369 // compile-command: "scons -u doc"