1 // $Id:SocketPolicy.hh 218 2007-03-20 14:39:32Z tho $
4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
6 // Stefan Bund <stefan.bund@fokus.fraunhofer.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.
24 \brief Policy Framework public header
26 \todo We should probably remove BufferingPolicy from the interface, it does not make much sense
27 (how did I come to include it ??)
29 \todo Do we want to support separate read and write policies. This allows to treat pipes within
30 this framework however, is this worth the effort?
32 \idea Creating a new Socket will create 4 (!) new instances (The handle, the body, the policy
33 and the protocol) of which 3 (argh) (body, policy and protocol) live on the heap. This is
34 expensive. We should convert all the policy classes to singletons and assign the same
35 instance to all socket bodies with the same policy. This would reduce the number of heap
36 allocations per socket handle to two.
39 /** \defgroup policy_group The Policy Framework
42 <map name="socketPolicy">
43 <area shape="rect" alt="SocketPolicy" href="structsenf_1_1SocketPolicy.html" title="SocketPolicy" coords="276,90,558,213" />
44 <area shape="rect" alt="BufferingPolicyBase" href="structsenf_1_1BufferingPolicyBase.html" title="BufferingPolicyBase" coords="25,282,190,306" />
45 <area shape="rect" alt="WritePolicyBase" href="structsenf_1_1WritePolicyBase.html" title="WritePolicyBase" coords="39,243,174,268" />
46 <area shape="rect" alt="ReadPolicyBase" href="structsenf_1_1ReadPolicyBase.html" title="ReadPolicyBase" coords="42,204,174,231" />
47 <area shape="rect" alt="CommunicationPolicyBase" href="structsenf_1_1CommunicationPolicyBase.html" title="CommunicationPolicyBase" coords="0,166,215,193" />
48 <area shape="rect" alt="FramingPolicyBase" href="structsenf_1_1FramingPolicyBase.html" title="FramingPolicyBase" coords="30,129,185,155" />
49 <area shape="rect" alt="AddressingPolicyBase" href="structsenf_1_1AddressingPolicyBase.html" title="AddressingPolicyBase" coords="17,90,200,116" />
51 <img src="SocketPolicy.png" border="0" alt="Socket Policy" usemap="#socketPolicy">
54 \section policy_group_introduction Introduction to the Policy Framework
56 The policy framework conceptually implements a list of parallel inheritance hierarchies each
57 covering a specific interface aspect of the socket handle. The socket handle itself only
58 provides minimal functionality. All further functionality is relayed to a policy class, or more
59 precisely, to a group of policy classes, one for each policy axis. The policy axis are
61 <dl><dt><em>addressingPolicy</em></dt><dd>configures, whether a socket is addressable and if
62 so, configures the address type</dd>
64 <dt><em>framingPolicy</em></dt> <dd>configures the type of framing the socket provides: either
65 no framing providing a simple i/o stream or packet framing</dd>
67 <dt><em>communicationPolicy</em></dt><dd>configures,if and how the communication partner is
70 <dt><em>readPolicy</em></dt><dd>configures the readability of the socket</dd>
72 <dt><em>writePolicy</em></dt><dd>configures the writability of the socket</dd>
74 <dt><em>bufferingPolicy</em></dt><dd>configures, if and how buffering is configured for a
77 The template senf::SocketPolicy combines these policy axis to form a concrete socket policy. In
78 a concrete policy, each of these policy axis is assigned a value, the policy value. This value
79 is identified by a class type, a policy class. E.g. possible values for <em>framingPolicy</em>
80 are <tt>DatagramFramingPolicy</tt> or <tt>StreamFramingPolicy</tt> which are classes derived
81 from the axis base class <tt>FramingPolicyBase</tt>. This base class also doubles as
82 <tt>UnspecifiedFramingPolicy</tt> (which is just a typedef alias). If a policy axis is assigned
83 this Unspecified type, the axis is left unspecified, the concrete policy will be incomplete.
85 The senf::SocketPolicy template defines the behavior of a socket handle. The socket handle
86 instances do not implement any socket functionality themselves instead deferring the
87 implementation to the policy classes. The SocketHandle interface is therefore \e not implemented
88 using virtual members, all important socket functions can be inlined by the compiler to create
89 highly efficient code.
91 A senf::SocketPolicy instance can be incomplete. In this case it does \e not completely specify
92 the socket interface, it leaves some aspects open by assigning the Unspecified value to one or
93 more of the policy axis. A senf::SocketHandle based on such a policy will have a reduced
94 interface: It will only support those members for which the corresponding policies are defined.
96 To build a senf::SocketPolicy instance the senf::MakeSocketPolicy helper is provided. This
97 helper template takes any number (it is really limited to 6 Arguments but more arguments don't
98 make sense) of policy classes as it's argument. The MakeSocketPolicy helper will take the
99 arguments in the order they are specified and for each argument will check to which axis the
100 policy class belongs (by checking the base classes of that class) and assign it to the correct
101 policy axis in the senf::SocketPolicy template. If any policy axis are not specified, they are
102 defaulted to their corresponding Unspecified value. This helper frees you to specify the policy
103 classes in any order. An additional feature is, that you may specify a complete policy as a
104 first argument. This policy will then be used to provide default values for unspecified axis.
106 Two senf::SocketHandle's with different policies can be \e compatible. If they are, the more
107 specific SocketHandle can be converted (assigned to) the more basic SocketHandle. A SocketHandle
108 is more specific then another SocketHandle if the policy of the former is more specific then
109 that of the latter which means, that for each policy axis separately, the value of that axis of
110 the more specific policy is derived from or the same as the value of that axis in the more basic
111 policy. This is like converting a derived class pointer to a base class pointer, only it happens
112 separately but at the same time for each policy axis:
115 // This defines an incomplete policy where addressingPolicy, writePolicy and bufferingPolicy
117 typedef senf::MakeSocketPolicy<
118 senf::StreamFramingPolicy,
119 senf::ConnectedCommunicationPolicy,
121 >::policy MyReadableSocketPolicy
123 typedef senf::ClientSocketHandle<MyReadableSocketPolicy> MyReadableHandle;
125 // TCPv4ClientSocketHandle is a socket handle with the policy equivalent to
126 // senf::MakeSocketPolicy<
127 // INet4AddressingPolicy,
128 // StreamFramingPolicy,
129 // ConnectedCommunicationPolicy,
132 // SocketBufferingPolicy>::policy
133 senf::TCPv4ClientSocketHandle tcpHandle (...);
135 MyReadableHandle myHandle (tcpHandle); // Conversion to more basic socket handle
138 \section policy_group_details The Policy Framework Classes
140 In the following discussion, deeper insight into C++ and especially the concepts of template
141 meta-programming are needed. However, this information is only needed if you want to write new
142 policy classes or want to use the policy framework explicitly for your own involved
143 optimizations ... or if you are just plain curious :-)
145 In the following discussion we will use the following conventions:
146 \li \e Axis is one or \c AddressingPolicy, \c FramingPolicy, \c CommunicationPolicy, \c
147 ReadPolicy, \c WritePolicy or \c BufferingPolicy
148 \li \e socketPolicy is any socket policy (that is, an instantiation of the SocketPolicy
150 \li \e trait is an any policy class (that is, any class derived from one of the axis base
153 Each axis is comprised of a number of classes and templates (all in namespace senf of course):
155 <dl><dt>\e Axis \c Base (ex: AddressingPolicyBase)</dt><dd>Baseclass of all policies in this
158 <dt>\c Unspecified \e Axis (ex: \ref UnspecifiedAddressingPolicy)</dt> <dd>An alias (typedef)
159 for \e Axis \c Base</dd>
161 <dt>\e Axis \c Is < \e socketPolicy, \e trait > (ex: AddressingPolicyIs)</dt> <dd>A template
162 metafunction returning \c boost::true_type, if \e trait (any class derived from \e Axis \c
163 Base) is a compatible policy value of the given \e socketPolicy</dd>
165 <dt>\c If \e Axis \c Is < \e socketPolicy, \e trait > (ex: IfAddressingPolicyIs)</dt> <dd>This
166 is a combination of \e Axis \c Is and \c boost::enable_if</dd>
168 <dt>\c If \e Axis \c IsNot < \e socketPolicy, \e trait > (ex: IfAddressingPolicyIsNot)</dt>
169 <dd>The inverse of above</dd> </dl>
171 These classes form the basis of the policy framework. To bind the policy axis together, there
172 are some more classes and templates.
174 <dl><dt>\c class \c SocketPolicyBase</dt> <dd>This class is the base class of the SocketPolicy
175 template. It is used to validate, that a class is really a SocketPolicy (by checking, that it
176 derives from SocketPolicyBase. This is simpler than checking the template directly).</dd>
178 <dt>\c template \c SocketPolicy < \e addressingPolicy, \e framingPolicy, \e communicationPolicy,
179 \e readPolicy, \e writePolicy, \e bufferingPolicy ></dt> <dd>This is the central SocketPolicy
180 template. It combines a complete set of policy classes, one for each axis.</dd>
182 <dt>\c template \c MakeSocketPolicy < \e args ></dt> <dd>\c MakeSocketPolicy is a template
183 metafunction which simplifies building SocketPolicy instantiations. It takes any number (ok, up
184 to a maximum of 6) of policy classes as an argument (in any order). It will sort these arguments
185 into the SocketPolicy template arguments. If for some axis no class is specified, it's slot will
186 be filled with \c Unspecified \e Axis. Additionally, the first Argument may optionally be ab
187 arbitrary SocketPolicy. It will provide default values for unspecified axis</dd>
189 <dt>\c template \c SocketPolicyIsBaseOf < \e base, \e derived ></dt> <dd>This template
190 metafunction will check, whether the socket policy \e derived is convertible to \e base. This
191 means, that for each axis, the corresponding policy class in \e derived must be derived or be
192 the same as the one on \e base.</dd> </dl>
194 \implementation All these classes are created automatically. The \c SENF_SOCKET_POLICIES macro
195 is a Boost.Preprocessor style sequence listing all policy axis. The Boost.Preprocessor library
196 is then used to generate the respective classes.
198 \section policy_implement Implementing Policy Classes
200 To define a new policy class, derive from the corresponding base class for your policy
201 axes. The only policy axis which might possibly need to be extended are the addressing policy
202 (AddressingPolicyBase) and the buffering policy (BufferingPolicyBase). See the Documentation of
203 these classes for more information on which members can be implemented.
205 All members you define must be static. For any of the policy classes, you must only define those
206 members which are supported by your implementation. If you leave out a member you automatically
207 disable the corresponding functionality in the ClientSocketHandle/ServerSocketHandle interface.
209 The member prototypes given in the base class documentation only specify the call signature not
210 the way, the member must be defined (FileHandle really is not a FileHandle but an arbitrary
213 If the existence of a member depends on other policies, you should use the
214 <code>If</code><i>SomePolicy</i><code>Is</code> and
215 <code>If</code><i>SomePolicy</i><code>IsNot</code> templates to dynamically enable/disable the
216 member depending on some other policy:
219 struct ExampleAddressingPolicy
221 template <class Policy>
222 void connect(senf::SocketHandle<Policy> handle, Address & addr,
223 typename senf::IfCommmunicationPolicyIs<
224 Policy, senf::ConnectedCommunicationPolicy>::type * = 0);
228 The \c connect member in this example will only be enabled, it the communication policy of the
229 socket handle is ConnectedCommunicationPolicy (or a derived type). See <a
230 href="http://www.boost.org/libs/utility/enable_if.html">Boost.Enable_If</a> for a discussion of
231 the third argument (\c senf::ConnectedCommunicationPolicyIs is based on the \c boost::enable_if
234 \see \ref extend_policy \n
235 <a href="http://www.boost.org/libs/utility/enable_if.html">The Boost enable_if utility</a> \n
236 <a href="http://www.boost.org/libs/mpl/doc/index.html">The Boost.MPL library</a> \n
237 <a href="http://www.boost.org/libs/preprocessor/doc/index.html">The Boost.Preprocessor library</a>
239 \idea We could combine all the \e Axis \c Is templates into a single template. Since the \e
240 trait argument will automatically specify the axis to be used, it is not necessary to specify
241 that axis in the template functor's name. We could even combine this with \c
242 SocketPolicyIsBaseOf.
245 /** \defgroup policy_impl_group Policy Implementation classes
246 \ingroup policy_group
248 Here you will find all policy classes. Also included are some supporting classes which are used
249 as base classes to build other policy classes.
252 #ifndef HH_SocketPolicy_
253 #define HH_SocketPolicy_ 1
257 #include "GenericSockAddr.hh"
259 //#include "SocketPolicy.mpp"
260 ///////////////////////////////hh.p////////////////////////////////////////
264 /// \addtogroup policy_group
267 // This may be adapted to change the supported policies (however, ClientSocketHandle and
268 // ServerSocketHandle will probably have to be adjusted accordingly)
270 /** \brief List all policy axis
274 This define symbol is used to configure the policy axis. The base class for each of these
275 axis must be defined explicitly (e.g. AddressingPolicyBase). The implementation files will
276 then automatically generate all the other classes from this list.
280 # define SENF_SOCKET_POLICIES \
283 (CommunicationPolicy) \
288 // Wer define these classes explicitly (and not with some macro
290 // a) AddressingPolicyBase is different from all the others
291 // b) We want to document each one explicitly
293 /** \brief Policy defining socket addressing
295 AddressingPolicyBase is the baseclass of all addressing policy classes. When defining a new
296 addressing policy, the following members can be defined. All methods must be static.
299 <tr><td>typedef</td> <td><tt>Address</tt></td> <td>Address type</td></tr>
300 <tr><td>method</td> <td><tt>void local(FileHandle, Address &)</tt></td> <td>Get local socket address</td></tr>
301 <tr><td>method</td> <td><tt>void peer(FileHandle, Address &)</tt></td> <td>Get remote socket address</td></tr>
302 <tr><td>method</td> <td><tt>void bind(FileHandle, Address const &)</tt></td> <td>Bind socket to local address</td></tr>
303 <tr><td>method</tr> <td><tt>void connect(FileHandle, Address const &)</tt></td> <td>Connect to remote address</td></tr>
308 struct AddressingPolicyBase
310 virtual ~AddressingPolicyBase() {}
312 typedef GenericSockAddr Address;
315 /** \brief Policy defining the framing format
317 This policy does not define any operations since it does have no influence on any method
318 signature. It does however affect the semantics of the \c read() and \c write() operations.
320 \note This policy axis probably only has two sensible states: StreamFramingPolicy and
321 DatagramFramingPolicy.
325 struct FramingPolicyBase
327 virtual ~FramingPolicyBase() {}
330 /** \brief Policy defining, how peers are selected
332 The CommunicationPolicy may define two members:
335 <tr><td>method</td> <td><tt>void listen(FileHandle, unsigned backlog)</tt></td> <td>Switch socket into listening state</td></tr>
336 <tr><td>method</td> <td><tt>int accept(FileHandle, Address &)</tt></td> <td>Accept a new connection</td></tr>
339 The \c listen member is straight forward. The \c accept() member must return a new file
340 descriptor (which will be used to create a new SocketHandle of the correct
341 type). Additionally, accept() should only be defined, if the Addressing policy is not \c
342 NoAddressingPolicy (which together with ConnectedCommunicationPolicy would identify a
343 point-to-point link with fixed communication partners).
345 \note This Policy only has two meaningful states: ConnectedCommunicationPolicy and
346 UnconnectedCommunicationPolicy. It is probably not sensible to define a new
347 CommunicationPolicy type.
351 struct CommunicationPolicyBase
353 virtual ~CommunicationPolicyBase() {}
356 /** \brief Policy defining the readability
358 The ReadPolicy defines, whether the socket is readable. It may define two members:
361 <tr><td>method</td> <td><tt>unsigned read(FileHandle, char * buffer, unsigned size)</tt></td> <td>read data from socket</td></tr>
362 <tr><td>method</td> <td><tt>unsigned readfrom(FileHandle, char * buffer, unsigned size, Address &)</tt></td> <td>read data from unconnected socket</td></tr>
365 The second member should only be enabled if the communication policy is
366 UnconnectedCommunicationPolicy (otherwise it does not make sense since the communication partner
367 is fixed) (see AddressingPolicyBase on how to do this).
369 \note This Policy only has two meaningful states: ReadablePolicy and NotReadablePolicy. It
370 probably does not make sense to define new read policy types.
374 struct ReadPolicyBase
376 virtual ~ReadPolicyBase() {}
379 /** \brief Policy defining the writability
381 The WritePolicy defines, whether the socket is writable. It may define two members:
384 <tr><td>method</td> <td><tt>unsigned write(FileHandle, char * buffer, unsigned size)</tt></td> <td>read data from socket</td></tr>
385 <tr><td>method</td> <td><tt>unsigned writeto(FileHandle, char * buffer, unsigned size, Address &)</tt></td> <td>read data from unconnected socket</td></tr>
388 The second member should only be enabled if the communication policy is
389 UnconnectedCommunicationPolicy (otherwise it does not make sense since the communication partner
390 is fixed) (see AddressingPolicyBase on how to do this).
392 \note This Policy only has two meaningful states: WritablePolicy and NotWritablePolicy. It
393 probably does not make sense to define new write policy types.
397 struct WritePolicyBase
399 virtual ~WritePolicyBase() {}
402 /** \brief Policy defining the buffering interface
404 The BufferingPolicy defines the buffer handling of the socket. It may provide the following
409 struct BufferingPolicyBase
411 virtual ~BufferingPolicyBase() {}
414 // The implementation file will for each Policy declared above
415 // define the following (SomePolicy is one of the above):
417 // struct SomePolicyBase;
418 // typedef UndefinedSomePolicy;
419 // template SomePolicyIs< SocketPolicy, Axis >
420 // template IfSomePolicyIs< SocketPolicy, Axis >
421 // template IfSomePolicyIsNot< SocketPolicy, Axis >
423 // Additionally the following are defined:
425 // class SocketPolicyBase
426 // template SocketPolicy< ..policies.. >
427 // template MakeSocketPolicy< ..args.. >
428 // template SocketPolicyIsBaseOf< Base, Derived >
432 // The following stub definitions are only visible to doxygen
434 /** \brief Alias of AddressingPolicyBase for better readability
435 \see \ref policy_group
437 typedef AddressingPolicyBase UnspecifiedAddressingPolicy;
439 /** \brief Check single policy axis
441 This template is an example of the \e Axis \c Is family of template metafunctions. It will
442 check, whether \c Trait is a valid compatible Policy class of \c SocketPolicy. \c Trait must
443 be derived from AddressingPolicyBase (respectively \c Policy \c Base).
445 \see \ref policy_group
447 template <class SocketPolicy, class Trait>
448 struct AddressingPolicyIs
451 /** \brief Enable template overload depending on policy value
453 This template is an example of the \c If \e Axis \c Is family of templates. It is used like
454 <a href="http://www.boost.org/libs/utility/enable_if.html">Boost.enable_if</a> to enable a
455 templated overload only, if the AddressingPolicy of \e Axis is compatible with \c Trait
456 (that is the AddressingPolicy of \c Policy is derived from \c Trait).
460 template <class SocketPolicy, class Trait>
461 struct IfAddressingPolicyIs
464 /** \brief Inversion of \c IfAddressingPolicyIs
467 template <class SocketPolicy, class Trait>
468 struct IfAddressingPolicyIsNot
471 /** \brief Baseclass of all SocketPolicies
475 This class provides the baseclass of all socket policies (bundles). It serves two purposes:
476 \li It allows us to easily identify a socket policy bundle by checking a classes baseclass.
477 \li It provides an abstract (virtual) interface to access the policy axes
481 struct SocketPolicyBase
483 /** \brief Polymorphic access to policy axes
485 This is an example of a policy axes accessor. It returns a reference to the policy axes
486 used by the concrete protocol bundle. This reference can then be checked using RTTI
489 AddressingPolicyBase const & theAddressingPolicy() const = 0;
492 /** \brief Collection of policy classes
494 The SocketPolicy template defines the complete Policy used by the socket library. It
495 contains one policy class for each policy axis. This template takes one policy from each
496 axis as it's template arguments (this example implementation only has AddressingPolicy as an
499 A SocketPolicy can be complete or incomplete. An incomplete SocketPolicy will have at least
500 one axis set to \c Undefined \e Axis (or a generic derived class which is used to group some
501 other policies but does not (completely) define the policy behavior). A complete
502 SocketPolicy will have a concrete definition of the desired behavior for each policy axis.
506 template < class AddressingPolicy >
509 /** \brief Check dynamic policy compatibility
511 This method will check the socket policy \a other against this policy. It will check,
512 whether \a other is a base policy (or the same) of this policy. This check is done
513 against the \e dynamic type of \a other using RTTI. It will throw \c std::bad_cast, if
514 the policy is not compatible.
516 \param[in] other SocketPolicy to check
517 \throws std::bad_cast if \a other is not a compatible policy
519 static void checkBaseOf(SocketPolicyBase const & other);
522 /** \brief Metafunction to create SocketPolicy
524 This template metafunction simplifies the creation of a SocketPolicy instantiation. It takes
525 any number (that is up to 6) of Policy classes as arguments in any Order. It will create a
526 SocketPolicy from these policy classes. Any axis not specified will be left as \c
531 template <class Arg1, class Arg2, class ArgN>
532 struct MakeSocketPolicy
535 /** \brief Check policy compatibility
537 This template metafunction checks, whether the SocketPolicy \c Derived is more specialized
538 than \c Base (and therefore a SocketHandle with policy \c Derived is convertible to a
539 SocketHandle with policy \c Base).
541 The metafunction will return true (that is inherits from \c boost::true_type, see the <a
542 href="http://www.boost.org/libs/mpl/doc/index.html">Boost.MPL</a> library documentation for
543 more information) if each policy class in \c Base is a baseclass of (or the same as) the
544 corresponding policy class in \c Derived.
548 template <class Base, class Derived>
549 struct SocketPolicyIsBaseOf
557 //////////////////////////////hh.e////////////////////////////////////////
558 #include "SocketPolicy.ih"
559 //#include "SocketPolicy.cci"
560 #include "SocketPolicy.ct"
561 //#include "SocketPolicy.cti"
568 // c-file-style: "senf"
569 // indent-tabs-mode: nil
570 // ispell-local-dictionary: "american"
571 // compile-command: "scons -u test"
572 // comment-column: 40