| <?xml version="1.0" encoding="utf-8"?> |
| <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| <!-- |
| Copyright Douglas Gregor 2001-2004 |
| Copyright Frank Mori Hess 2007-2009 |
| |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| --> |
| <header name="boost/signals2/slot.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $"> |
| <using-namespace name="boost::signals2"/> |
| <using-namespace name="boost"/> |
| <using-class name="boost::signals2::signal"/> |
| <using-class name="boost::signals2::slot_base"/> |
| <namespace name="boost"> |
| <namespace name="signals2"> |
| <class name="slot"> |
| <template> |
| <template-type-parameter name="Signature"> |
| <purpose>Function type R (T1, T2, ..., TN)</purpose> |
| </template-type-parameter> |
| <template-type-parameter name="SlotFunction"> |
| <default><classname>boost::function</classname><R (T1, T2, ..., TN)></default> |
| </template-type-parameter> |
| </template> |
| <inherit access="public"> |
| <type><classname>boost::signals2::slot_base</classname></type> |
| </inherit> |
| <purpose>Pass slots as function arguments, and associate tracked objects with a slot.</purpose> |
| |
| <description> |
| <para>A slot consists of a polymorphic function wrapper (<classname>boost::function</classname> by default) |
| plus a container of <code>weak_ptr</code>s 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 <code>shared_ptr</code> during invocation, to prevent any of them from expiring while |
| the polymorphic function wrapper is being run. |
| </para> |
| <para> |
| The slot constructor will search for <classname>signals2::signal</classname> and |
| <classname>signals2::trackable</classname> inside incoming function objects and |
| automatically track them. It does so by applying a visitor |
| to the incoming functors with <functionname>boost::visit_each</functionname>. |
| </para> |
| </description> |
| |
| <typedef name="result_type"> |
| <type>R</type> |
| </typedef> |
| <typedef name="argument_type"> |
| <type>T1</type> |
| <purpose>Exists iff arity == 1</purpose> |
| </typedef> |
| <typedef name="first_argument_type"> |
| <type>T1</type> |
| <purpose>Exists iff arity == 2</purpose> |
| </typedef> |
| <typedef name="second_argument_type"> |
| <type>T2</type> |
| <purpose>Exists iff arity == 2</purpose> |
| </typedef> |
| <typedef name="signature_type"> |
| <type>Signature</type> |
| </typedef> |
| <typedef name="slot_function_type"> |
| <type>SlotFunction</type> |
| </typedef> |
| |
| <class name="arg"> |
| <template> |
| <template-nontype-parameter name="n"> |
| <type>unsigned</type> |
| </template-nontype-parameter> |
| </template> |
| <typedef name="type"> |
| <type>Tn</type> |
| <purpose>The type of the <classname alt="signals2::slot">slot</classname>'s (n+1)th argument</purpose> |
| </typedef> |
| </class> |
| |
| <static-constant name="arity"> |
| <type>int</type> |
| <default>N</default> |
| <purpose>The number of arguments taken by the slot.</purpose> |
| </static-constant> |
| |
| <constructor> |
| <template> |
| <template-type-parameter name="Slot"/> |
| </template> |
| |
| <parameter name="target"> |
| <paramtype>const Slot &</paramtype> |
| </parameter> |
| |
| <effects> |
| <para>Initializes the <code>SlotFunction</code> object in <code>this</code> |
| with <code>target</code>, which may be any |
| function object with which a |
| <code>SlotFunction</code> can be |
| constructed. |
| </para> |
| <para>In this special case where the template type parameter <code>Slot</code> is |
| a compatible <classname>signals2::signal</classname> type, |
| the signal will automatically be added to the slot's tracked object list. |
| Otherwise, the slot's tracked object list is initially empty. |
| </para> |
| </effects> |
| </constructor> |
| <constructor> |
| <template> |
| <template-type-parameter name="OtherSignature"/> |
| <template-type-parameter name="OtherSlotFunction"/> |
| </template> |
| |
| <parameter name="other_slot"> |
| <paramtype>const slot<OtherSignature, OtherSlotFunction> &</paramtype> |
| </parameter> |
| |
| <effects> |
| <para>Initializes <code>this</code> with a copy of |
| <code>other_slot</code>'s <code>OtherSlotFunction</code> object and tracked object list. |
| </para></effects> |
| </constructor> |
| <constructor> |
| <template> |
| <template-type-parameter name="Func"/> |
| <template-type-parameter name="Arg1"/> |
| <template-type-parameter name="Arg2"/> |
| <template-varargs/> |
| <template-type-parameter name="ArgN"/> |
| </template> |
| |
| <parameter name="f"> |
| <paramtype>const Func &</paramtype> |
| </parameter> |
| <parameter name="a1"> |
| <paramtype>const Arg1 &</paramtype> |
| </parameter> |
| <parameter name="a2"> |
| <paramtype>const Arg2 &</paramtype> |
| </parameter> |
| <parameter> |
| <paramtype>...</paramtype> |
| </parameter> |
| <parameter name="aN"> |
| <paramtype>const ArgN &</paramtype> |
| </parameter> |
| |
| <effects> |
| <para>Syntactic sugar for <code>bind()</code> when the constructor is passed more than |
| one argument. As if: |
| <code>slot(boost::bind(f, a1, a2, ..., aN))</code> |
| </para></effects> |
| </constructor> |
| |
| <method-group name="invocation"> |
| <overloaded-method name="operator()"> |
| <signature> |
| <type>result_type</type> |
| <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter> |
| <parameter name="a2"><paramtype>arg<1>::_type</paramtype></parameter> |
| <parameter><paramtype>...</paramtype></parameter> |
| <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter> |
| </signature> |
| |
| <signature cv="const"> |
| <type>result_type</type> |
| <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter> |
| <parameter name="a2"><paramtype>arg<1>::_type</paramtype></parameter> |
| <parameter><paramtype>...</paramtype></parameter> |
| <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter> |
| </signature> |
| |
| <effects><para>Calls the slot's <code>SlotFunction</code> object. |
| </para></effects> |
| |
| <returns><para>The result returned by the slot's <code>SlotFunction</code> object.</para></returns> |
| |
| <throws><para>Any exceptions thrown by the slot's <code>SlotFunction</code> object. |
| <classname>boost::signals2::expired_slot</classname> if any object in the tracked object list |
| has expired.</para></throws> |
| |
| <notes><para>If you have already used <methodname>lock</methodname> to insure the |
| tracked objects are valid, it is slightly more efficient to use the |
| <methodname>slot_function</methodname>() method |
| and call the slot's <code>SlotFunction</code> directly.</para> |
| </notes> |
| </overloaded-method> |
| </method-group> |
| |
| <method-group name="tracking"> |
| <overloaded-method name="track"> |
| <signature> |
| <type>slot &</type> |
| <parameter name="tracked_object"> |
| <paramtype>const weak_ptr<void> &</paramtype> |
| </parameter> |
| </signature> |
| <signature> |
| <type>slot &</type> |
| <parameter name="tracked_signal"> |
| <paramtype>const <classname>signals2::signal_base</classname> &</paramtype> |
| </parameter> |
| </signature> |
| <signature> |
| <type>slot &</type> |
| <parameter name="tracked_slot"> |
| <paramtype>const <classname>signals2::slot_base</classname> &</paramtype> |
| </parameter> |
| </signature> |
| <effects> |
| <para> |
| 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 <code>operator()</code> |
| or <code>lock()</code> methods will throw an <classname>signals2::expired_slot</classname> exception. |
| </para> |
| <para>When tracking a signal, a <classname>shared_ptr</classname> |
| internal to the signal class is used for tracking. The signal does not |
| need to be owned by an external <code>shared_ptr</code>. |
| </para> |
| <para> |
| In the case of passing another slot as the argument to <code>track()</code>, |
| only the objects currently in the other slot's tracked object list are added |
| to the tracked object list of <code>this</code>. The other slot object itself |
| is not tracked. |
| </para> |
| </effects> |
| <returns><para><code>*this</code></para></returns> |
| </overloaded-method> |
| <overloaded-method name="track_foreign"> |
| <signature> |
| <template> |
| <template-type-parameter name="ForeignWeakPtr"/> |
| </template> |
| <type>slot &</type> |
| <parameter name="tracked_object"> |
| <paramtype>const ForeignWeakPtr &</paramtype> |
| </parameter> |
| <parameter name="SFINAE"> |
| <paramtype>typename weak_ptr_traits<ForeignWeakPtr>::shared_type *</paramtype> |
| <default>0</default> |
| </parameter> |
| </signature> |
| <signature> |
| <template> |
| <template-type-parameter name="ForeignSharedPtr"/> |
| </template> |
| <type>slot &</type> |
| <parameter name="tracked_object"> |
| <paramtype>const ForeignSharedPtr &</paramtype> |
| </parameter> |
| <parameter name="SFINAE"> |
| <paramtype>typename shared_ptr_traits<ForeignSharedPtr>::weak_type *</paramtype> |
| <default>0</default> |
| </parameter> |
| </signature> |
| <effects> |
| <para> |
| The <code>track_foreign</code>() method behaves similarly to calling the <methodname>track</methodname>() method |
| with a <classname>boost::shared_ptr</classname> or <classname>boost::weak_ptr</classname> argument. |
| However, <code>track_foreign</code> is more flexible in that it will accept <code>shared_ptr</code> |
| or <code>weak_ptr</code> classes from outside of boost (most significantly <code>std::shared_ptr</code> |
| or <code>std::weak_ptr</code>). |
| </para> |
| <para> |
| In order to use a particular <code>shared_ptr</code> class with this function, a specialization of |
| <classname>boost::signals2::shared_ptr_traits</classname> must exist for it. |
| Also, a specialization of <classname>boost::signals2::weak_ptr_traits</classname> must |
| be provided for its corresponding <code>weak_ptr</code> class. |
| The <code>shared_ptr_traits</code> specialization must include a <code>weak_type</code> |
| member typedef which specifies the |
| corresponding <code>weak_ptr</code> type of the <code>shared_ptr</code> class. |
| Similarly, the <code>weak_ptr_traits</code> specialization must include a <code>shared_type</code> |
| member typedef which specifies the corresponding <code>shared_ptr</code> type of the |
| <code>weak_ptr</code> class. Specializations |
| for <code>std::shared_ptr</code> and <code>std::weak_ptr</code> are already provided by the signals2 library. |
| For other <code>shared_ptr</code> classes, you must provide the specializations. |
| </para> |
| <para>The second argument "SFINAE" may be ignored, it is used to resolve the overload between |
| either <code>shared_ptr</code> or <code>weak_ptr</code> objects passed in as the first argument. |
| </para> |
| </effects> |
| <returns><para><code>*this</code></para></returns> |
| </overloaded-method> |
| </method-group> |
| |
| <method-group name="slot function access"> |
| <overloaded-method name="slot_function"> |
| <signature> |
| <type>slot_function_type &</type> |
| </signature> |
| <signature cv="const"> |
| <type>const slot_function_type &</type> |
| </signature> |
| <returns><para>A reference to the slot's underlying SlotFunction object.</para></returns> |
| </overloaded-method> |
| </method-group> |
| </class> |
| </namespace> |
| </namespace> |
| </header> |