libs/signals/doc/reference/signal_header.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 <header name="boost/signal.hpp" last-revision="$Date$">
   5   <namespace name="boost">
   6     <namespace name="signals">
   7       <enum name="connect_position">
   8         <enumvalue name="at_front"/>
   9         <enumvalue name="at_back"/>
  10       </enum>
  11     </namespace>
  12     <class name="signalN">
  13       <template>
  14         <template-type-parameter name="R"/>
  15         <template-type-parameter name="T1"/>
  16         <template-type-parameter name="T2"/>
  17         <template-varargs/>
  18         <template-type-parameter name="TN"/>
  19         <template-type-parameter name="Combiner">
  20           <default><classname>last_value</classname>&lt;R&gt;</default>
  21         </template-type-parameter>
  22         <template-type-parameter name="Group">
  23           <default>int</default>
  24         </template-type-parameter>
  25         <template-type-parameter name="GroupCompare">
  26           <default><classname>std::less</classname>&lt;Group&gt;</default>
  27         </template-type-parameter>
  28         <template-type-parameter name="SlotFunction">
  29           <default><classname>functionN</classname>&lt;R, T1, T2, ..., TN&gt;</default>
  30         </template-type-parameter>
  31       </template>
  32       <inherit access="public"><classname>signals::trackable</classname></inherit>
  33       <inherit access="private">
  34         <type><classname>noncopyable</classname></type>
  35         <purpose>Exposition only</purpose>
  36       </inherit>
  37
  38       <purpose>Set of safe multicast callback types.</purpose>
  39
  40       <description>
  41         <para>The class template <classname>signalN</classname> covers
  42          several related classes signal0, signal1, signal2, etc.,
  43          where the number suffix describes the number of function
  44          parameters the signal and its connected slots will
  45          take. Instead of enumerating all classes, a single pattern
  46          <classname>signalN</classname> will be described, where N
  47          represents the number of function parameters.</para>
  48       </description>
  49
  50       <typedef name="result_type">
  51         <type>typename Combiner::result_type</type>
  52       </typedef>
  53       <typedef name="combiner_type"><type>Combiner</type></typedef>
  54       <typedef name="group_type"><type>Group</type></typedef>
  55       <typedef name="group_compare_type"><type>GroupCompare</type></typedef>
  56       <typedef name="slot_function_type"><type>SlotFunction</type></typedef>
  57       <typedef name="slot_type">
  58         <type><classname>slot</classname>&lt;SlotFunction&gt;</type>
  59       </typedef>
  60       <typedef name="slot_result_type">
  61         <type><emphasis>unspecified</emphasis></type>
  62       </typedef>
  63       <typedef name="slot_call_iterator">
  64         <type><emphasis>unspecified</emphasis></type>
  65       </typedef>
  66       <typedef name="argument_type">
  67         <type>T1</type>
  68         <purpose>If N == 1</purpose>
  69       </typedef>
  70       <typedef name="first_argument_type">
  71         <type>T1</type>
  72         <purpose>If N == 2</purpose>
  73       </typedef>
  74       <typedef name="second_argument_type">
  75         <type>T2</type>
  76         <purpose>If N == 2</purpose>
  77       </typedef>
  78       <typedef name="arg1_type"><type>T1</type></typedef>
  79       <typedef name="arg2_type"><type>T2</type></typedef>
  80       <typedef name="..."><type/></typedef>
  81       <typedef name="argN_type"><type>TN</type></typedef>
  82
  83       <static-constant name="arity">
  84         <type>int</type>
  85         <default>N</default>
  86       </static-constant>
  87
  88       <constructor>
  89         <parameter name="combiner">
  90           <paramtype>const combiner_type&amp;</paramtype>
  91           <default>combiner_type()</default>
  92         </parameter>
  93         <parameter name="compare">
  94           <paramtype>const group_compare_type&amp;</paramtype>
  95           <default>group_compare_type()</default>
  96         </parameter>
  97
  98         <effects><simpara>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.</simpara></effects>
  99
 100         <postconditions><simpara><computeroutput>this-&gt;<methodname>empty</methodname>()</computeroutput></simpara></postconditions>
 101       </constructor>
 102
 103       <destructor>
 104         <effects><simpara>Disconnects all slots connected to <computeroutput>*this</computeroutput>.</simpara></effects>
 105       </destructor>
 106
 107       <method-group name="connection management">
 108         <overloaded-method name="connect">
 109           <signature>
 110             <type><classname>signals::connection</classname></type>
 111             <parameter name="slot">
 112               <paramtype>const slot_type&amp;</paramtype>
 113             </parameter>
 114             <parameter name="at">
 115               <paramtype>signals::connect_position</paramtype>
 116               <default>signals::at_back</default>
 117             </parameter>
 118           </signature>
 119
 120           <signature>
 121             <type><classname>signals::connection</classname></type>
 122             <parameter name="group">
 123               <paramtype>const group_type&amp;</paramtype>
 124             </parameter>
 125             <parameter name="slot">
 126               <paramtype>const slot_type&amp;</paramtype>
 127             </parameter>
 128             <parameter name="at">
 129               <paramtype>signals::connect_position</paramtype>
 130               <default>signals::at_back</default>
 131             </parameter>
 132           </signature>
 133
 134           <effects><simpara>Connects the signal this to the incoming
 135           slot. If the slot is inactive, i.e., any of the trackable
 136           objects bound by the slot call have been destroyed, then the
 137           call to connect is a no-op. If the second version of
 138           <computeroutput>connect</computeroutput> is invoked, the
 139           slot is associated with the given group. The <code>at</code>
 140           parameter specifies where the slot should be connected:
 141           <code>at_front</code> indicates that the slot will be
 142           connected at the front of the list or group of slots and
 143           <code>at_back</code> indicates that the slot will be
 144           connected at the back of the list or group of
 145           slots.</simpara></effects>
 146
 147           <returns><simpara>A
 148           <computeroutput><classname>signals::connection</classname></computeroutput>
 149           object that references the newly-created connection between
 150           the signal and the slot; if the slot is inactive, returns a
 151           disconnected connection.</simpara></returns>
 152
 153           <throws><simpara>This routine meets the strong exception guarantee,
 154           where any exception thrown will cause the slot to not be
 155           connected to the signal.</simpara></throws>
 156
 157           <complexity><simpara>Constant time when connecting a slot
 158           without a group name or logarithmic in the number of groups
 159           when connecting to a particular
 160           group.</simpara></complexity>
 161
 162           <notes><simpara>It is unspecified whether connecting a slot while the
 163           signal is calling will result in the slot being called
 164           immediately.</simpara></notes>
 165         </overloaded-method>
 166
 167         <overloaded-method name="disconnect">
 168           <signature>
 169             <type>void</type>
 170             <parameter name="group">
 171               <paramtype>const group_type&amp;</paramtype>
 172             </parameter>
 173           </signature>
 174           <signature>
 175             <template>
 176               <template-type-parameter name="Slot"/>
 177             </template>
 178             <type>void</type>
 179             <parameter name="slot">
 180               <paramtype>const Slot&amp;</paramtype>
 181             </parameter>
 182           </signature>
 183
 184           <effects><simpara>If the parameter is (convertible to) a
 185           group name, any slots in the given group are
 186           disconnected. Otherwise, any slots equal to the given slot
 187           are disconnected.</simpara></effects>
 188
 189           <throws><simpara>Will not throw unless a user destructor or
 190           equality operator <code>==</code> throws. If either throws,
 191           not all slots may be disconnected.</simpara></throws>
 192
 193           <complexity><simpara>If a group is given, O(lg g) + k where
 194           g is the number of groups in the signal and k is the
 195           number of slots in the group. Otherwise, linear in the
 196           number of slots connected to the
 197           signal.</simpara></complexity>
 198         </overloaded-method>
 199
 200         <method name="disconnect_all_slots">
 201           <type>void</type>
 202           <effects><simpara>Disconnects all slots connected to the signal.</simpara></effects>
 203
 204           <postconditions><simpara><computeroutput>this-&gt;<methodname>empty</methodname>()</computeroutput>.</simpara></postconditions>
 205
 206           <throws><simpara>If disconnecting a slot causes an exception to be
 207           thrown, not all slots may be disconnected.</simpara></throws>
 208
 209           <complexity><simpara>Linear in the number of slots known to the
 210           signal.</simpara></complexity>
 211
 212           <notes><simpara>May be called at any time within the lifetime of the
 213           signal, including during calls to the signal's slots.</simpara></notes>
 214         </method>
 215
 216         <method name="empty" cv="const">
 217           <type>bool</type>
 218           <returns><simpara><computeroutput>true</computeroutput> if no slots
 219           are connected to the signal, and
 220           <computeroutput>false</computeroutput> otherwise.</simpara></returns>
 221
 222           <throws><simpara>Will not throw.</simpara></throws>
 223
 224           <complexity><simpara>Linear in the number of slots known to the
 225           signal.</simpara></complexity>
 226
 227           <rationale><simpara>Slots can disconnect at any point in time,
 228           including while those same slots are being invoked. It is
 229           therefore possible that the implementation must search
 230           through a list of disconnected slots to determine if any
 231           slots are still connected.</simpara></rationale>
 232         </method>
 233
 234         <method name="num_slots" cv="const">
 235           <type>std::size_t</type>
 236           <returns><simpara>The number of slots connected to the signal</simpara></returns>
 237
 238           <throws><simpara>Will not throw.</simpara></throws>
 239
 240           <complexity><simpara>Linear in the number of slots known to the
 241           signal.</simpara></complexity>
 242
 243           <rationale><simpara>Slots can disconnect at any point in time,
 244           including while those same slots are being invoked. It is
 245           therefore possible that the implementation must search
 246           through a list of disconnected slots to determine how many
 247           slots are still connected.</simpara></rationale>
 248         </method>
 249       </method-group>
 250
 251       <method-group name="invocation">
 252         <overloaded-method name="operator()">
 253           <signature>
 254             <type>result_type</type>
 255             <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
 256             <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
 257             <parameter><paramtype>...</paramtype></parameter>
 258             <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
 259           </signature>
 260
 261           <signature cv="const">
 262             <type>result_type</type>
 263             <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
 264             <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
 265             <parameter><paramtype>...</paramtype></parameter>
 266             <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
 267           </signature>
 268
 269           <effects><simpara>Invokes the combiner with a
 270           <computeroutput>slot_call_iterator</computeroutput> range
 271           [first, last) corresponding to the sequence of calls to the
 272           slots connected to signal
 273           <computeroutput>*this</computeroutput>. Dereferencing an
 274           iterator in this range causes a slot call with the given set
 275           of parameters <computeroutput>(a1, a2, ...,
 276           aN)</computeroutput>, the result of which is returned from
 277           the iterator dereference operation.</simpara></effects>
 278
 279           <returns><simpara>The result returned by the combiner.</simpara></returns>
 280
 281           <throws><simpara>If an exception is thrown by a slot call, or if the
 282           combiner does not dereference any slot past some given slot,
 283           all slots after that slot in the internal list of connected
 284           slots will not be invoked.</simpara></throws>
 285
 286           <notes><simpara>Only the slots associated with iterators that are
 287           actually dereferenced will be invoked. Multiple dereferences
 288           of the same iterator will not result in multiple slot
 289           invocations, because the return value of the slot will be
 290           cached.</simpara>
 291
 292           <simpara>The <computeroutput>const</computeroutput> version of
 293           the function call operator will invoke the combiner as
 294           <computeroutput>const</computeroutput>, whereas the
 295           non-<computeroutput>const</computeroutput> version will
 296           invoke the combiner as
 297           non-<computeroutput>const</computeroutput>.</simpara>
 298
 299           <simpara>Calling the function call operator may invoke undefined
 300           behavior if no slots are connected to the signal, depending
 301           on the combiner used. The default combiner is well-defined
 302           for zero slots when the return type is void but is undefined
 303           when the return type is any other type (because there is no
 304           way to synthesize a return value).</simpara></notes>
 305         </overloaded-method>
 306       </method-group>
 307
 308       <method-group name="combiner access">
 309         <overloaded-method name="combiner">
 310           <signature>
 311             <type>combiner_type&amp;</type>
 312           </signature>
 313           <signature cv="const">
 314             <type>const combiner_type&amp;</type>
 315           </signature>
 316
 317           <returns><simpara>A reference to the stored combiner.</simpara></returns>
 318           <throws><simpara>Will not throw.</simpara></throws>
 319         </overloaded-method>
 320       </method-group>
 321     </class>
 322
 323     <class name="signal">
 324       <template>
 325         <template-type-parameter name="Signature">
 326           <purpose>Function type R (T1, T2, ..., TN)</purpose>
 327         </template-type-parameter>
 328         <template-type-parameter name="Combiner">
 329           <default><classname>last_value</classname>&lt;R&gt;</default>
 330         </template-type-parameter>
 331         <template-type-parameter name="Group">
 332           <default>int</default>
 333         </template-type-parameter>
 334         <template-type-parameter name="GroupCompare">
 335           <default><classname>std::less</classname>&lt;Group&gt;</default>
 336         </template-type-parameter>
 337         <template-type-parameter name="SlotFunction">
 338           <default><classname>functionN</classname>&lt;Signature&gt;</default>
 339         </template-type-parameter>
 340       </template>
 341
 342       <inherit access="public"><classname>signalN</classname>&lt;R, T1, T2, ..., TN, Combiner, Group, GroupCompare, SlotFunction&gt;</inherit>
 343       <purpose>Safe multicast callback.</purpose>
 344
 345       <description>
 346         <para>Class template <classname>signal</classname> is a thin
 347         wrapper around the numbered class templates <classname
 348         alt="signalN">signal0</classname>, <classname
 349         alt="signalN">signal1</classname>, etc. It accepts a function
 350         type with N arguments instead of N separate arguments, and
 351         derives from the appropriate <classname>signalN</classname>
 352         instantiation.</para>
 353
 354         <para>All functionality of this class template is in its base
 355         class <classname>signalN</classname>.</para>
 356       </description>
 357
 358       <constructor>
 359         <parameter name="combiner">
 360           <paramtype>const combiner_type&amp;</paramtype>
 361           <default>combiner_type()</default>
 362         </parameter>
 363         <parameter name="compare">
 364           <paramtype>const group_compare_type&amp;</paramtype>
 365           <default>group_compare_type()</default>
 366         </parameter>
 367
 368         <effects><simpara>Initializes the base class with the given combiner
 369         and comparison objects.</simpara></effects>
 370       </constructor>
 371     </class>
 372   </namespace>
 373 </header>