signalN
N is the number of signal parameters supported. So the header <boost/signals/signal0.hpp>
contains signal0
, header <boost/signals/signal1.hpp>
contains signal1
, etc. The maximum number of signal parameters supported is implementation-defined, but must be at least 10.
#include <boost/signals/signalN.hpp>
This document 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.
namespace boost {
template<typename R,
typename T1,
typename T2,
...
typename TN,
typename Combiner = last_value<R>,
typename Group = int,
typename GroupCompare = std::less<Group>,
typename SlotFunction = boost::functionN<R, T1, T2, ..., TN> >
class signalN :
boost::noncopyable // exposition only: class meets Noncopyable requirement,
boost::trackable
{
public:
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<slot_function_type> slot_type;
typedef implementation-defined slot_result_type; // if SlotFunction has a void return type, may not be void; otherwise it is the SlotFunction return type
typedef implementation-defined slot_call_iterator; // InputIterator with value_type R
.
typedef T1 argument_type; // If N == 1 then signal models AdaptableUnaryFunction
typedef T1 first_argument_type; // If N==2 then signal models AdaptableBinaryFunction
typedef T2 second_argument_type; // If N==2 then signal models AdaptableBinaryFunction
typedef T1 arg1_type;
typedef T2 arg2_type;
.
.
.
typedef TN argN_type;
explicit signalN(const combiner_type& = combiner_type(), const group_compare_type& = group_compare_type());
~signal();
signals::connection connect(const slot_type&);
signals::connection connect(const group_type&, const slot_type& slot);
void disconnect(const group_type&);
void disconnect_all_slots();
bool empty() const;
result_type operator()(T1 a1, T2 a2, ..., TN aN);
result_type operator()(T1 a1, T2 a2, ..., TN aN) const;
private:
combiner_type combiner; // exposition only
};
}
A Combiner is a function object that accepts an iterator sequence [first, last)
and dereferences some number of the iterators within the sequence, then returns a value. The type of the iterators passed to the combiner will be the slot call iterator type.
The slot group defines the type to be used to group connections. It must be DefaultConstructible
and CopyConstructible
.
The group comparison is a BinaryPredicate
where the argument types coincide with the group type. It defines an ordering relation on the connection groups.
The slot function type must be a function object adaptor capable of being constructed with another compatible function object (where "compatible" is defined by the slot function type itself). The slot function type must accept parameters of types T1, T2, ..., TN
and must return a result that is convertible to the template type parameter R
of the signal; note that when R
is void, any slot function return type will be ignored.
For connections to other signals and to function object
references, the slot function type must be able to accept reference_wrapper
objects.
type slot_result_type
: when the SlotFunction
returns void
, the slot result type may be an implementation-defined type; otherwise, the slot result type must be the type retuned by SlotFunction
function objects.
type slot_call_iterator
: an InputIterator
whose value_type
is R
. The dereference operator of the slot_call_iterator
is responsible for invoking the underlying slot given a specific set of arguments, and returning its result. The result must be cached to ensure that multiple dereferences of an iterator do not invoke the slot multiple times.
explicit signalN(const combiner_type& = combiner_type(), const group_compare_type& = group_compare_type());
this->empty();
signals::connection connect(const slot_type& slot);
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.signals::connection
object that
references the newly-created connection between the signal and
the slot; if the slot
is inactive, returns a
disconnected connection.signals::connection connect(const group_type& group, const slot_type& slot);
connect(slot)
), and associates this slot connection with the given group group
.
signals::connection
object
that references the newly-created connection between the signal and
the slot.void disconnect(const group_type& group);
this->empty()
.true
if no slots are connected to the signal, and false
otherwise.
result_type operator()(T1 a1, T2 a2, ..., TN aN); result_type operator()(T1 a1, T2 a2, ..., TN aN) const;
slot_call_iterator
range [first, last)
(i.e., combiner(first, last)
) that iterates over the
results of calling each slot with the given set of parameters
a1, a2, ..., aN
. Slots are called according to
the partial ordering given by the group comparison function object,
with ungrouped slots called last. 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
.
Ordering between members of a given group or between ungrouped slots is unspecified.
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).