ceph/src/boost/libs/signals2/doc/reference/trackable.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/trackable.hpp">
  12   <namespace name="boost">
  13     <namespace name="signals2">
  14       <class name="trackable">
  15         <purpose>Provided to ease porting for code using the boost::signals::trackable class from
  16           the original Boost.Signals library.</purpose>
  17
  18         <description>
  19           <para>Use of the <code>trackable</code> class is not recommended
  20           for new code.  The <code>trackable</code> class is not thread-safe
  21           since <code>trackable</code> objects disconnect their associated
  22           connections in the <code>trackable</code> destructor.
  23           Since the <code>trackable</code> destructor is not run until
  24           after the destructors of any derived classes have completed,
  25           that leaves open a window where a partially destructed
  26           object can still have active connections.
  27           </para>
  28
  29           <para>
  30           The preferred method of automatic connection management
  31           with Boost.Signals2 is to manage the lifetime of
  32           tracked objects with <code>shared_ptr</code>s and
  33           to use the <methodname>signals2::slot::track</methodname>
  34           method to track their lifetimes.</para>
  35
  36           <para>The <code>trackable</code> class provides automatic
  37           disconnection of signals and slots when objects bound in
  38           slots (via pointer or reference) are destroyed.
  39           <code>trackable</code> class may only be used as a public
  40           base class for some other class; when used as such, that
  41           class may be bound to function objects used as part of
  42           slots. The manner in which a <code>trackable</code> object
  43           tracks the set of signal-slot connections it is a part of is
  44           unspecified.</para>
  45
  46           <para>The actual use of <code>trackable</code> is contingent
  47           on the presence of appropriate
  48           <functionname>visit_each</functionname> overloads for any
  49           type that may contain pointers or references to trackable
  50           objects.</para>
  51
  52         </description>
  53
  54         <constructor>
  55           <effects><para>Sets the list of connected slots to empty.</para></effects>
  56           <throws><para>Will not throw.</para></throws>
  57         </constructor>
  58
  59         <constructor>
  60           <parameter name="other">
  61             <paramtype>const <classname>trackable</classname>&amp;</paramtype>
  62           </parameter>
  63
  64           <effects><para>Sets the list of connected slots to empty.</para></effects>
  65           <throws><para>Will not throw.</para></throws>
  66           <rationale><para>Signal-slot connections can only be created via calls to an explicit connect method, and therefore cannot be created here when trackable objects are copied.</para></rationale>
  67         </constructor>
  68
  69         <destructor>
  70           <effects><para>Disconnects all signal/slot connections that
  71           contain a pointer or reference to this trackable object that
  72           can be found by
  73           <functionname>visit_each</functionname>.</para></effects>
  74         </destructor>
  75
  76         <copy-assignment>
  77           <parameter name="other">
  78             <paramtype>const <classname>trackable</classname>&amp;</paramtype>
  79           </parameter>
  80
  81           <effects><para>Sets the list of connected slots to empty.</para></effects>
  82           <returns><para><code>*this</code></para></returns>
  83           <throws><para>Will not throw.</para></throws>
  84           <rationale><para>Signal-slot connections can only be created via calls to an explicit connect method, and therefore cannot be created here when trackable objects are copied.</para></rationale>
  85         </copy-assignment>
  86       </class>
  87     </namespace>
  88   </namespace>
  89 </header>