123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304 |
- <?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>
|