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/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>&</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>&</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>