3 /** \mainpage The SENF Socket Library
5 The Socket library provides a high level and object oriented
6 abstraction of the BSD socket API. The abstraction is based on
9 \li The basic visible interface is a \link handle_group handle
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
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
27 \ref protocol_group \n
32 /** \page usage Using the Socket Library
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.
40 \section usage_create Creating a Socket Handle
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
51 \section usage_reusable Writing Reusable Components
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. If instead of using the
57 fully specified handle type you use a more incomplete type, you
58 allow your code to be used with all socket which fulfill the
59 minimal requirements of your code.
61 This works, by defining a special reduced policy or handle for
65 typedef ClientSocketHandle<
69 ConnectedCommunicationPolicy > > MyReadableHandle;
73 This defines \c MyReadableHandle as a ClientSocketHandle
74 which will have only read functionality. Your code expects a
75 stream interface (in contrast to a packet or datagram based
76 interface). You will not have \c write or \c readfrom members. \c
77 write will be disabled since the WritePolicy is unknown, \c
78 readfrom will be disabled since a socket with the
79 ConnectedCommunicationPolicy does not have a \c readfrom
85 /** \page extend Extending the Library
87 There are two layers, on which the socket library can be
88 extended: On the protocol layer and on the policy layer. Extending
89 the protocol layer is quite simple and works as long as the
90 desired protocol does use the same BSD API used by the standard
91 internet protocols as implemented in the standard policies
92 (i.e. it uses ordinary read() and write() or rcvfrom() or sendto()
95 If however the implementation of a policy feature needs to be
96 changed, a new policy class has to be written. This also is not
97 very complicated however the integration is more complex.
99 \section extend_protocol Writing a new protocol class
101 Most protocols can be implemented by just implementing a new
102 protocol class. The protocol class must be derived from
103 ConcreteSocketProtocol and takes the socket policy (as
104 created by MakeSocketPolicy) as a template argument. See the
105 documentation of this class for the interface.
107 \attention You may want to use multiple inheritance as it is used
108 in the implementation of the standard protocols (See \ref
109 protocol_group). You must however be extra careful to ensure, that
110 every class ultimately has SocketPolicy as a public \e
113 After the protocol class has been defined, you will probably want to
114 provide typedefs for the new protocol sockets. If the new protocol
115 is connection oriented, this will be like
117 typedef ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
118 typedef ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
121 \section extend_policy Extending the policy framework
123 If you have to extend the policy framework, you will need to be
124 aware of some important limitations of the socket library:
126 \li When you define a new policy for some axis, this new policy
127 <em>must not</em> be derived from one of the existing concrete
128 policy classes (except of course the respective policy axis
129 base class). This is important since the policy type is \e not
130 polymorphic. The policy to be used is selected by the compiler
131 using the \e static type, which is exactly what is desired,
132 since this allows calls to be efficiently inlined.
134 \li Therefore, extending the policy framework will make the new
135 socket probably \e incompatible with generic code which relies
136 on the policy axis which is extended. Example: If you write a
137 new write policy because your protocol does not use ordinary
138 write() system calls but some protocol specific API, Then any
139 generic function relying on WritablePolicy will \e not
140 work with the new socket, since the socket does \e not have
141 this policy, it has some other kind of write policy.
143 Therefore you need to be careful of what you are doing. The first
144 step is to find out, which policy you will have to implement. For
145 this, find the ClientSocketHandle and/or
146 ServerSocketHandle members you want to change (see \ref
147 ClientSocketHandle and \ref ServerSocketHandle). Not
148 all policy axis directly contribute to the SocketHandle
149 interface. However, some policy members additionally depend on
150 other policy axis (example: AddressingPolicy::connect is only
151 defined if the communication policy is
152 ConnectedCommunication).
157 /** \page glossary Glossary
159 <table class="glossary">
161 <tr><td>policy</td> <td>collection of policy classes, one for each
162 policy axis, instantiation of the SocketPolicy template</td></tr>
164 <tr><td>policy axis</td> <td>one aspect defined in the socket
165 policy, typedef and member of the SocketPolicy template</td></tr>
167 <tr><td>policy class</td> <td>implementation of a single policy
168 axis, class derived from the axis base class</td></tr>
170 <tr><td>complete policy</td> <td>socket policy where each
171 axis is specified completely</td></tr>
173 <tr><td>incomplete policy</td> <td>socket policy, where at
174 least one axis is not fully specified</td></tr>
176 <tr><td>protocol class</td> <td>definition of a protocol as a
177 class, class inheriting from ConcreteSocketProtocol.</td></tr>
179 <tr><td>protocol facet</td> <td>a class providing some subset of
180 the protocol interface, class derived from SocketProtocol but not
181 from ConcreteSocketProtocol</td></tr>
183 <tr><td>policy interface</td> <td>interface directly provided by
184 ClientSocketHandle/ServerSocketHandle and defined through the
187 <tr><td>protocol interface</td> <td>interface provided by the
188 protocol class and accessible via the
189 ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol()
195 /** \page implementation Implementation notes
197 \section class_diagram Class Diagram
199 \image html SocketLibrary-classes.png
201 \section impl_notes Arbitrary Implementation Notes
203 \li The implementation tries to isolate the library user as much
204 as possible from the system header files since those headers
205 define a lot of define symbols and introduce a host of symbols
206 into the global namespace. This is, why some classes define
207 their own \c enum types to replace system defined define
208 constants. This also precludes inlining some functionality.
210 \li To reduce overhead, template functions/members which are
211 more than one-liners are often implemented in terms of a
212 non-template function/member. This is also used to further the
213 isolation from system headers as defined above (template code
214 must always be included into every compilation unit together
215 with all headers need for the implementation).
225 // ispell-local-dictionary: "american"