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<!-- 5Copyright Frank Mori Hess 2007-2009 6 7Distributed under the Boost Software License, Version 1.0. (See accompanying 8file 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> 310