...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::signals2::signal — Safe multicast callback.
// In header: <boost/signals2/signal.hpp> template<typename Signature, typename Combiner = boost::signals2::optional_last_value<R>, typename Group = int, typename GroupCompare = std::less<Group>, typename SlotFunction = boost::function<Signature>, typename ExtendedSlotFunction = boost::function<R (const connection &, T1, T2, ..., TN)>, typename Mutex = boost::signals2::mutex> class signal : public boost::signals2::signal_base { public: // types typedef Signature signature_type; typedef typename Combiner::result_type result_type; typedef Combiner combiner_type; typedef Group group_type; typedef GroupCompare group_compare_type; typedef SlotFunction slot_function_type; typedef typename signals2::slot<Signature, SlotFunction> slot_type; typedef ExtendedSlotFunction extended_slot_function_type; typedef typename signals2::slot<R (const connection &, T1, ..., TN), ExtendedSlotFunction> extended_slot_type; typedef typename SlotFunction::result_type slot_result_type; typedef unspecified slot_call_iterator; typedef T1 argument_type; // Exists iff arity == 1 typedef T1 first_argument_type; // Exists iff arity == 2 typedef T2 second_argument_type; // Exists iff arity == 2 // static constants static const int arity = N; // The number of arguments taken by the signal. // member classes/structs/unions template<unsigned n> class arg { public: // types typedef Tn type; // The type of the signal's (n+1)th argument }; // construct/copy/destruct signal(const combiner_type& = combiner_type(), const group_compare_type& = group_compare_type()); signal(signal &&); signal& operator=(signal &&); // connection management connection connect(const slot_type&, connect_position = at_back); connection connect(const group_type&, const slot_type&, connect_position = at_back); connection connect_extended(const extended_slot_type&, connect_position = at_back); connection connect_extended(const group_type&, const extended_slot_type&, connect_position = at_back); void disconnect(const group_type&); template<typename S> void disconnect(const S&); void disconnect_all_slots(); bool empty() const; std::size_t num_slots() const; // invocation result_type operator()(arg<0>::type, arg<1>::type, ..., arg<N-1>::type); result_type operator()(arg<0>::type, arg<1>::type, ..., arg<N-1>::type) const; // combiner access combiner_type combiner() const; void set_combiner(const combiner_type&); // modifiers void swap(signal&); }; // specialized algorithms template<typename Signature, typename Combiner, typename Group, typename GroupCompare, typename SlotFunction, typename ExtendedSlotFunction, typename Mutex> void swap(signal<Signature, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex>&, signal<Signature, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex>&);
See the tutorial for more information on how to use the signal class.
typename Signature
typename Combiner = boost::signals2::optional_last_value<R>
typename Group = int
typename GroupCompare = std::less<Group>
typename SlotFunction = boost::function<Signature>
typename ExtendedSlotFunction = boost::function<R (const connection &, T1, T2, ..., TN)>
typename Mutex = boost::signals2::mutex
signal
public
typestypedef typename signals2::slot<R (const connection &, T1, ..., TN), ExtendedSlotFunction> extended_slot_type;
Slots of the extended_slot_type
may be connected to the signal using the
connect_extended methods. The extended_slot_type
has an additional signals2::connection argument in its signature,
which gives slot functions access to their connection to the signal
invoking them.
typedef typename SlotFunction::result_type slot_result_type;
This is the type returned when dereferencing the input iterators passed to the signal's combiner.
typedef unspecified slot_call_iterator;
The input iterator type passed to the combiner when the signal is invoked.
signal
public
construct/copy/destructsignal(const combiner_type& combiner = combiner_type(), const group_compare_type& compare = group_compare_type());
Effects: |
Initializes the signal to contain no slots, copies the given combiner into internal storage, and stores the given group comparison function object to compare groups. |
Postconditions: |
|
signal(signal && other);
Move constructor.
Postconditions: |
The signal |
Throws: |
Will not throw. |
signal& operator=(signal && rhs);
Move assignment.
Postconditions: |
The signal |
Throws: |
Will not throw. |
signal
connection managementconnection connect(const slot_type& slot, connect_position at = at_back); connection connect(const group_type& group, const slot_type& slot, connect_position at = at_back);
Effects: |
Connects the signal this to the incoming
slot. If the slot is inactive, i.e., any of the slots's tracked
objects have been destroyed, then the
call to connect is a no-op. If the second version of
|
Returns: |
A
|
Throws: |
This routine meets the strong exception guarantee, where any exception thrown will cause the slot to not be connected to the signal. |
Complexity: |
Constant time when connecting a slot without a group name or logarithmic in the number of groups when connecting to a particular group. |
Notes: |
It is unspecified whether connecting a slot while the signal is calling will result in the slot being called immediately. |
connection connect_extended(const extended_slot_type& slot, connect_position at = at_back); connection connect_extended(const group_type& group, const extended_slot_type& slot, connect_position at = at_back);
The connect_extended
methods work the same as the connect
methods, except they take slots of type extended_slot_type
.
This is useful if a slot needs to access the connection between it and the
signal invoking it, for example if it wishes to disconnect or block its own connection.
void disconnect(const group_type& group); template<typename S> void disconnect(const S& slot_func);
Effects: |
If the parameter is (convertible to) a group name, any slots in the given group are disconnected. Otherwise, any slots equal to the given slot function are disconnected. Note, the |
Throws: |
Will not throw unless a user destructor or
equality operator |
Complexity: |
If a group is given, O(lg g) + k where g is the number of groups in the signal and k is the number of slots in the group. Otherwise, linear in the number of slots connected to the signal. |
void disconnect_all_slots();
Effects: |
Disconnects all slots connected to the signal. |
Postconditions: |
|
Throws: |
If disconnecting a slot causes an exception to be thrown, not all slots may be disconnected. |
Complexity: |
Linear in the number of slots known to the signal. |
Notes: |
May be called at any time within the lifetime of the signal, including during calls to the signal's slots. |
bool empty() const;
Returns: |
|
Throws: |
Will not throw. |
Complexity: |
Linear in the number of slots known to the signal. |
Rationale: |
Slots can disconnect at any point in time, including while those same slots are being invoked. It is therefore possible that the implementation must search through a list of disconnected slots to determine if any slots are still connected. |
std::size_t num_slots() const;
Returns: |
The number of slots connected to the signal |
Throws: |
Will not throw. |
Complexity: |
Linear in the number of slots known to the signal. |
Rationale: |
Slots can disconnect at any point in time, including while those same slots are being invoked. It is therefore possible that the implementation must search through a list of disconnected slots to determine how many slots are still connected. |
signal
invocationresult_type operator()(arg<0>::type a1, arg<1>::type a2, ..., arg<N-1>::type aN); result_type operator()(arg<0>::type a1, arg<1>::type a2, ..., arg<N-1>::type aN) const;
Effects: |
Invokes the combiner with a
|
Returns: |
The result returned by the combiner. |
Throws: |
If an exception is thrown by a slot call, or if the combiner does not dereference any slot past some given slot, all slots after that slot in the internal list of connected slots will not be invoked. |
Notes: |
Only the slots associated with iterators that are actually dereferenced will be invoked. Multiple dereferences of the same iterator will not result in multiple slot invocations, because the return value of the slot will be cached. The |
signal
modifiersvoid swap(signal& other);
Effects: |
Swaps the signal referenced in
|
Throws: |
Will not throw. |
signal
specialized algorithmstemplate<typename Signature, typename Combiner, typename Group, typename GroupCompare, typename SlotFunction, typename ExtendedSlotFunction, typename Mutex> void swap(signal<Signature, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex>& x, signal<Signature, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex>& y);
Effects: |
|
Throws: |
Will not throw. |