...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
The namespace boost::signals
has been replaced by boost::signals2
to avoid conflict with the original Boost.Signals implementation, as well as the Qt "signals" macro.
All the Boost.Signals2 classes are inside the boost::signals2
namespace,
unlike the original Boost.Signals which has some classes in the boost
namespace in addition to its own boost::signals
namespace.
The Boost.Signals2 header files are contained in the
boost/signals2/
subdirectory instead of the boost/signals
subdirectory used by the original Boost.Signals. Furthermore, all the headers except
for the convenience header boost/signals2.hpp
are inside the
boost/signals2/
subdirectory, unlike the original Boost.Signals which
keeps a few headers in the parent boost/
directory
in addition to its own boost/signals/
subdirectory.
For example, the signal
class is now
in the boost::signals2
namespace instead of the
boost
namespace,
and it's header file is now at boost/signals2/signal.hpp
instead of
boost/signal.hpp
.
While porting, only trivial changes to #include
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.
Automatic connection management is now achieved through the use of
shared_ptr
/weak_ptr
and signals2::slot::track
(), as described in the
tutorial.
However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management
is still supported via the boost::signals2::trackable
class.
If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace
your uses of boost::signals::trackable
as a base class with
boost::signals2::trackable
. Boost.Signals2 uses the same
boost::visit_each
mechanism to discover
trackable
objects
as used by the original Boost.Signals library.
Support for postconstructors (and predestructors) on objects managed by shared_ptr
has been added with
the deconstruct
factory function.
This was motivated by the importance of
shared_ptr
for the new connection tracking scheme, and the
inability to obtain a shared_ptr
to an object in its constructor.
The use of deconstruct
is described in the
tutorial.
The use of deconstruct
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
adl_postconstruct
function, where
a reference to the owning shared_ptr
is available for
passing to signals2::slot::track
.
The deconstruct
function would be used create objects
of the class and run their associated adl_postconstruct
function.
You can enforce use of deconstruct
by
making the class' constructors private and declaring
deconstruct_access
a friend.
The signals2::slot
class takes a new Signature
template parameter,
is useable as a function object, and has some additional features to support the
new Boost.Signals2 automatic connection management scheme.
The changes to the slot class should generally not cause any porting difficulties,
especially if you are using the boost::signals2::trackable
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
tutorial.
The optional_last_value
class has replaced last_value
as the default combiner for signals.
The signals2::last_value
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).
If you are porting signals which have a void
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
optional_last_value
returns a
boost::optional
instead of a plain value. One simple
way to deal with this is to use boost::optional::operator*()
to access the
value wrapped inside the returned boost::optional
.
Alternatively, you could do a port by specifying the Combiner
template parameter
for your signals2::signal
to be signals2::last_value
.
The signals2::signal
class has an additional typedef
signals2::signal::extended_slot_type
and new signals2::signal::connect_extended
()
methods. These allow connection of slots
which take an additional signals2::connection
argument, giving them thread-safe
access to their signal/slot connection when they are invoked. There is also a
new ExtendedSlotFunction
template parameter for specifying the underlying slot function
type for the new extended slots.
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 signals2::connection
to the signal invoking them (for example to block or disconnect their connection)
you may wish to connect the slots with
signals2::signal::connect_extended
().
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 tutorial.
The signals2::signal
class has a new Mutex
template parameter for specifying
the mutex type used internally by the signal and its connections.
The Mutex
template parameter can be left to its default value of
boost::signals2::mutex
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 dummy_mutex
.
See the tutorial
for more information on the Mutex
parameter.
The signal::combiner()
method, which formerly returned a reference to the
signal's combiner has been replaced by signals2::signal::combiner
(which now returns the combiner by value) and signals2::signal::set_combiner
.
During porting it should be straightforward to replace uses of the old reference-returning
signal::combiner()
function with the new "by-value" signals2::signal::combiner
and signals2::signal::set_combiner
functions.
However, you will need to inspect each call of the combiner
method in your code
to determine if your program logic has been broken by the changed
return type.
Connections no longer have block()
and unblock()
methods. Blocking
of connections is now accomplished by creating shared_connection_block
objects,
which provide RAII-style blocking.
If you have existing Boost.Signals code that blocks, for example:
namespace bs = boost::signals; bs::connection my_connection; //... my_connection.block(); do_something(); my_connection.unblock();
then the version ported to Boost.Signals2 would look like:
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
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.
Version 1.45 added slot::track_foreign
(). This method allows tracking
of objects owned by shared_ptr
classes other than boost::shared_ptr
,
for example std::shared_ptr
.
Version 1.40 adds a few new features to the shared_connection_block
class to make it more flexible:
shared_connection_block
is now default constructible.
A shared_connection_block
may now be constructed without
immediately blocking its connection.
The shared_connection_block::connection
() query has been
added, to provide access to the shared_connection_block
s associated
connection.
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.
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).
The "portable syntax" signal and slot classes, i.e. signals2::signal0, signal1, etc.
The arg1_type, arg2_type, etc. member typedefs in the signals2::signal
and
signals2::slot
classes. They are replaced by the
template member classes signals2::signal::arg
and
signals2::slot::arg
.
Last revised: June 12, 2007 at 14:01:23 -0400 |