Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is an old version of boost. Click here for the latest version's documentation home page.
Class template signalN
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore

Class template signalN

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

Synopsis

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::connection connect(const group_type&, const slot_type&);
  void disconnect(const group_type&);
  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;
};

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 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. signals::connection connect(const slot_type& slot);
    signals::connection connect(const group_type& group, 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. If the second version of connect is invoked, the slot is associated with the given group.
    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: 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.

  2. 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 slots in the group.

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

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

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

    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 revised: , at GMTCopyright © 2001-2003 Douglas Gregor