ceph/src/boost/libs/signals2/doc/reference/slot.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4 <!--
   5 Copyright Douglas Gregor 2001-2004
   6 Copyright Frank Mori Hess 2007-2009
   7
   8 Distributed under the Boost Software License, Version 1.0. (See accompanying
   9 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  10 -->
  11 <header name="boost/signals2/slot.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
  12   <using-namespace name="boost::signals2"/>
  13   <using-namespace name="boost"/>
  14   <using-class name="boost::signals2::signal"/>
  15   <using-class name="boost::signals2::slot_base"/>
  16   <namespace name="boost">
  17     <namespace name="signals2">
  18       <class name="slot">
  19         <template>
  20           <template-type-parameter name="Signature">
  21             <purpose>Function type R (T1, T2, ..., TN)</purpose>
  22           </template-type-parameter>
  23           <template-type-parameter name="SlotFunction">
  24             <default><classname>boost::function</classname>&lt;R (T1, T2, ..., TN)&gt;</default>
  25           </template-type-parameter>
  26         </template>
  27         <inherit access="public">
  28           <type><classname>boost::signals2::slot_base</classname></type>
  29         </inherit>
  30         <purpose>Pass slots as function arguments, and associate tracked objects with a slot.</purpose>
  31
  32         <description>
  33           <para>A slot consists of a polymorphic function wrapper (<classname>boost::function</classname> by default)
  34             plus a container of <code>weak_ptr</code>s which identify the slot's "tracked objects".  If any of the
  35             tracked objects expire, the slot will automatically disable itself.  That is, the slot's function
  36             call operator will throw an exception instead of forwarding the function call to the slot's
  37             polymorphic function wrapper.  Additionally, a slot will automatically lock all the tracked objects
  38             as <code>shared_ptr</code> during invocation, to prevent any of them from expiring while
  39             the polymorphic function wrapper is being run.
  40           </para>
  41           <para>
  42             The slot constructor will search for <classname>signals2::signal</classname> and
  43             <classname>signals2::trackable</classname> inside incoming function objects and
  44             automatically track them.  It does so by applying a visitor
  45             to the incoming functors with <functionname>boost::visit_each</functionname>.
  46           </para>
  47         </description>
  48
  49         <typedef name="result_type">
  50           <type>R</type>
  51         </typedef>
  52         <typedef name="argument_type">
  53           <type>T1</type>
  54           <purpose>Exists iff arity == 1</purpose>
  55         </typedef>
  56         <typedef name="first_argument_type">
  57           <type>T1</type>
  58           <purpose>Exists iff arity == 2</purpose>
  59         </typedef>
  60         <typedef name="second_argument_type">
  61           <type>T2</type>
  62           <purpose>Exists iff arity == 2</purpose>
  63         </typedef>
  64         <typedef name="signature_type">
  65           <type>Signature</type>
  66         </typedef>
  67         <typedef name="slot_function_type">
  68           <type>SlotFunction</type>
  69         </typedef>
  70
  71         <class name="arg">
  72           <template>
  73             <template-nontype-parameter name="n">
  74               <type>unsigned</type>
  75             </template-nontype-parameter>
  76           </template>
  77           <typedef name="type">
  78             <type>Tn</type>
  79             <purpose>The type of the <classname alt="signals2::slot">slot</classname>'s (n+1)th argument</purpose>
  80           </typedef>
  81         </class>
  82
  83         <static-constant name="arity">
  84           <type>int</type>
  85           <default>N</default>
  86           <purpose>The number of arguments taken by the slot.</purpose>
  87         </static-constant>
  88
  89         <constructor>
  90           <template>
  91             <template-type-parameter name="Slot"/>
  92           </template>
  93
  94           <parameter name="target">
  95             <paramtype>const Slot &amp;</paramtype>
  96           </parameter>
  97
  98           <effects>
  99             <para>Initializes the <code>SlotFunction</code> object in <code>this</code>
 100             with <code>target</code>, which may be any
 101             function object with which a
 102             <code>SlotFunction</code> can be
 103             constructed.
 104             </para>
 105             <para>In this special case where the template type parameter <code>Slot</code> is
 106               a compatible <classname>signals2::signal</classname> type,
 107               the signal will automatically be added to the slot's tracked object list.
 108               Otherwise, the slot's tracked object list is initially empty.
 109             </para>
 110           </effects>
 111         </constructor>
 112       <constructor>
 113           <template>
 114             <template-type-parameter name="OtherSignature"/>
 115             <template-type-parameter name="OtherSlotFunction"/>
 116           </template>
 117
 118           <parameter name="other_slot">
 119             <paramtype>const slot&lt;OtherSignature, OtherSlotFunction&gt; &amp;</paramtype>
 120           </parameter>
 121
 122           <effects>
 123             <para>Initializes <code>this</code> with a copy of
 124             <code>other_slot</code>'s <code>OtherSlotFunction</code> object and tracked object list.
 125             </para></effects>
 126         </constructor>
 127         <constructor>
 128           <template>
 129             <template-type-parameter name="Func"/>
 130             <template-type-parameter name="Arg1"/>
 131             <template-type-parameter name="Arg2"/>
 132             <template-varargs/>
 133             <template-type-parameter name="ArgN"/>
 134           </template>
 135
 136           <parameter name="f">
 137             <paramtype>const Func &amp;</paramtype>
 138           </parameter>
 139           <parameter name="a1">
 140             <paramtype>const Arg1 &amp;</paramtype>
 141           </parameter>
 142           <parameter name="a2">
 143             <paramtype>const Arg2 &amp;</paramtype>
 144           </parameter>
 145           <parameter>
 146             <paramtype>...</paramtype>
 147           </parameter>
 148           <parameter name="aN">
 149             <paramtype>const ArgN &amp;</paramtype>
 150           </parameter>
 151
 152           <effects>
 153             <para>Syntactic sugar for <code>bind()</code> when the constructor is passed more than
 154               one argument.  As if:
 155             <code>slot(boost::bind(f, a1, a2, ..., aN))</code>
 156             </para></effects>
 157         </constructor>
 158
 159         <method-group name="invocation">
 160           <overloaded-method name="operator()">
 161             <signature>
 162               <type>result_type</type>
 163               <parameter name="a1"><paramtype>arg&lt;0&gt;::type</paramtype></parameter>
 164               <parameter name="a2"><paramtype>arg&lt;1&gt;::_type</paramtype></parameter>
 165               <parameter><paramtype>...</paramtype></parameter>
 166               <parameter name="aN"><paramtype>arg&lt;N-1&gt;::type</paramtype></parameter>
 167             </signature>
 168
 169             <signature cv="const">
 170               <type>result_type</type>
 171               <parameter name="a1"><paramtype>arg&lt;0&gt;::type</paramtype></parameter>
 172               <parameter name="a2"><paramtype>arg&lt;1&gt;::_type</paramtype></parameter>
 173               <parameter><paramtype>...</paramtype></parameter>
 174               <parameter name="aN"><paramtype>arg&lt;N-1&gt;::type</paramtype></parameter>
 175             </signature>
 176
 177             <effects><para>Calls the slot's <code>SlotFunction</code> object.
 178             </para></effects>
 179
 180             <returns><para>The result returned by the slot's <code>SlotFunction</code> object.</para></returns>
 181
 182             <throws><para>Any exceptions thrown by the slot's <code>SlotFunction</code> object.
 183             <classname>boost::signals2::expired_slot</classname> if any object in the tracked object list
 184             has expired.</para></throws>
 185
 186             <notes><para>If you have already used <methodname>lock</methodname> to insure the
 187             tracked objects are valid, it is slightly more efficient to use the
 188             <methodname>slot_function</methodname>() method
 189             and call the slot's <code>SlotFunction</code> directly.</para>
 190             </notes>
 191           </overloaded-method>
 192         </method-group>
 193
 194         <method-group name="tracking">
 195           <overloaded-method name="track">
 196             <signature>
 197               <type>slot &amp;</type>
 198               <parameter name="tracked_object">
 199                 <paramtype>const weak_ptr&lt;void&gt; &amp;</paramtype>
 200               </parameter>
 201             </signature>
 202             <signature>
 203               <type>slot &amp;</type>
 204               <parameter name="tracked_signal">
 205                 <paramtype>const <classname>signals2::signal_base</classname> &amp;</paramtype>
 206               </parameter>
 207             </signature>
 208             <signature>
 209               <type>slot &amp;</type>
 210               <parameter name="tracked_slot">
 211                 <paramtype>const <classname>signals2::slot_base</classname> &amp;</paramtype>
 212               </parameter>
 213             </signature>
 214             <effects>
 215               <para>
 216                 Adds object(s) to the slot's tracked object list.  Should any of the
 217                 tracked objects expire, then subsequent attempts to call the slot's <code>operator()</code>
 218                 or <code>lock()</code> methods will throw an <classname>signals2::expired_slot</classname> exception.
 219               </para>
 220               <para>When tracking a signal, a <classname>shared_ptr</classname>
 221                 internal to the signal class is used for tracking.  The signal does not
 222                 need to be owned by an external <code>shared_ptr</code>.
 223               </para>
 224               <para>
 225                 In the case of passing another slot as the argument to <code>track()</code>,
 226                 only the objects currently in the other slot's tracked object list are added
 227                 to the tracked object list of <code>this</code>.  The other slot object itself
 228                 is not tracked.
 229               </para>
 230             </effects>
 231             <returns><para><code>*this</code></para></returns>
 232           </overloaded-method>
 233           <overloaded-method name="track_foreign">
 234             <signature>
 235               <template>
 236                 <template-type-parameter name="ForeignWeakPtr"/>
 237               </template>
 238               <type>slot &amp;</type>
 239               <parameter name="tracked_object">
 240                 <paramtype>const ForeignWeakPtr &amp;</paramtype>
 241               </parameter>
 242               <parameter name="SFINAE">
 243                 <paramtype>typename weak_ptr_traits&lt;ForeignWeakPtr&gt;::shared_type *</paramtype>
 244                 <default>0</default>
 245               </parameter>
 246             </signature>
 247             <signature>
 248               <template>
 249                 <template-type-parameter name="ForeignSharedPtr"/>
 250               </template>
 251               <type>slot &amp;</type>
 252               <parameter name="tracked_object">
 253                 <paramtype>const ForeignSharedPtr &amp;</paramtype>
 254               </parameter>
 255               <parameter name="SFINAE">
 256                 <paramtype>typename shared_ptr_traits&lt;ForeignSharedPtr&gt;::weak_type *</paramtype>
 257                 <default>0</default>
 258               </parameter>
 259             </signature>
 260             <effects>
 261               <para>
 262                 The <code>track_foreign</code>() method behaves similarly to calling the <methodname>track</methodname>() method
 263                 with a <classname>boost::shared_ptr</classname> or <classname>boost::weak_ptr</classname> argument.
 264                 However, <code>track_foreign</code> is more flexible in that it will accept <code>shared_ptr</code>
 265                 or <code>weak_ptr</code> classes from outside of boost (most significantly <code>std::shared_ptr</code>
 266                 or <code>std::weak_ptr</code>).
 267               </para>
 268               <para>
 269                 In order to use a particular <code>shared_ptr</code> class with this function, a specialization of
 270                 <classname>boost::signals2::shared_ptr_traits</classname> must exist for it.
 271                 Also, a specialization of <classname>boost::signals2::weak_ptr_traits</classname> must
 272                 be provided for its corresponding <code>weak_ptr</code> class.
 273                 The <code>shared_ptr_traits</code> specialization must include a <code>weak_type</code>
 274                 member typedef which specifies the
 275                 corresponding <code>weak_ptr</code> type of the <code>shared_ptr</code> class.
 276                 Similarly, the <code>weak_ptr_traits</code> specialization must include a <code>shared_type</code>
 277                 member typedef which specifies the corresponding <code>shared_ptr</code> type of the
 278                 <code>weak_ptr</code> class.  Specializations
 279                 for <code>std::shared_ptr</code> and <code>std::weak_ptr</code> are already provided by the signals2 library.
 280                 For other <code>shared_ptr</code> classes, you must provide the specializations.
 281               </para>
 282               <para>The second argument "SFINAE" may be ignored, it is used to resolve the overload between
 283                 either <code>shared_ptr</code> or <code>weak_ptr</code> objects passed in as the first argument.
 284               </para>
 285             </effects>
 286             <returns><para><code>*this</code></para></returns>
 287           </overloaded-method>
 288         </method-group>
 289
 290         <method-group name="slot function access">
 291           <overloaded-method name="slot_function">
 292             <signature>
 293               <type>slot_function_type &amp;</type>
 294             </signature>
 295             <signature cv="const">
 296               <type>const slot_function_type &amp;</type>
 297             </signature>
 298             <returns><para>A reference to the slot's underlying SlotFunction object.</para></returns>
 299           </overloaded-method>
 300         </method-group>
 301       </class>
 302     </namespace>
 303   </namespace>
 304 </header>