310 lines
16 KiB
XML
310 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<!--
|
|
Copyright Frank Mori Hess 2007-2009
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
-->
|
|
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.api_changes">
|
|
<title>Signals2 API Changes</title>
|
|
<using-namespace name="boost::signals2"/>
|
|
<using-namespace name="boost"/>
|
|
<section id="signals2.porting">
|
|
<title>Porting from Boost.Signals to Boost.Signals2</title>
|
|
<para>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.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The namespace <code>boost::signals</code> has been replaced by <code>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>boost::signals2</code> namespace,
|
|
unlike the original Boost.Signals which has some classes in the <code>boost</code>
|
|
namespace in addition to its own <code>boost::signals</code> namespace.
|
|
</para>
|
|
<para>
|
|
The Boost.Signals2 header files are contained in the
|
|
<code>boost/signals2/</code> subdirectory instead of the <code>boost/signals</code>
|
|
subdirectory used by the original Boost.Signals. Furthermore, all the headers except
|
|
for the convenience header <code>boost/signals2.hpp</code> are inside the
|
|
<code>boost/signals2/</code> subdirectory, unlike the original Boost.Signals which
|
|
keeps a few headers in the parent <code>boost/</code> directory
|
|
in addition to its own <code>boost/signals/</code> subdirectory.
|
|
</para>
|
|
<para>
|
|
For example, the <code>signal</code> class is now
|
|
in the <code>boost::signals2</code> namespace instead of the
|
|
<code>boost</code> namespace,
|
|
and it's header file is now at <code>boost/signals2/signal.hpp</code> instead of
|
|
<code>boost/signal.hpp</code>.
|
|
</para>
|
|
<para>
|
|
While porting, only trivial changes to <code>#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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Automatic connection management is now achieved through the use of
|
|
<classname>shared_ptr</classname>/<classname>weak_ptr</classname>
|
|
and <methodname>signals2::slot::track</methodname>(), as described in the
|
|
<link linkend="signals2.tutorial.connection-management">tutorial</link>.
|
|
However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management
|
|
is still supported via the <classname>boost::signals2::trackable</classname> class.
|
|
</para>
|
|
<para>
|
|
If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace
|
|
your uses of <classname>boost::signals::trackable</classname> as a base class with
|
|
<classname>boost::signals2::trackable</classname>. Boost.Signals2 uses the same
|
|
<functionname>boost::visit_each</functionname> mechanism to discover
|
|
<code>trackable</code> objects
|
|
as used by the original Boost.Signals library.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Support for postconstructors (and predestructors) on objects managed by <classname>shared_ptr</classname>
|
|
has been added with
|
|
the <functionname>deconstruct</functionname> factory function.
|
|
This was motivated by the importance of
|
|
<code>shared_ptr</code> for the new connection tracking scheme, and the
|
|
inability to obtain a <code>shared_ptr</code> to an object in its constructor.
|
|
The use of <functionname>deconstruct</functionname> is described in the
|
|
<link linkend="signals2.tutorial.deconstruct">tutorial</link>.
|
|
</para>
|
|
<para>
|
|
The use of <functionname>deconstruct</functionname> 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>adl_postconstruct</code> function, where
|
|
a reference to the owning <classname>shared_ptr</classname> is available for
|
|
passing to <methodname>signals2::slot::track</methodname>.
|
|
The <functionname>deconstruct</functionname> function would be used create objects
|
|
of the class and run their associated <code>adl_postconstruct</code> function.
|
|
You can enforce use of <functionname>deconstruct</functionname> by
|
|
making the class' constructors private and declaring
|
|
<classname>deconstruct_access</classname> a friend.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <classname>signals2::slot</classname> class takes a new <code>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.
|
|
</para>
|
|
<para>
|
|
The changes to the slot class should generally not cause any porting difficulties,
|
|
especially if you are using the <classname>boost::signals2::trackable</classname>
|
|
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
|
|
<link linkend="signals2.tutorial.connection-management">tutorial</link>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <classname>optional_last_value</classname> class has replaced <code>last_value</code>
|
|
as the default combiner for signals.
|
|
</para>
|
|
<para>
|
|
The <classname>signals2::last_value</classname> 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).
|
|
</para>
|
|
<para>
|
|
If you are porting signals which have a <code>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
|
|
<classname>optional_last_value</classname> returns a
|
|
<classname>boost::optional</classname> instead of a plain value. One simple
|
|
way to deal with this is to use <code>boost::optional::operator*()</code> to access the
|
|
value wrapped inside the returned <classname>boost::optional</classname>.
|
|
</para>
|
|
<para>
|
|
Alternatively, you could do a port by specifying the <code>Combiner</code> template parameter
|
|
for your <code>signals2::signal</code> to be <classname>signals2::last_value</classname>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <classname>signals2::signal</classname> class has an additional typedef
|
|
<classname>signals2::signal::extended_slot_type</classname>
|
|
and new <methodname>signals2::signal::connect_extended</methodname>()
|
|
methods. These allow connection of slots
|
|
which take an additional <classname>signals2::connection</classname> argument, giving them thread-safe
|
|
access to their signal/slot connection when they are invoked. There is also a
|
|
new <code>ExtendedSlotFunction</code> template parameter for specifying the underlying slot function
|
|
type for the new extended slots.
|
|
</para>
|
|
<para>
|
|
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 <classname>signals2::connection</classname>
|
|
to the signal invoking them (for example to block or disconnect their connection)
|
|
you may wish to connect the slots with
|
|
<methodname>signals2::signal::connect_extended</methodname>().
|
|
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 <link linkend="signals2.tutorial.extended-slot-type">tutorial</link>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <classname>signals2::signal</classname> class has a new <code>Mutex</code> template parameter for specifying
|
|
the mutex type used internally by the signal and its connections.
|
|
</para>
|
|
<para>
|
|
The <code>Mutex</code> template parameter can be left to its default value of
|
|
<classname>boost::signals2::mutex</classname> 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 <classname>dummy_mutex</classname>.
|
|
See the <link linkend="signals2.tutorial.signal-mutex-template-parameter">tutorial</link>
|
|
for more information on the <code>Mutex</code> parameter.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <code>signal::combiner()</code> method, which formerly returned a reference to the
|
|
signal's combiner has been replaced by <methodname>signals2::signal::combiner</methodname>
|
|
(which now returns the combiner by value) and <methodname>signals2::signal::set_combiner</methodname>.
|
|
</para>
|
|
<para>
|
|
During porting it should be straightforward to replace uses of the old reference-returning
|
|
<code>signal::combiner()</code>
|
|
function with the new "by-value" <methodname>signals2::signal::combiner</methodname>
|
|
and <methodname>signals2::signal::set_combiner</methodname> functions.
|
|
However, you will need to inspect each call of the <code>combiner</code> method in your code
|
|
to determine if your program logic has been broken by the changed
|
|
return type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Connections no longer have <code>block()</code> and <code>unblock()</code> methods. Blocking
|
|
of connections is now accomplished by creating <classname>shared_connection_block</classname> objects,
|
|
which provide RAII-style blocking.
|
|
</para>
|
|
<para>
|
|
If you have existing Boost.Signals code that blocks, for example:
|
|
</para>
|
|
<programlisting>
|
|
namespace bs = boost::signals;
|
|
|
|
bs::connection my_connection;
|
|
//...
|
|
|
|
my_connection.block();
|
|
do_something();
|
|
my_connection.unblock();
|
|
</programlisting>
|
|
<para>
|
|
then the version ported to Boost.Signals2 would look like:
|
|
</para>
|
|
<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
|
|
</programlisting>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section id="signals2.api_history">
|
|
<title>Signals2 API Development</title>
|
|
<section id="signals2.api_history.1-56">
|
|
<title>Version 1.56</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
<section id="signals2.api_history.1-45">
|
|
<title>Version 1.45</title>
|
|
<para>
|
|
Version 1.45 added <methodname>slot::track_foreign</methodname>(). This method allows tracking
|
|
of objects owned by <code>shared_ptr</code> classes other than <classname>boost::shared_ptr</classname>,
|
|
for example <classname>std::shared_ptr</classname>.
|
|
</para>
|
|
</section>
|
|
<section id="signals2.api_history.1-40">
|
|
<title>Version 1.40</title>
|
|
<para>
|
|
Version 1.40 adds a few new features to the <classname>shared_connection_block</classname>
|
|
class to make it more flexible:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<classname>shared_connection_block</classname> is now default constructible.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A <classname>shared_connection_block</classname> may now be constructed without
|
|
immediately blocking its connection.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <methodname>shared_connection_block::connection</methodname>() query has been
|
|
added, to provide access to the <code>shared_connection_block</code>s associated
|
|
connection.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>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.
|
|
</para>
|
|
<para>
|
|
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).
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The "portable syntax" signal and slot classes, i.e. signals2::signal0, signal1, etc.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The arg1_type, arg2_type, etc. member typedefs in the <classname>signals2::signal</classname> and
|
|
<classname>signals2::slot</classname> classes. They are replaced by the
|
|
template member classes <classname>signals2::signal::arg</classname> and
|
|
<classname>signals2::slot::arg</classname>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section id="signals2.api_history.1-39">
|
|
<title>Version 1.39</title>
|
|
<para>Version 1.39 is the first release of Boost to include the Signals2 library.</para>
|
|
</section>
|
|
</section>
|
|
</section>
|