|  | Home | Libraries | People | FAQ | More | 
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_blocks 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 |