1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Signals2 API Changes</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../signals2.html" title="Chapter 35. Boost.Signals2"> 10<link rel="prev" href="rationale.html" title="Design Rationale"> 11<link rel="next" href="tests.html" title="Testsuite"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="rationale.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tests.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="signals2.api_changes"></a>Signals2 API Changes</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="api_changes.html#signals2.porting">Porting from Boost.Signals to Boost.Signals2</a></span></dt> 31<dt><span class="section"><a href="api_changes.html#signals2.api_history">Signals2 API Development</a></span></dt> 32</dl></div> 33<div class="section"> 34<div class="titlepage"><div><div><h3 class="title"> 35<a name="signals2.porting"></a>Porting from Boost.Signals to Boost.Signals2</h3></div></div></div> 36<p>The changes made to the Boost.Signals2 API compared to the original Boost.Signals 37 library are summarized below. We also provide some notes on 38 dealing with each change while porting existing Boost.Signals code to Boost.Signals2. 39 </p> 40<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 41<li class="listitem"> 42<p>The namespace <code class="computeroutput">boost::signals</code> has been replaced by <code class="computeroutput">boost::signals2</code> 43 to avoid conflict with the original Boost.Signals implementation, as well as the Qt "signals" macro. 44 All the Boost.Signals2 classes are inside the <code class="computeroutput">boost::signals2</code> namespace, 45 unlike the original Boost.Signals which has some classes in the <code class="computeroutput">boost</code> 46 namespace in addition to its own <code class="computeroutput">boost::signals</code> namespace. 47 </p> 48<p> 49 The Boost.Signals2 header files are contained in the 50 <code class="computeroutput">boost/signals2/</code> subdirectory instead of the <code class="computeroutput">boost/signals</code> 51 subdirectory used by the original Boost.Signals. Furthermore, all the headers except 52 for the convenience header <code class="computeroutput">boost/signals2.hpp</code> are inside the 53 <code class="computeroutput">boost/signals2/</code> subdirectory, unlike the original Boost.Signals which 54 keeps a few headers in the parent <code class="computeroutput">boost/</code> directory 55 in addition to its own <code class="computeroutput">boost/signals/</code> subdirectory. 56 </p> 57<p> 58 For example, the <code class="computeroutput">signal</code> class is now 59 in the <code class="computeroutput">boost::signals2</code> namespace instead of the 60 <code class="computeroutput">boost</code> namespace, 61 and it's header file is now at <code class="computeroutput">boost/signals2/signal.hpp</code> instead of 62 <code class="computeroutput">boost/signal.hpp</code>. 63 </p> 64<p> 65 While porting, only trivial changes to <code class="computeroutput">#include</code> directives 66 and namespace qualifications should be required to deal with these changes. 67 Furthermore, the new namespace and header locations for Boost.Signals2 68 allow it to coexist in the same program with the original Boost.Signals library, 69 and porting can be performed piecemeal. 70 </p> 71</li> 72<li class="listitem"> 73<p> 74 Automatic connection management is now achieved through the use of 75 <code class="computeroutput">shared_ptr</code>/<code class="computeroutput">weak_ptr</code> 76 and <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_36_6_12_5_1_1_17_1-bb">signals2::slot::track</a></code>(), as described in the 77 <a class="link" href="tutorial.html#signals2.tutorial.connection-management" title="Automatic Connection Management (Intermediate)">tutorial</a>. 78 However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management 79 is still supported via the <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code> class. 80 </p> 81<p> 82 If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace 83 your uses of <code class="computeroutput">boost::signals::trackable</code> as a base class with 84 <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code>. Boost.Signals2 uses the same 85 <code class="computeroutput">boost::visit_each</code> mechanism to discover 86 <code class="computeroutput">trackable</code> objects 87 as used by the original Boost.Signals library. 88 </p> 89</li> 90<li class="listitem"> 91<p>Support for postconstructors (and predestructors) on objects managed by <code class="computeroutput">shared_ptr</code> 92 has been added with 93 the <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> factory function. 94 This was motivated by the importance of 95 <code class="computeroutput">shared_ptr</code> for the new connection tracking scheme, and the 96 inability to obtain a <code class="computeroutput">shared_ptr</code> to an object in its constructor. 97 The use of <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> is described in the 98 <a class="link" href="tutorial.html#signals2.tutorial.deconstruct" title="Postconstructors and Predestructors (Advanced)">tutorial</a>. 99 </p> 100<p> 101 The use of <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> is in no way required, 102 it is only provided in the hope 103 it may be useful. You may wish to use it if you are porting code where 104 a class creates connections to its own member functions in its constructor, 105 and you also 106 wish to use the new automatic connection management scheme. You could then 107 move the connection creation from the constructor to to the an 108 <code class="computeroutput">adl_postconstruct</code> function, where 109 a reference to the owning <code class="computeroutput">shared_ptr</code> is available for 110 passing to <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_36_6_12_5_1_1_17_1-bb">signals2::slot::track</a></code>. 111 The <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> function would be used create objects 112 of the class and run their associated <code class="computeroutput">adl_postconstruct</code> function. 113 You can enforce use of <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> by 114 making the class' constructors private and declaring 115 <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct_access.html" title="Class deconstruct_access">deconstruct_access</a></code> a friend. 116 </p> 117</li> 118<li class="listitem"> 119<p> 120 The <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html" title="Class template slot">signals2::slot</a></code> class takes a new <code class="computeroutput">Signature</code> template parameter, 121 is useable as a function object, and has some additional features to support the 122 new Boost.Signals2 automatic connection management scheme. 123 </p> 124<p> 125 The changes to the slot class should generally not cause any porting difficulties, 126 especially if you are using the <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code> 127 compatibility class mentioned above. If you are converting your code over to 128 use the new automatic connection management scheme, you will need to 129 employ some of the new slot features, as described in the 130 <a class="link" href="tutorial.html#signals2.tutorial.connection-management" title="Automatic Connection Management (Intermediate)">tutorial</a>. 131 </p> 132</li> 133<li class="listitem"> 134<p> 135 The <code class="computeroutput"><a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">optional_last_value</a></code> class has replaced <code class="computeroutput">last_value</code> 136 as the default combiner for signals. 137 </p> 138<p> 139 The <code class="computeroutput"><a class="link" href="../boost/signals2/last_value.html" title="Class template last_value">signals2::last_value</a></code> combiner is still provided, although its 140 behavior is slightly changed in that it 141 throws an exception when no slots are connected on signal invocation, instead of 142 always requiring at least one slot to be connected (except for its void specialization 143 which never required any slots to be connected). 144 </p> 145<p> 146 If you are porting signals which have a <code class="computeroutput">void</code> return type in their signature 147 and they use the default combiner, there are no changes required. If you are 148 using the default combiner with a non-void return type and care about the 149 value returned from signal invocation, you will have to take into account that 150 <code class="computeroutput"><a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">optional_last_value</a></code> returns a 151 <code class="computeroutput">boost::optional</code> instead of a plain value. One simple 152 way to deal with this is to use <code class="computeroutput">boost::optional::operator*()</code> to access the 153 value wrapped inside the returned <code class="computeroutput">boost::optional</code>. 154 </p> 155<p> 156 Alternatively, you could do a port by specifying the <code class="computeroutput">Combiner</code> template parameter 157 for your <code class="computeroutput">signals2::signal</code> to be <code class="computeroutput"><a class="link" href="../boost/signals2/last_value.html" title="Class template last_value">signals2::last_value</a></code>. 158 </p> 159</li> 160<li class="listitem"> 161<p> 162 The <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signals2::signal</a></code> class has an additional typedef 163 <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#boost.signals2.signal.extended_slot_type">signals2::signal::extended_slot_type</a></code> 164 and new <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_36_6_9_3_1_2_24_2-bb">signals2::signal::connect_extended</a></code>() 165 methods. These allow connection of slots 166 which take an additional <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> argument, giving them thread-safe 167 access to their signal/slot connection when they are invoked. There is also a 168 new <code class="computeroutput">ExtendedSlotFunction</code> template parameter for specifying the underlying slot function 169 type for the new extended slots. 170 </p> 171<p> 172 These additions should have no effect on porting unless you are also converting 173 your program from a single threaded program into a multi-threaded one. In that case, 174 if you have slots which need access to their <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> 175 to the signal invoking them (for example to block or disconnect their connection) 176 you may wish to connect the slots with 177 <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_36_6_9_3_1_2_24_2-bb">signals2::signal::connect_extended</a></code>(). 178 This also requires adding an additional connection argument to the slot. 179 More information on how and why to use extended slots is available 180 in the <a class="link" href="tutorial.html#signals2.tutorial.extended-slot-type" title="Giving a Slot Access to its Connection (Advanced)">tutorial</a>. 181 </p> 182</li> 183<li class="listitem"> 184<p> 185 The <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signals2::signal</a></code> class has a new <code class="computeroutput">Mutex</code> template parameter for specifying 186 the mutex type used internally by the signal and its connections. 187 </p> 188<p> 189 The <code class="computeroutput">Mutex</code> template parameter can be left to its default value of 190 <code class="computeroutput"><a class="link" href="../boost/signals2/mutex.html" title="Class mutex">boost::signals2::mutex</a></code> and should have little effect on porting. 191 However, if you have a single-threaded program and are 192 concerned about incuring a performance overhead from unneeded mutex locking, you may 193 wish to use a different mutex for your signals such as <code class="computeroutput"><a class="link" href="../boost/signals2/dummy_mutex.html" title="Class dummy_mutex">dummy_mutex</a></code>. 194 See the <a class="link" href="tutorial.html#signals2.tutorial.signal-mutex-template-parameter" title="Changing the Mutex Type of a Signal (Advanced).">tutorial</a> 195 for more information on the <code class="computeroutput">Mutex</code> parameter. 196 </p> 197</li> 198<li class="listitem"> 199<p>The <code class="computeroutput">signal::combiner()</code> method, which formerly returned a reference to the 200 signal's combiner has been replaced by <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_36_6_9_3_1_2_26_1-bb">signals2::signal::combiner</a></code> 201 (which now returns the combiner by value) and <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_36_6_9_3_1_2_26_2-bb">signals2::signal::set_combiner</a></code>. 202 </p> 203<p> 204 During porting it should be straightforward to replace uses of the old reference-returning 205 <code class="computeroutput">signal::combiner()</code> 206 function with the new "by-value" <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_36_6_9_3_1_2_26_1-bb">signals2::signal::combiner</a></code> 207 and <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_36_6_9_3_1_2_26_2-bb">signals2::signal::set_combiner</a></code> functions. 208 However, you will need to inspect each call of the <code class="computeroutput">combiner</code> method in your code 209 to determine if your program logic has been broken by the changed 210 return type. 211 </p> 212</li> 213<li class="listitem"> 214<p>Connections no longer have <code class="computeroutput">block()</code> and <code class="computeroutput">unblock()</code> methods. Blocking 215 of connections is now accomplished by creating <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> objects, 216 which provide RAII-style blocking. 217 </p> 218<p> 219 If you have existing Boost.Signals code that blocks, for example: 220 </p> 221<pre class="programlisting"> 222 namespace bs = boost::signals; 223 224 bs::connection my_connection; 225 //... 226 227 my_connection.block(); 228 do_something(); 229 my_connection.unblock(); 230 </pre> 231<p> 232 then the version ported to Boost.Signals2 would look like: 233 </p> 234<pre class="programlisting"> 235 namespace bs2 = boost::signals2; 236 237 bs2::connection my_connection; 238 //... 239 240 { 241 bs2::shared_connection_block blocker(my_connection); 242 do_something(); 243 } // blocker goes out of scope here and releases its block on my_connection 244 </pre> 245</li> 246</ul></div> 247</div> 248<div class="section"> 249<div class="titlepage"><div><div><h3 class="title"> 250<a name="signals2.api_history"></a>Signals2 API Development</h3></div></div></div> 251<div class="toc"><dl class="toc"> 252<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-56">Version 1.56</a></span></dt> 253<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-45">Version 1.45</a></span></dt> 254<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-40">Version 1.40</a></span></dt> 255<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-39">Version 1.39</a></span></dt> 256</dl></div> 257<div class="section"> 258<div class="titlepage"><div><div><h4 class="title"> 259<a name="signals2.api_history.1-56"></a>Version 1.56</h4></div></div></div> 260<p> 261 Version 1.56 modified the behavior of the signal destructor, in that it no longer 262 explicitly calls disconnect_all_slots. Any signal invocations running 263 concurrently with the signal destructor should now complete normally, rather 264 than skipping all remaining slots. Once all concurrent signal invocations 265 complete, all connections to the deleted signal will still ultimately 266 be disconnected. This change brings Boost.Signals2 267 behavior closer to the behavior of the original Boost.Signals library. 268 </p> 269</div> 270<div class="section"> 271<div class="titlepage"><div><div><h4 class="title"> 272<a name="signals2.api_history.1-45"></a>Version 1.45</h4></div></div></div> 273<p> 274 Version 1.45 added <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_36_6_12_5_1_1_17_2-bb">slot::track_foreign</a></code>(). This method allows tracking 275 of objects owned by <code class="computeroutput">shared_ptr</code> classes other than <code class="computeroutput">boost::shared_ptr</code>, 276 for example <code class="computeroutput">std::shared_ptr</code>. 277 </p> 278</div> 279<div class="section"> 280<div class="titlepage"><div><div><h4 class="title"> 281<a name="signals2.api_history.1-40"></a>Version 1.40</h4></div></div></div> 282<p> 283 Version 1.40 adds a few new features to the <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> 284 class to make it more flexible: 285 </p> 286<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 287<li class="listitem"><p> 288 <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> is now default constructible. 289 </p></li> 290<li class="listitem"><p> 291 A <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> may now be constructed without 292 immediately blocking its connection. 293 </p></li> 294<li class="listitem"><p> 295 The <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html#id-1_3_36_6_8_4_1_1_8_1-bb">shared_connection_block::connection</a></code>() query has been 296 added, to provide access to the <code class="computeroutput">shared_connection_block</code>s associated 297 connection. 298 </p></li> 299</ul></div> 300<p> 301 </p> 302<p>Version 1.40 also introduces a variadic templates implementation of 303 Signals2, which is used when Boost detects compiler support for variadic templates 304 (variadic templates are a new feature of C++11). 305 This change is mostly transparent to the user, however it does introduce a few 306 visible tweaks to the interface as described in the following. 307 </p> 308<p> 309 The following library features are 310 deprecated, and are only available if your compiler is NOT using 311 variadic templates (i.e. BOOST_NO_CXX11_VARIADIC_TEMPLATES is defined 312 by Boost.Config). 313 </p> 314<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 315<li class="listitem"><p> 316 The "portable syntax" signal and slot classes, i.e. signals2::signal0, signal1, etc. 317 </p></li> 318<li class="listitem"><p> 319 The arg1_type, arg2_type, etc. member typedefs in the <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signals2::signal</a></code> and 320 <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html" title="Class template slot">signals2::slot</a></code> classes. They are replaced by the 321 template member classes <code class="computeroutput"><a class="link" href="../boost/signals2/signal/arg.html" title="Class template arg">signals2::signal::arg</a></code> and 322 <code class="computeroutput"><a class="link" href="../boost/signals2/slot/arg.html" title="Class template arg">signals2::slot::arg</a></code>. 323 </p></li> 324</ul></div> 325<p> 326 </p> 327</div> 328<div class="section"> 329<div class="titlepage"><div><div><h4 class="title"> 330<a name="signals2.api_history.1-39"></a>Version 1.39</h4></div></div></div> 331<p>Version 1.39 is the first release of Boost to include the Signals2 library.</p> 332</div> 333</div> 334</div> 335<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 336<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23 -0400</small></p></td> 337<td align="right"><div class="copyright-footer">Copyright © 2001-2004 Douglas Gregor<br>Copyright © 2007-2009 Frank Mori Hess<p>Distributed under the Boost 338 Software License, Version 1.0. (See accompanying file 339 <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p> 340</div></td> 341</tr></table> 342<hr> 343<div class="spirit-nav"> 344<a accesskey="p" href="rationale.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tests.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 345</div> 346</body> 347</html> 348
