|
Home | Libraries | People | FAQ | More |
boost::signalN — Set of safe multicast callback types.
template<typename R, typename T1, typename T2, ..., typename TN, typename Combiner = last_value<R>, typename Group = int, typename GroupCompare = std::less<Group>, typename SlotFunction = functionN<R, T1, T2, ..., TN> > class signalN : public signals::trackable, private noncopyable // Exposition only { public: // types 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 slot<SlotFunction> slot_type; typedef unspecified slot_result_type; typedef unspecified slot_call_iterator; typedef T1 argument_type; // If N == 1 typedef T1 first_argument_type; // If N == 2 typedef T2 second_argument_type; // If N == 2 typedef T1 arg1_type; typedef T2 arg2_type; . . . typedef TN argN_type; // static constants static const int arity = N; // construct/copy/destruct signalN(const combiner_type& = combiner_type(), const group_compare_type& = group_compare_type()); ~signalN(); // connection management signals::connection connect(const slot_type&, signals::connect_position = signals::at_back); signals::connection connect(const group_type&, const slot_type&, signals::connect_position = signals::at_back); void disconnect(const group_type&); template<typename Slot> void disconnect(const Slot&); void disconnect_all_slots(); bool empty() const; std::size_t num_slots() const; // invocation result_type operator()(arg1_type, arg2_type, ..., argN_type); result_type operator()(arg1_type, arg2_type, ..., argN_type) const; // combiner access combiner_type& combiner(); const combiner_type& combiner() const; };
The class template signalN covers several related classes signal0, signal1, signal2, etc., where the number suffix describes the number of function parameters the signal and its connected slots will take. Instead of enumerating all classes, a single pattern signalN will be described, where N represents the number of function parameters.
signalN construct/copy/destructsignalN(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:
this->empty()
~signalN();
Effects:
Disconnects all slots connected to *this.
signalN connection managementsignals::connection connect(const slot_type& slot, signals::connect_position at = signals::at_back); signals::connection connect(const group_type& group, const slot_type& slot, signals::connect_position at = signals::at_back);
Effects:
Connects the signal this to the incoming
slot. If the slot is inactive, i.e., any of the trackable
objects bound by the slot call have been destroyed, then the
call to connect is a no-op. If the second version of
connect is invoked, the
slot is associated with the given group. The at
parameter specifies where the slot should be connected:
at_front indicates that the slot will be
connected at the front of the list or group of slots and
at_back indicates that the slot will be
connected at the back of the list or group of
slots.
Returns:
A
signals::connection
object that references the newly-created connection between
the signal and the slot; if the slot is inactive, returns a
disconnected connection.
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.
void disconnect(const group_type& group); template<typename Slot> void disconnect(const Slot& slot);
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
are disconnected.
Throws:
Will not throw unless a user destructor or
equality operator == throws. If either throws,
not all slots may be disconnected.
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:
this->empty().
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:
true if no slots
are connected to the signal, and
false otherwise.
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.
signalN invocationresult_type operator()(arg1_type a1, arg2_type a2, ... , argN_type aN); result_type operator()(arg1_type a1, arg2_type a2, ... , argN_type aN) const;
Effects:
Invokes the combiner with a
slot_call_iterator range
[first, last) corresponding to the sequence of calls to the
slots connected to signal
*this. Dereferencing an
iterator in this range causes a slot call with the given set
of parameters (a1, a2, ...,
aN), the result of which is returned from
the iterator dereference operation.
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 const version of
the function call operator will invoke the combiner as
const, whereas the
non-const version will
invoke the combiner as
non-const.
Calling the function call operator may invoke undefined behavior if no slots are connected to the signal, depending on the combiner used. The default combiner is well-defined for zero slots when the return type is void but is undefined when the return type is any other type (because there is no way to synthesize a return value).
| Copyright © 2001-2004 Douglas Gregor |