Class template slot

boost::signals2::slot — Pass slots as function arguments, and associate tracked objects with a slot.

Synopsis

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

template<typename Signature, 
         typename SlotFunction = boost::function<R (T1, T2, ..., TN)> > 
class slot : public boost::signals2::slot_base {
public:
  // types
  typedef R            result_type;         
  typedef T1           argument_type;         // Exists iff arity == 1
  typedef T1           first_argument_type;   // Exists iff arity == 2
  typedef T2           second_argument_type;  // Exists iff arity == 2
  typedef Signature    signature_type;      
  typedef SlotFunction slot_function_type;  

  // static constants
  static const int arity = N;  // The number of arguments taken by the slot.

  // member classes/structs/unions
  template<unsigned n> 
  class arg {
  public:
    // types
    typedef Tn type;  // The type of the slot's (n+1)th argument
  };

  // construct/copy/destruct
  template<typename Slot> slot(const Slot &);
  template<typename OtherSignature, typename OtherSlotFunction> 
    slot(const slot<OtherSignature, OtherSlotFunction> &);
  template<typename Func, typename Arg1, typename Arg2, ..., typename ArgN> 
    slot(const Func &, const Arg1 &, const Arg2 &, ..., const ArgN &);

  // invocation
  result_type operator()(arg<0>::type, arg<1>::_type, ..., arg<N-1>::type);
  result_type operator()(arg<0>::type, arg<1>::_type, ..., arg<N-1>::type) const;

  // tracking
  slot & track(const weak_ptr<void> &);
  slot & track(const signals2::signal_base &);
  slot & track(const signals2::slot_base &);
  template<typename ForeignWeakPtr> 
    slot & track_foreign(const ForeignWeakPtr &, 
                         typename weak_ptr_traits<ForeignWeakPtr>::shared_type * = 0);
  template<typename ForeignSharedPtr> 
    slot & track_foreign(const ForeignSharedPtr &, 
                         typename shared_ptr_traits<ForeignSharedPtr>::weak_type * = 0);

  // slot function access
  slot_function_type & slot_function();
  const slot_function_type & slot_function() const;
};

Description

A slot consists of a polymorphic function wrapper (boost::function by default) plus a container of weak_ptrs which identify the slot's "tracked objects". If any of the tracked objects expire, the slot will automatically disable itself. That is, the slot's function call operator will throw an exception instead of forwarding the function call to the slot's polymorphic function wrapper. Additionally, a slot will automatically lock all the tracked objects as shared_ptr during invocation, to prevent any of them from expiring while the polymorphic function wrapper is being run.

The slot constructor will search for signals2::signal and signals2::trackable inside incoming function objects and automatically track them. It does so by applying a visitor to the incoming functors with boost::visit_each.

Template Parameters

```
typename Signature
```

typename SlotFunction = boost::function<R (T1, T2, ..., TN)>

`slot` public construct/copy/destruct

template<typename Slot> slot(const Slot & target);

Effects:

Initializes the SlotFunction object in this with target, which may be any function object with which a SlotFunction can be constructed.

In this special case where the template type parameter Slot is a compatible signals2::signal type, the signal will automatically be added to the slot's tracked object list. Otherwise, the slot's tracked object list is initially empty.

template<typename OtherSignature, typename OtherSlotFunction> 
  slot(const slot<OtherSignature, OtherSlotFunction> & other_slot);

Effects:

Initializes this with a copy of other_slot's OtherSlotFunction object and tracked object list.

template<typename Func, typename Arg1, typename Arg2, ..., typename ArgN> 
  slot(const Func & f, const Arg1 & a1, const Arg2 & a2, ..., const ArgN & aN);

Effects:

Syntactic sugar for bind() when the constructor is passed more than one argument. As if: slot(boost::bind(f, a1, a2, ..., aN))

`slot` invocation

result_type operator()(arg<0>::type a1, arg<1>::_type a2, ..., 
                       arg<N-1>::type aN);
result_type operator()(arg<0>::type a1, arg<1>::_type a2, ..., 
                       arg<N-1>::type aN) const;

Effects:	Calls the slot's `SlotFunction` object.
Returns:	The result returned by the slot's `SlotFunction` object.
Throws:	Any exceptions thrown by the slot's `SlotFunction` object. boost::signals2::expired_slot if any object in the tracked object list has expired.
Notes:	If you have already used lock to insure the tracked objects are valid, it is slightly more efficient to use the slot_function() method and call the slot's `SlotFunction` directly.

`slot` tracking

slot & track(const weak_ptr<void> & tracked_object);
slot & track(const signals2::signal_base & tracked_signal);
slot & track(const signals2::slot_base & tracked_slot);

Effects:

Adds object(s) to the slot's tracked object list. Should any of the tracked objects expire, then subsequent attempts to call the slot's operator() or lock() methods will throw an signals2::expired_slot exception.

When tracking a signal, a shared_ptr internal to the signal class is used for tracking. The signal does not need to be owned by an external shared_ptr.

In the case of passing another slot as the argument to track(), only the objects currently in the other slot's tracked object list are added to the tracked object list of this. The other slot object itself is not tracked.

Returns:

*this

template<typename ForeignWeakPtr> 
  slot & track_foreign(const ForeignWeakPtr & tracked_object, 
                       typename weak_ptr_traits<ForeignWeakPtr>::shared_type * SFINAE = 0);
template<typename ForeignSharedPtr> 
  slot & track_foreign(const ForeignSharedPtr & tracked_object, 
                       typename shared_ptr_traits<ForeignSharedPtr>::weak_type * SFINAE = 0);

Effects:

The track_foreign() method behaves similarly to calling the track() method with a boost::shared_ptr or boost::weak_ptr argument. However, track_foreign is more flexible in that it will accept shared_ptr or weak_ptr classes from outside of boost (most significantly std::shared_ptr or std::weak_ptr).

In order to use a particular shared_ptr class with this function, a specialization of boost::signals2::shared_ptr_traits must exist for it. Also, a specialization of boost::signals2::weak_ptr_traits must be provided for its corresponding weak_ptr class. The shared_ptr_traits specialization must include a weak_type member typedef which specifies the corresponding weak_ptr type of the shared_ptr class. Similarly, the weak_ptr_traits specialization must include a shared_type member typedef which specifies the corresponding shared_ptr type of the weak_ptr class. Specializations for std::shared_ptr and std::weak_ptr are already provided by the signals2 library. For other shared_ptr classes, you must provide the specializations.

The second argument "SFINAE" may be ignored, it is used to resolve the overload between either shared_ptr or weak_ptr objects passed in as the first argument.

Returns:

*this

`slot` slot function access

slot_function_type & slot_function();
const slot_function_type & slot_function() const;

Returns:

A reference to the slot's underlying SlotFunction object.