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<!-- 5Copyright Douglas Gregor 2001-2004 6Copyright Frank Mori Hess 2007-2009 7 8Distributed under the Boost Software License, Version 1.0. (See accompanying 9file 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><R (T1, T2, ..., TN)></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 &</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<OtherSignature, OtherSlotFunction> &</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 &</paramtype> 138 </parameter> 139 <parameter name="a1"> 140 <paramtype>const Arg1 &</paramtype> 141 </parameter> 142 <parameter name="a2"> 143 <paramtype>const Arg2 &</paramtype> 144 </parameter> 145 <parameter> 146 <paramtype>...</paramtype> 147 </parameter> 148 <parameter name="aN"> 149 <paramtype>const ArgN &</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<0>::type</paramtype></parameter> 164 <parameter name="a2"><paramtype>arg<1>::_type</paramtype></parameter> 165 <parameter><paramtype>...</paramtype></parameter> 166 <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter> 167 </signature> 168 169 <signature cv="const"> 170 <type>result_type</type> 171 <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter> 172 <parameter name="a2"><paramtype>arg<1>::_type</paramtype></parameter> 173 <parameter><paramtype>...</paramtype></parameter> 174 <parameter name="aN"><paramtype>arg<N-1>::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 &</type> 198 <parameter name="tracked_object"> 199 <paramtype>const weak_ptr<void> &</paramtype> 200 </parameter> 201 </signature> 202 <signature> 203 <type>slot &</type> 204 <parameter name="tracked_signal"> 205 <paramtype>const <classname>signals2::signal_base</classname> &</paramtype> 206 </parameter> 207 </signature> 208 <signature> 209 <type>slot &</type> 210 <parameter name="tracked_slot"> 211 <paramtype>const <classname>signals2::slot_base</classname> &</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 &</type> 239 <parameter name="tracked_object"> 240 <paramtype>const ForeignWeakPtr &</paramtype> 241 </parameter> 242 <parameter name="SFINAE"> 243 <paramtype>typename weak_ptr_traits<ForeignWeakPtr>::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 &</type> 252 <parameter name="tracked_object"> 253 <paramtype>const ForeignSharedPtr &</paramtype> 254 </parameter> 255 <parameter name="SFINAE"> 256 <paramtype>typename shared_ptr_traits<ForeignSharedPtr>::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 &</type> 294 </signature> 295 <signature cv="const"> 296 <type>const slot_function_type &</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> 305