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/signal.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 <namespace name="boost"> 15 <namespace name="signals2"> 16 <enum name="connect_position"> 17 <enumvalue name="at_front"/> 18 <enumvalue name="at_back"/> 19 </enum> 20 <class name="signal"> 21 <template> 22 <template-type-parameter name="Signature"> 23 <purpose>Function type R (T1, T2, ..., TN)</purpose> 24 </template-type-parameter> 25 <template-type-parameter name="Combiner"> 26 <default><classname>boost::signals2::optional_last_value</classname><R></default> 27 </template-type-parameter> 28 <template-type-parameter name="Group"> 29 <default>int</default> 30 </template-type-parameter> 31 <template-type-parameter name="GroupCompare"> 32 <default><classname>std::less</classname><Group></default> 33 </template-type-parameter> 34 <template-type-parameter name="SlotFunction"> 35 <default><classname>boost::function</classname><Signature></default> 36 </template-type-parameter> 37 <template-type-parameter name="ExtendedSlotFunction"> 38 <default><classname>boost::function</classname><R (const <classname alt="signals2::connection">connection</classname> &, T1, T2, ..., TN)></default> 39 </template-type-parameter> 40 <template-type-parameter name="Mutex"> 41 <default><classname>boost::signals2::mutex</classname></default> 42 </template-type-parameter> 43 </template> 44 <inherit access="public"> 45 <type><classname>boost::signals2::signal_base</classname></type> 46 </inherit> 47 48 <purpose>Safe multicast callback.</purpose> 49 50 <description> 51 <para> 52 See the <link linkend="signals2.tutorial">tutorial</link> 53 for more information on how to use the signal class. 54 </para> 55 </description> 56 57 <typedef name="signature_type"><type>Signature</type></typedef> 58 <typedef name="result_type"> 59 <type>typename Combiner::result_type</type> 60 </typedef> 61 <typedef name="combiner_type"><type>Combiner</type></typedef> 62 <typedef name="group_type"><type>Group</type></typedef> 63 <typedef name="group_compare_type"><type>GroupCompare</type></typedef> 64 <typedef name="slot_function_type"><type>SlotFunction</type></typedef> 65 <typedef name="slot_type"> 66 <type>typename <classname>signals2::slot</classname><Signature, SlotFunction></type> 67 </typedef> 68 <typedef name="extended_slot_function_type"><type>ExtendedSlotFunction</type></typedef> 69 <typedef name="extended_slot_type"> 70 <type>typename <classname>signals2::slot</classname><R (const <classname alt="signals2::connection">connection</classname> &, T1, ..., TN), ExtendedSlotFunction></type> 71 <description> 72 <para>Slots of the <code>extended_slot_type</code> may be connected to the signal using the 73 <methodname>connect_extended</methodname> methods. The <code>extended_slot_type</code> 74 has an additional <classname>signals2::connection</classname> argument in its signature, 75 which gives slot functions access to their connection to the signal 76 invoking them. 77 </para> 78 </description> 79 </typedef> 80 <typedef name="slot_result_type"> 81 <type>typename SlotFunction::result_type</type> 82 <description> 83 <para> 84 This is the type returned when dereferencing the input iterators passed to the signal's 85 combiner. 86 </para> 87 </description> 88 </typedef> 89 <typedef name="slot_call_iterator"> 90 <type><emphasis>unspecified</emphasis></type> 91 <description> 92 <para> 93 The input iterator type passed to the combiner when the signal is invoked. 94 </para> 95 </description> 96 </typedef> 97 <typedef name="argument_type"> 98 <type>T1</type> 99 <purpose>Exists iff arity == 1</purpose> 100 </typedef> 101 <typedef name="first_argument_type"> 102 <type>T1</type> 103 <purpose>Exists iff arity == 2</purpose> 104 </typedef> 105 <typedef name="second_argument_type"> 106 <type>T2</type> 107 <purpose>Exists iff arity == 2</purpose> 108 </typedef> 109 110 <class name="arg"> 111 <template> 112 <template-nontype-parameter name="n"> 113 <type>unsigned</type> 114 </template-nontype-parameter> 115 </template> 116 <typedef name="type"> 117 <type>Tn</type> 118 <purpose>The type of the <classname alt="signals2::signal">signal</classname>'s (n+1)th argument</purpose> 119 </typedef> 120 </class> 121 122 <static-constant name="arity"> 123 <type>int</type> 124 <default>N</default> 125 <purpose>The number of arguments taken by the signal.</purpose> 126 </static-constant> 127 128 <constructor> 129 <parameter name="combiner"> 130 <paramtype>const combiner_type&</paramtype> 131 <default>combiner_type()</default> 132 </parameter> 133 <parameter name="compare"> 134 <paramtype>const group_compare_type&</paramtype> 135 <default>group_compare_type()</default> 136 </parameter> 137 138 <effects><para>Initializes the signal to contain no slots, copies the given combiner into internal storage, and stores the given group comparison function object to compare groups.</para></effects> 139 140 <postconditions><para><computeroutput>this-><methodname>empty</methodname>()</computeroutput></para></postconditions> 141 </constructor> 142 143 <constructor> 144 <parameter name="other"> 145 <paramtype>signal &&</paramtype> 146 </parameter> 147 <description><para>Move constructor.</para></description> 148 <postconditions><para>The signal <computeroutput>other</computeroutput> 149 is in a "moved-from" state where it may only be destroyed, swapped, or move assigned. 150 Any other operation on a "moved-from" signal is invalid.</para></postconditions> 151 152 <throws><para>Will not throw.</para></throws> 153 </constructor> 154 155 <copy-assignment> 156 <parameter name="rhs"> 157 <paramtype>signal &&</paramtype> 158 </parameter> 159 <description><para>Move assignment.</para></description> 160 <postconditions><para>The signal <computeroutput>rhs</computeroutput> 161 is in a "moved-from" state where it may only be destroyed, swapped, or move assigned. 162 Any other operation on a "moved-from" signal is invalid.</para></postconditions> 163 164 <throws><para>Will not throw.</para></throws> 165 </copy-assignment> 166 167 <method-group name="connection management"> 168 <overloaded-method name="connect"> 169 <signature> 170 <type><classname alt="signals2::connection">connection</classname></type> 171 <parameter name="slot"> 172 <paramtype>const slot_type&</paramtype> 173 </parameter> 174 <parameter name="at"> 175 <paramtype>connect_position</paramtype> 176 <default>at_back</default> 177 </parameter> 178 </signature> 179 180 <signature> 181 <type><classname alt="signals2::connection">connection</classname></type> 182 <parameter name="group"> 183 <paramtype>const group_type&</paramtype> 184 </parameter> 185 <parameter name="slot"> 186 <paramtype>const slot_type&</paramtype> 187 </parameter> 188 <parameter name="at"> 189 <paramtype>connect_position</paramtype> 190 <default>at_back</default> 191 </parameter> 192 </signature> 193 194 <effects><para>Connects the signal this to the incoming 195 slot. If the slot is inactive, i.e., any of the slots's tracked 196 objects have been destroyed, then the 197 call to connect is a no-op. If the second version of 198 <computeroutput>connect</computeroutput> is invoked, the 199 slot is associated with the given group. The <code>at</code> 200 parameter specifies where the slot should be connected: 201 <code>at_front</code> indicates that the slot will be 202 connected at the front of the list or group of slots and 203 <code>at_back</code> indicates that the slot will be 204 connected at the back of the list or group of 205 slots.</para></effects> 206 207 <returns><para>A 208 <computeroutput><classname>signals2::connection</classname></computeroutput> 209 object that references the newly-created connection between 210 the signal and the slot; if the slot is inactive, returns a 211 disconnected connection.</para></returns> 212 213 <throws><para>This routine meets the strong exception guarantee, 214 where any exception thrown will cause the slot to not be 215 connected to the signal.</para></throws> 216 217 <complexity><para>Constant time when connecting a slot 218 without a group name or logarithmic in the number of groups 219 when connecting to a particular 220 group.</para></complexity> 221 222 <notes><para>It is unspecified whether connecting a slot while the 223 signal is calling will result in the slot being called 224 immediately.</para></notes> 225 </overloaded-method> 226 <overloaded-method name="connect_extended"> 227 <signature> 228 <type><classname alt="signals2::connection">connection</classname></type> 229 <parameter name="slot"> 230 <paramtype>const extended_slot_type&</paramtype> 231 </parameter> 232 <parameter name="at"> 233 <paramtype>connect_position</paramtype> 234 <default>at_back</default> 235 </parameter> 236 </signature> 237 238 <signature> 239 <type><classname alt="signals2::connection">connection</classname></type> 240 <parameter name="group"> 241 <paramtype>const group_type&</paramtype> 242 </parameter> 243 <parameter name="slot"> 244 <paramtype>const extended_slot_type&</paramtype> 245 </parameter> 246 <parameter name="at"> 247 <paramtype>connect_position</paramtype> 248 <default>at_back</default> 249 </parameter> 250 </signature> 251 <description> 252 <para> 253 The <code>connect_extended</code> methods work the same as the <methodname>connect</methodname> 254 methods, except they take slots of type <classname>extended_slot_type</classname>. 255 This is useful if a slot needs to access the connection between it and the 256 signal invoking it, for example if it wishes to disconnect or block its own connection. 257 </para> 258 </description> 259 </overloaded-method> 260 261 <overloaded-method name="disconnect"> 262 <signature> 263 <type>void</type> 264 <parameter name="group"> 265 <paramtype>const group_type&</paramtype> 266 </parameter> 267 </signature> 268 <signature> 269 <template> 270 <template-type-parameter name="S"/> 271 </template> 272 <type>void</type> 273 <parameter name="slot_func"> 274 <paramtype>const S&</paramtype> 275 </parameter> 276 </signature> 277 278 <effects><para>If the parameter is (convertible to) a 279 group name, any slots in the given group are 280 disconnected. Otherwise, any slots equal to the 281 given slot function 282 are disconnected. 283 </para> 284 <para>Note, the <code>slot_func</code> 285 argument should not be an actual <classname>signals2::slot</classname> 286 object (which does not even support <code>operator==</code>), but rather 287 the functor you wrapped inside a <classname>signals2::slot</classname> 288 when you initially made the connection. 289 </para></effects> 290 291 <throws><para>Will not throw unless a user destructor or 292 equality operator <code>==</code> throws. If either throws, 293 not all slots may be disconnected.</para></throws> 294 295 <complexity><para>If a group is given, O(lg g) + k where 296 g is the number of groups in the signal and k is the 297 number of slots in the group. Otherwise, linear in the 298 number of slots connected to the 299 signal.</para></complexity> 300 </overloaded-method> 301 302 <method name="disconnect_all_slots"> 303 <type>void</type> 304 <effects><para>Disconnects all slots connected to the signal.</para></effects> 305 306 <postconditions><para><computeroutput>this-><methodname>empty</methodname>()</computeroutput>.</para></postconditions> 307 308 <throws><para>If disconnecting a slot causes an exception to be 309 thrown, not all slots may be disconnected.</para></throws> 310 311 <complexity><para>Linear in the number of slots known to the 312 signal.</para></complexity> 313 314 <notes><para>May be called at any time within the lifetime of the 315 signal, including during calls to the signal's slots.</para></notes> 316 </method> 317 318 <method name="empty" cv="const"> 319 <type>bool</type> 320 <returns><para><computeroutput>true</computeroutput> if no slots 321 are connected to the signal, and 322 <computeroutput>false</computeroutput> otherwise.</para></returns> 323 324 <throws><para>Will not throw.</para></throws> 325 326 <complexity><para>Linear in the number of slots known to the 327 signal.</para></complexity> 328 329 <rationale><para>Slots can disconnect at any point in time, 330 including while those same slots are being invoked. It is 331 therefore possible that the implementation must search 332 through a list of disconnected slots to determine if any 333 slots are still connected.</para></rationale> 334 </method> 335 336 <method name="num_slots" cv="const"> 337 <type>std::size_t</type> 338 <returns><para>The number of slots connected to the signal</para></returns> 339 340 <throws><para>Will not throw.</para></throws> 341 342 <complexity><para>Linear in the number of slots known to the 343 signal.</para></complexity> 344 345 <rationale><para>Slots can disconnect at any point in time, 346 including while those same slots are being invoked. It is 347 therefore possible that the implementation must search 348 through a list of disconnected slots to determine how many 349 slots are still connected.</para></rationale> 350 </method> 351 </method-group> 352 353 <method-group name="invocation"> 354 <overloaded-method name="operator()"> 355 <signature> 356 <type>result_type</type> 357 <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter> 358 <parameter name="a2"><paramtype>arg<1>::type</paramtype></parameter> 359 <parameter><paramtype>...</paramtype></parameter> 360 <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter> 361 </signature> 362 363 <signature cv="const"> 364 <type>result_type</type> 365 <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter> 366 <parameter name="a2"><paramtype>arg<1>::type</paramtype></parameter> 367 <parameter><paramtype>...</paramtype></parameter> 368 <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter> 369 </signature> 370 371 <effects><para>Invokes the combiner with a 372 <computeroutput>slot_call_iterator</computeroutput> range 373 [first, last) corresponding to the sequence of calls to the 374 slots connected to signal 375 <computeroutput>*this</computeroutput>. Dereferencing an 376 iterator in this range causes a slot call with the given set 377 of parameters <computeroutput>(a1, a2, ..., 378 aN)</computeroutput>, the result of which is returned from 379 the iterator dereference operation.</para></effects> 380 381 <returns><para>The result returned by the combiner.</para></returns> 382 383 <throws><para>If an exception is thrown by a slot call, or if the 384 combiner does not dereference any slot past some given slot, 385 all slots after that slot in the internal list of connected 386 slots will not be invoked.</para></throws> 387 388 <notes><para>Only the slots associated with iterators that are 389 actually dereferenced will be invoked. Multiple dereferences 390 of the same iterator will not result in multiple slot 391 invocations, because the return value of the slot will be 392 cached.</para> 393 394 <para>The <computeroutput>const</computeroutput> version of 395 the function call operator will invoke the combiner as 396 <computeroutput>const</computeroutput>, whereas the 397 non-<computeroutput>const</computeroutput> version will 398 invoke the combiner as 399 non-<computeroutput>const</computeroutput>.</para> 400 </notes> 401 </overloaded-method> 402 </method-group> 403 404 <method-group name="combiner access"> 405 <method name="combiner" cv="const"> 406 <type>combiner_type</type> 407 408 <returns><para>A copy of the stored combiner.</para></returns> 409 <throws><para>Will not throw.</para></throws> 410 </method> 411 <method name="set_combiner"> 412 <type>void</type> 413 <parameter name="combiner"><paramtype>const combiner_type&</paramtype></parameter> 414 415 <effects><para>Copies a new combiner into the signal for use with 416 future signal invocations.</para></effects> 417 <throws><para>Will not throw.</para></throws> 418 </method> 419 </method-group> 420 421 <method-group name="modifiers"> 422 <method name="swap"> 423 <type>void</type> 424 <parameter name="other"> 425 <paramtype><classname alt="signals2::signal">signal</classname>&</paramtype> 426 </parameter> 427 <effects><para>Swaps the signal referenced in 428 <computeroutput>this</computeroutput> and 429 <computeroutput>other</computeroutput>.</para></effects> 430 431 <throws><para>Will not throw.</para></throws> 432 </method> 433 </method-group> 434 435 <free-function-group name="specialized algorithms"> 436 <function name="swap"> 437 <template> 438 <template-type-parameter name="Signature"/> 439 <template-type-parameter name="Combiner"/> 440 <template-type-parameter name="Group"/> 441 <template-type-parameter name="GroupCompare"/> 442 <template-type-parameter name="SlotFunction"/> 443 <template-type-parameter name="ExtendedSlotFunction"/> 444 <template-type-parameter name="Mutex"/> 445 </template> 446 <type>void</type> 447 <parameter name="x"> 448 <paramtype><classname alt="signals2::signal">signal</classname><Signature, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex>&</paramtype> 449 </parameter> 450 <parameter name="y"> 451 <paramtype><classname alt="signals2::signal">signal</classname><Signature, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex>&</paramtype> 452 </parameter> 453 454 <effects><para><computeroutput>x.swap(y)</computeroutput></para></effects> 455 <throws><para>Will not throw.</para></throws> 456 </function> 457 </free-function-group> 458 </class> 459 </namespace> 460 </namespace> 461</header> 462