Signals

Header: "boost/signals.hpp"

This includes all of the library through a single header.

 "boost/signals/signal.hpp" 

contains the definition of signals.

 "boost/signals/slot.hpp" 

contains the definition of the slot class.

 "boost/signals/connection.hpp" 

contains definitions of the classes connection and scoped_connection.

To use this library, either include the header "boost/signals.hpp", which ensures that the entire library is available, or include the separate headers containing the functionality that you need. The core of the Boost.Signals library exists in namespace boost, and advanced features reside in boost::signals.

The following is a partial synopsis for signal, followed by a brief discussion of the most important members. For a full reference, see the online documentation for Signals.

 namespace boost {   template<typename Signature,   // Function type R(T1, T2, ..., TN)     typename Combiner = last_value<R>,     typename Group = int,     typename GroupCompare = std::less<Group>,     typename SlotFunction = function<Signature> >   class signal : public signals::trackable,                  private noncopyable {   public:     signal(const Combiner&=Combiner(),            const GroupCompare&=GroupCompare());     ~signal();     signals::connection connect(const slot_type&);     signals::connection connect(       const Group&,       const slot_type&);     void disconnect(const Group&);     std::size_t num_slots() const;     result_type operator()       (T1, T2, ..., TN);   }; } 

Types

Let's have a look first at the template parameters for signal. There are reasonable defaults for all but the first argument, but it helps to understand the basic meaning of these parameters. The first template parameter is the actual signature of the function to be invoked. In the case of signals, the signal itself is the entity to be invoked. When declaring this signature, use the same syntax as for ordinary function signatures.^[1] For example, the signature for a function returning double and accepting one argument of type int looks like this:

^[1] The alert reader might notice that this is how boost::function works, too.

 signal<double(int)> 

The Combiner parameter denotes a function object responsible for iterating through and calling all of the connected slots for the signal. It also determines how to combine the results of invoking the handlers. The default type, last_value, simply returns the result of invoking the last slot.

The Groups parameter is the type to be used for grouping the slots that are connected to the signal. By connecting to different slot groups, it's possible to predict the order of slot invocation, and to disconnect groups of slots simultaneously.

The GroupCompare parameter decides how the Groups are ordered, and the default is std::less<Group>, which is almost always correct. If a custom type is used for Groups, some other ordering sometimes makes sense.

Finally, the SlotFunction parameter denotes the type of the slot functions, and the default is a boost::function. I am not familiar with any scenarios where changing this default would be wise. This template parameter is used to define the slot type, available through the public typedef slot<SlotFunction> slot_type.

Members

 signal(const Combiner&=Combiner(),   const GroupCompare&=GroupCompare()); 

When constructing a signal, it's possible to pass a Combiner, which is an object responsible for invoking the slots and handling the logic for the values returned when signaling to the slots.

 ~signal(); 

The destructor disconnects all of the slots that are connected at the time of destruction.

 signals::connection connect(const slot_type& s); 

The connect function connects the slot s to the signal. A function pointer, function object, a bind expression, or a lambda expression can be used as slots. connect returns a signals::connection, which is a handle to the created connection. Using that handle, the slot can be disconnected from the signal, or you can test whether the slot is still connected.

 signals::connection connect(const Group& g, const slot_type& s); 

This overloaded version of connect works like the previous one, and in addition, it connects the slot s to the group g. Connecting a slot to a group means that when a signal is signaling, slots that belong to groups that precede other groups are called before those (as described by the ordering for the groups, the GroupCompare parameter to the signal template), and all slots that belong to a group are called before those that aren't (it's possible to have only some of the slots in groups).

 void disconnect(const Group& g); 

Disconnects all of the connected slots that belong to the group g.

 std::size_t num_slots() const; 

Returns the number of slots that are currently connected to the signal. It is preferred to call the function empty rather than test the return value from num_slots against 0, because empty can be more efficient.

 result_type operator()(T1, T2, ..., TN); 

signals are invoked using the function call operator. When signaling, the appropriate arguments must be passed to the function call operator, as described by the signature of the signal (the first template parameter when declaring the signal type). The types of arguments must be implicitly convertible to the types required by the signal for the invocation to succeed.

There are other types available in Boost.Signals, but rather than distract you with a synopsis and discussion of each here, we'll discuss them in detail throughout the rest of this chapter. We will also discuss useful typedefs in the signal class.