ceph/src/boost/libs/signals2/doc/porting.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4 <!--
   5 Copyright Frank Mori Hess 2007-2009
   6
   7 Distributed under the Boost Software License, Version 1.0. (See accompanying
   8 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 -->
  10 <section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.api_changes">
  11   <title>Signals2 API Changes</title>
  12   <using-namespace name="boost::signals2"/>
  13   <using-namespace name="boost"/>
  14   <section id="signals2.porting">
  15   <title>Porting from Boost.Signals to Boost.Signals2</title>
  16     <para>The changes made to the Boost.Signals2 API compared to the original Boost.Signals
  17       library are summarized below.  We also provide some notes on
  18       dealing with each change while porting existing Boost.Signals code to Boost.Signals2.
  19     </para>
  20     <itemizedlist>
  21       <listitem>
  22         <para>The namespace <code>boost::signals</code> has been replaced by <code>boost::signals2</code>
  23           to avoid conflict with the original Boost.Signals implementation, as well as the Qt "signals" macro.
  24           All the Boost.Signals2 classes are inside the <code>boost::signals2</code> namespace,
  25           unlike the original Boost.Signals which has some classes in the <code>boost</code>
  26           namespace in addition to its own <code>boost::signals</code> namespace.
  27         </para>
  28         <para>
  29           The Boost.Signals2 header files are contained in the
  30           <code>boost/signals2/</code> subdirectory instead of the <code>boost/signals</code>
  31           subdirectory used by the original Boost.Signals.  Furthermore, all the headers except
  32           for the convenience header <code>boost/signals2.hpp</code> are inside the
  33           <code>boost/signals2/</code> subdirectory, unlike the original Boost.Signals which
  34           keeps a few headers in the parent <code>boost/</code> directory
  35           in addition to its own <code>boost/signals/</code> subdirectory.
  36         </para>
  37         <para>
  38           For example, the <code>signal</code> class is now
  39           in the <code>boost::signals2</code> namespace instead of the
  40           <code>boost</code> namespace,
  41           and it's header file is now at <code>boost/signals2/signal.hpp</code> instead of
  42           <code>boost/signal.hpp</code>.
  43         </para>
  44         <para>
  45           While porting, only trivial changes to <code>#include</code> directives
  46           and namespace qualifications should be required to deal with these changes.
  47           Furthermore, the new namespace and header locations for Boost.Signals2
  48           allow it to coexist in the same program with the original Boost.Signals library,
  49           and porting can be performed piecemeal.
  50         </para>
  51       </listitem>
  52       <listitem>
  53         <para>
  54           Automatic connection management is now achieved through the use of
  55           <classname>shared_ptr</classname>/<classname>weak_ptr</classname>
  56           and <methodname>signals2::slot::track</methodname>(), as described in the
  57           <link linkend="signals2.tutorial.connection-management">tutorial</link>.
  58           However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management
  59           is still supported via the <classname>boost::signals2::trackable</classname> class.
  60         </para>
  61         <para>
  62           If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace
  63           your uses of <classname>boost::signals::trackable</classname> as a base class with
  64           <classname>boost::signals2::trackable</classname>.  Boost.Signals2 uses the same
  65           <functionname>boost::visit_each</functionname> mechanism to discover
  66           <code>trackable</code> objects
  67           as used by the original Boost.Signals library.
  68         </para>
  69       </listitem>
  70       <listitem>
  71         <para>Support for postconstructors (and predestructors) on objects managed by <classname>shared_ptr</classname>
  72           has been added with
  73           the <functionname>deconstruct</functionname> factory function.
  74           This was motivated by the importance of
  75           <code>shared_ptr</code> for the new connection tracking scheme, and the
  76           inability to obtain a <code>shared_ptr</code> to an object in its constructor.
  77           The use of <functionname>deconstruct</functionname> is described in the
  78           <link linkend="signals2.tutorial.deconstruct">tutorial</link>.
  79         </para>
  80         <para>
  81           The use of <functionname>deconstruct</functionname> is in no way required,
  82           it is only provided in the hope
  83           it may be useful.  You may wish to use it if you are porting code where
  84           a class creates connections to its own member functions in its constructor,
  85           and you also
  86           wish to use the new automatic connection management scheme.  You could then
  87           move the connection creation from the constructor to to the an
  88           <code>adl_postconstruct</code> function, where
  89           a reference to the owning <classname>shared_ptr</classname> is available for
  90           passing to <methodname>signals2::slot::track</methodname>.
  91           The <functionname>deconstruct</functionname> function would be used create objects
  92           of the class and run their associated <code>adl_postconstruct</code> function.
  93           You can enforce use of <functionname>deconstruct</functionname> by
  94           making the class' constructors private and declaring
  95           <classname>deconstruct_access</classname> a friend.
  96         </para>
  97       </listitem>
  98       <listitem>
  99         <para>
 100           The <classname>signals2::slot</classname> class takes a new <code>Signature</code> template parameter,
 101           is useable as a function object, and has some additional features to support the
 102           new Boost.Signals2 automatic connection management scheme.
 103         </para>
 104         <para>
 105           The changes to the slot class should generally not cause any porting difficulties,
 106           especially if you are using the <classname>boost::signals2::trackable</classname>
 107           compatibility class mentioned above.  If you are converting your code over to
 108           use the new automatic connection management scheme, you will need to
 109           employ some of the new slot features, as described in the
 110           <link linkend="signals2.tutorial.connection-management">tutorial</link>.
 111         </para>
 112       </listitem>
 113       <listitem>
 114         <para>
 115           The <classname>optional_last_value</classname> class has replaced <code>last_value</code>
 116           as the default combiner for signals.
 117         </para>
 118         <para>
 119           The <classname>signals2::last_value</classname> combiner is still provided, although its
 120           behavior is slightly changed in that it
 121           throws an exception when no slots are connected on signal invocation, instead of
 122           always requiring at least one slot to be connected (except for its void specialization
 123           which never required any slots to be connected).
 124         </para>
 125         <para>
 126           If you are porting signals which have a <code>void</code> return type in their signature
 127           and they use the default combiner, there are no changes required.  If you are
 128           using the default combiner with a non-void return type and care about the
 129           value returned from signal invocation, you will have to take into account that
 130           <classname>optional_last_value</classname> returns a
 131           <classname>boost::optional</classname> instead of a plain value.  One simple
 132           way to deal with this is to use <code>boost::optional::operator*()</code> to access the
 133           value wrapped inside the returned <classname>boost::optional</classname>.
 134         </para>
 135         <para>
 136           Alternatively, you could do a port by specifying the <code>Combiner</code> template parameter
 137           for your <code>signals2::signal</code> to be <classname>signals2::last_value</classname>.
 138         </para>
 139       </listitem>
 140       <listitem>
 141         <para>
 142           The <classname>signals2::signal</classname> class has an additional typedef
 143           <classname>signals2::signal::extended_slot_type</classname>
 144           and new <methodname>signals2::signal::connect_extended</methodname>()
 145           methods.  These allow connection of slots
 146           which take an additional <classname>signals2::connection</classname> argument, giving them thread-safe
 147           access to their signal/slot connection when they are invoked.  There is also a
 148           new <code>ExtendedSlotFunction</code> template parameter for specifying the underlying slot function
 149           type for the new extended slots.
 150         </para>
 151         <para>
 152           These additions should have no effect on porting unless you are also converting
 153           your program from a single threaded program into a multi-threaded one.  In that case,
 154           if you have slots which need access to their <classname>signals2::connection</classname>
 155           to the signal invoking them (for example to block or disconnect their connection)
 156           you may wish to connect the slots with
 157           <methodname>signals2::signal::connect_extended</methodname>().
 158           This also requires adding an additional connection argument to the slot.
 159           More information on how and why to use extended slots is available
 160           in the <link linkend="signals2.tutorial.extended-slot-type">tutorial</link>.
 161         </para>
 162       </listitem>
 163       <listitem>
 164         <para>
 165           The <classname>signals2::signal</classname> class has a new <code>Mutex</code> template parameter for specifying
 166           the mutex type used internally by the signal and its connections.
 167         </para>
 168         <para>
 169           The <code>Mutex</code> template parameter can be left to its default value of
 170           <classname>boost::signals2::mutex</classname> and should have little effect on porting.
 171           However, if you have a single-threaded program and are
 172           concerned about incuring a performance overhead from unneeded mutex locking, you may
 173           wish to use a different mutex for your signals such as <classname>dummy_mutex</classname>.
 174           See the <link linkend="signals2.tutorial.signal-mutex-template-parameter">tutorial</link>
 175           for more information on the <code>Mutex</code> parameter.
 176         </para>
 177       </listitem>
 178       <listitem>
 179         <para>The <code>signal::combiner()</code> method, which formerly returned a reference to the
 180           signal's combiner has been replaced by <methodname>signals2::signal::combiner</methodname>
 181           (which now returns the combiner by value) and <methodname>signals2::signal::set_combiner</methodname>.
 182         </para>
 183         <para>
 184           During porting it should be straightforward to replace uses of the old reference-returning
 185           <code>signal::combiner()</code>
 186           function with the new "by-value" <methodname>signals2::signal::combiner</methodname>
 187           and <methodname>signals2::signal::set_combiner</methodname> functions.
 188           However, you will need to inspect each call of the <code>combiner</code> method in your code
 189           to determine if your program logic has been broken by the changed
 190           return type.
 191         </para>
 192       </listitem>
 193       <listitem>
 194         <para>Connections no longer have <code>block()</code> and <code>unblock()</code> methods.  Blocking
 195           of connections is now accomplished by creating <classname>shared_connection_block</classname> objects,
 196           which provide RAII-style blocking.
 197         </para>
 198         <para>
 199           If you have existing Boost.Signals code that blocks, for example:
 200         </para>
 201         <programlisting>
 202   namespace bs = boost::signals;
 203
 204   bs::connection my_connection;
 205   //...
 206
 207   my_connection.block();
 208   do_something();
 209   my_connection.unblock();
 210   </programlisting>
 211             <para>
 212               then the version ported to Boost.Signals2 would look like:
 213             </para>
 214               <programlisting>
 215   namespace bs2 = boost::signals2;
 216
 217   bs2::connection my_connection;
 218   //...
 219
 220   {
 221     bs2::shared_connection_block blocker(my_connection);
 222     do_something();
 223   } // blocker goes out of scope here and releases its block on my_connection
 224   </programlisting>
 225       </listitem>
 226     </itemizedlist>
 227   </section>
 228   <section id="signals2.api_history">
 229     <title>Signals2 API Development</title>
 230     <section id="signals2.api_history.1-56">
 231       <title>Version 1.56</title>
 232       <para>
 233         Version 1.56 modified the behavior of the signal destructor, in that it no longer
 234         explicitly calls disconnect_all_slots.  Any signal invocations running
 235         concurrently with the signal destructor should now complete normally, rather
 236         than skipping all remaining slots.  Once all concurrent signal invocations
 237         complete, all connections to the deleted signal will still ultimately
 238         be disconnected.  This change brings Boost.Signals2
 239         behavior closer to the behavior of the original Boost.Signals library.
 240       </para>
 241     </section>
 242     <section id="signals2.api_history.1-45">
 243       <title>Version 1.45</title>
 244       <para>
 245         Version 1.45 added <methodname>slot::track_foreign</methodname>().  This method allows tracking
 246         of objects owned by <code>shared_ptr</code> classes other than <classname>boost::shared_ptr</classname>,
 247         for example <classname>std::shared_ptr</classname>.
 248       </para>
 249     </section>
 250     <section id="signals2.api_history.1-40">
 251       <title>Version 1.40</title>
 252       <para>
 253         Version 1.40 adds a few new features to the <classname>shared_connection_block</classname>
 254         class to make it more flexible:
 255         <itemizedlist>
 256           <listitem>
 257             <para>
 258               <classname>shared_connection_block</classname> is now default constructible.
 259             </para>
 260           </listitem>
 261           <listitem>
 262             <para>
 263               A <classname>shared_connection_block</classname> may now be constructed without
 264               immediately blocking its connection.
 265             </para>
 266           </listitem>
 267           <listitem>
 268             <para>
 269               The <methodname>shared_connection_block::connection</methodname>() query has been
 270               added, to provide access to the <code>shared_connection_block</code>s associated
 271               connection.
 272             </para>
 273           </listitem>
 274         </itemizedlist>
 275       </para>
 276       <para>Version 1.40 also introduces a variadic templates implementation of
 277         Signals2, which is used when Boost detects compiler support for variadic templates
 278         (variadic templates are a new feature of C++11).
 279         This change is mostly transparent to the user, however it does introduce a few
 280         visible tweaks to the interface as described in the following.
 281       </para>
 282       <para>
 283         The following library features are
 284         deprecated, and are only available if your compiler is NOT using
 285         variadic templates (i.e. BOOST_NO_CXX11_VARIADIC_TEMPLATES is defined
 286         by Boost.Config).
 287         <itemizedlist>
 288           <listitem>
 289             <para>
 290               The "portable syntax" signal and slot classes, i.e. signals2::signal0, signal1, etc.
 291             </para>
 292           </listitem>
 293           <listitem>
 294             <para>
 295               The arg1_type, arg2_type, etc. member typedefs in the <classname>signals2::signal</classname> and
 296               <classname>signals2::slot</classname> classes.  They are replaced by the
 297               template member classes <classname>signals2::signal::arg</classname> and
 298               <classname>signals2::slot::arg</classname>.
 299             </para>
 300           </listitem>
 301         </itemizedlist>
 302       </para>
 303     </section>
 304     <section id="signals2.api_history.1-39">
 305       <title>Version 1.39</title>
 306       <para>Version 1.39 is the first release of Boost to include the Signals2 library.</para>
 307     </section>
 308   </section>
 309 </section>