| Home | Libraries | People | FAQ | More

## Class template signalN

boost::signals2::signalN — Set of safe multicast callback types.

## Synopsis

    // In header: <boost/signals2/signal.hpp>

    template<typename R, typename T1, typename T2, ..., typename TN,
             typename Combiner = optional_last_value<R>, typename Group = int,
             typename GroupCompare = std::less<Group>,
             typename SlotFunction = functionN<R, T1, T2, ..., TN>,
             typename ExtendedSlotFunction = functionN<R, const connection &, T1, T2, ..., TN>,
             typename Mutex = mutex>
    class signalN : public signal_base {
    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 typename slotN<R, T1, T2, ..., TN, SlotFunction>                         slot_type;
      typedef ExtendedSlotFunction                                                     extended_slot_function_type;
      typedef typename slotN<R, const connection &, T1, ..., TN, ExtendedSlotFunction> extended_slot_type;
      typedef implementation-detail 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
      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()(arg1_type, arg2_type, ..., argN_type);
      result_type operator()(arg1_type, arg2_type, ..., argN_type) const;

      // combiner access
      combiner_type combiner() const;
      void set_combiner(const combiner_type&);
    };

## Description

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` public types

1. typedef typename slotN<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 connection argument in its signature, which gives slot functions access to their connection to the signal invoking them.

2. typedef implementation-detail slot_result_type;

   This is the type returned when dereferencing the input iterators passed to the signal's combiner. It is usually `slot_function_type::result_type` unless that type is `void`, in which case `slot_result_type` is unspecified.

### `signalN` public construct/copy/destruct

1.     signalN(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()`

2.     ~signalN();

   Effects: | Disconnects all slots connected to `*this`.

### `signalN` connection management

1.     connection 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 `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 `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.

2.     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 the connection.

3.     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 `slot_func` argument should not be an actual signals2::slot object (which does not even support `operator==`), but rather the functor you wrapped inside a signals2::slot when you initially made the connection.
   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.

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

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

6.     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` invocation

1.     result_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`.

### `signalN` combiner access

1.     combiner_type combiner() const;

   Returns: | A copy of the stored combiner.
   Throws: | Will not throw.

2.     void set_combiner(const combiner_type& combiner);

   Effects: | Copies a new combiner into the signal for use with future signal invocations.
   Throws: | Will not throw.