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