# Boost.Signals: class templates `signalN`

## Headers

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>

## Synopsis

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
      };
    }

## Associated Types

### Combiner

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.

### Group

The slot group defines the type to be used to group connections. It must be `DefaultConstructible` and `CopyConstructible`.

### Group comparison

The group comparison is a `BinaryPredicate` where the argument types coincide with the group type. It defines an ordering relation on the connection groups.

### Slot Function

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.

## Members

### Slot Result Type

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.

### Slot Call Iterator

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.

### Constructor

`explicit signalN(const combiner_type& = combiner_type(), const group_compare_type& = 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();`

### Destructor

`~signal();`

- Effects: disconnects all slot connections.

### Connection Management

`signals::connection connect(const slot_type& slot);`

- 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.
- Returns: 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: strong exception guarantee, where any exception thrown will cause the slot to not be connected to the signal.
- Complexity: O(lg n) where n is the number of slots known to the signal.
- Notes: it is unspecified whether connecting a slot while the signal is calling will result in the slot being called immediately.

`signals::connection connect(const group_type& group, const slot_type& slot);`

- Effects: connects the given slot to the signal (i.e., `connect(slot)`), and associates this slot connection with the given group `group`.
- Returns: returns a `signals::connection` object that references the newly-created connection between the signal and the slot.
- Throws: strong exception guarantee, where any exception thrown will cause the slot to not be connected to the signal.
- Complexity: O(lg n) where n is the number of slots known to the signal.
- 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);`

- Effects: any slots in the given group are disconnected.
- Throws: will not throw unless a user destructor throws. If a user destructor throws, not all slots in this group may be disconnected.
- Complexity: O(lg n) + k where n is the number of slots known to the signal and k is the number of .

`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: 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.

### Signal Invocation

    result_type operator()(T1 a1, T2 a2, ..., TN aN);
    result_type operator()(T1 a1, T2 a2, ..., TN aN) const;

- Effects: invokes the combiner with a `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.
- 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: 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`.

  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).

Last modified: Fri Oct 11 05:42:42 EDT 2002