PageRenderTime 23ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 0ms

/jni/boost/libs/smart_ptr/weak_ptr.htm

https://github.com/LeifAndersen/Android-Supertux
HTML | 244 lines | 227 code | 17 blank | 0 comment | 0 complexity | 09e711e1e4b7e8ecd1f6f22e0936097c MD5 | raw file
    

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2. 

  2. <html>
    3. 

  3. 	<head>
    4. 

  4. 		<title>weak_ptr</title>
    5. 

  5. 		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    6. 

  6. 	</head>
    7. 

  7. 	<body text="#000000" bgColor="#ffffff">
    8. 

  8. 		<h1><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle">weak_ptr 
    9. 

  9. 			class template</h1>
    10. 

  10. 		<p><A href="#Introduction">Introduction</A><br>
    11. 

  11. 			<A href="#Synopsis">Synopsis</A><br>
    12. 

  12. 			<A href="#Members">Members</A><br>
    13. 

  13. 			<A href="#functions">Free Functions</A><br>
    14. 

  14. 			<A href="#FAQ">Frequently Asked Questions</A>
    15. 

  15. 		</p>
    16. 

  16. 		<h2><a name="Introduction">Introduction</a></h2>
    17. 

  17. 		<p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's 
    18. 

  18. 			already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>weak_ptr</STRONG>
    19. 

  19. 			can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
    20. 

  20. 				the <STRONG>shared_ptr</STRONG> constructor</A> or the member function <STRONG><A href="#lock">
    21. 

  21. 					lock</A></STRONG>. When the last <b>shared_ptr</b> to the object goes 
    22. 

  22. 			away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
    23. 

  23. 			from the <b>weak_ptr</b> instances that refer to the deleted object will fail: 
    24. 

  24. 			the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>, 
    25. 

  25. 			and <STRONG>weak_ptr::lock</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
    26. 

  26. 		<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements 
    27. 

  27. 			of the C++ Standard Library, and so can be used in standard library containers. 
    28. 

  28. 			Comparison operators are supplied so that <b>weak_ptr</b> works with the 
    29. 

  29. 			standard library's associative containers.</p>
    30. 

  30. 		<P><STRONG>weak_ptr</STRONG> operations never throw&nbsp;exceptions.</P>
    31. 

  31. 		<p>The class template is parameterized on <b>T</b>, the type of the object pointed 
    32. 

  32. 			to.</p>
    33. 

  33. 		<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a 
    34. 

  34. 			very limited subset of operations since accessing its stored pointer is often 
    35. 

  35. 			dangerous in multithreaded programs, and sometimes unsafe even within a single 
    36. 

  36. 			thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b>
    37. 

  37. 			has a <b>get</b> member function that returns a raw pointer, and consider this 
    38. 

  38. 			innocent piece of code:</P>
    39. 

  39. 		<pre>shared_ptr&lt;int&gt; p(new int(5));
    40. 

  40. weak_ptr&lt;int&gt; q(p);
    41. 

  41. 

  42. // some time later
    43. 

  43. 

  44. if(int * r = q.get())
    45. 

  45. {
    46. 

  46.     // use *r
    47. 

  47. }
    48. 

  48. </pre>
    49. 

  49. 		<P>Imagine that after the <STRONG>if</STRONG>, but immediately before <STRONG>r</STRONG>
    50. 

  50. 			is used, another thread executes the statement <code>p.reset()</code>. Now <STRONG>r</STRONG>
    51. 

  51. 			is a dangling pointer.</P>
    52. 

  52. 		<P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
    53. 

  53. 			from <STRONG>q</STRONG>:</P>
    54. 

  54. 		<pre>shared_ptr&lt;int&gt; p(new int(5));
    55. 

  55. weak_ptr&lt;int&gt; q(p);
    56. 

  56. 

  57. // some time later
    58. 

  58. 

  59. if(shared_ptr&lt;int&gt; r = q.<A href="#lock" >lock</A>())
    60. 

  60. {
    61. 

  61.     // use *r
    62. 

  62. }
    63. 

  63. </pre>
    64. 

  64. 		<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>. 
    65. 

  65. 			Even if <code>p.reset()</code> is executed in another thread, the object will 
    66. 

  66. 			stay alive until <STRONG>r</STRONG> goes out of scope or is reset. By obtaining 
    67. 

  67. 			a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it 
    68. 

  68. 			against destruction.</p>
    69. 

  69. 		<h2><a name="Synopsis">Synopsis</a></h2>
    70. 

  70. 		<pre>namespace boost {
    71. 

  71. 

  72.   template&lt;class T&gt; class weak_ptr {
    73. 

  73. 

  74.     public:
    75. 

  75.       typedef T <A href="#element_type" >element_type</A>;
    76. 

  76. 

  77.       <A href="#default-constructor" >weak_ptr</A>();
    78. 

  78. 

  79.       template&lt;class Y&gt; <A href="#constructors" >weak_ptr</A>(shared_ptr&lt;Y&gt; const &amp; r);
    80. 

  80.       <A href="#constructors" >weak_ptr</A>(weak_ptr const &amp; r);
    81. 

  81.       template&lt;class Y&gt; <A href="#constructors" >weak_ptr</A>(weak_ptr&lt;Y&gt; const &amp; r);
    82. 

  82. 

  83.       <A href="#destructor" >~weak_ptr</A>();
    84. 

  84. 

  85.       weak_ptr &amp; <A href="#assignment" >operator=</A>(weak_ptr const &amp; r);
    86. 

  86.       template&lt;class Y&gt; weak_ptr &amp; <A href="#assignment" >operator=</A>(weak_ptr&lt;Y&gt; const &amp; r);
    87. 

  87.       template&lt;class Y&gt; weak_ptr &amp; <A href="#assignment" >operator=</A>(shared_ptr&lt;Y&gt; const &amp; r);
    88. 

  88. 

  89.       long <A href="#use_count" >use_count</A>() const;
    90. 

  90.       bool <A href="#expired" >expired</A>() const;
    91. 

  91.       shared_ptr&lt;T&gt; <A href="#lock" >lock</A>() const;
    92. 

  92. 

  93.       void <A href="#reset" >reset</A>();
    94. 

  94.       void <A href="#swap" >swap</A>(weak_ptr&lt;T&gt; &amp; b);
    95. 

  95.   };
    96. 

  96. 

  97.   template&lt;class T, class U&gt;
    98. 

  98.     bool <A href="#comparison" >operator&lt;</A>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b);
    99. 

  99. 

  100.   template&lt;class T&gt;
    101. 

  101.     void <A href="#free-swap" >swap</A>(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b);
    102. 

  102. }
    103. 

  103. </pre>
    104. 

  104. 		<h2><a name="Members">Members</a></h2>
    105. 

  105. 		<h3><a name="element_type">element_type</a></h3>
    106. 

  106. 		<pre>typedef T element_type;</pre>
    107. 

  107. 		<blockquote>
    108. 

  108. 			<p>Provides the type of the template parameter T.</p>
    109. 

  109. 		</blockquote>
    110. 

  110. 		<h3><a name="default-constructor">constructors</a></h3>
    111. 

  111. 		<pre>weak_ptr();</pre>
    112. 

  112. 		<blockquote>
    113. 

  113. 			<p><b>Effects:</b> Constructs an <EM>empty</EM> <b>weak_ptr</b>.</p>
    114. 

  114. 			<p><b>Postconditions:</b> <code>use_count() == 0</code>.</p>
    115. 

  115. 			<p><b>Throws:</b> nothing.</p>
    116. 

  116. 		</blockquote><a name="constructors"></a>
    117. 

  117. 		<pre>template&lt;class Y&gt; weak_ptr</A>(shared_ptr&lt;Y&gt; const &amp; r);
    118. 

  118. weak_ptr(weak_ptr const &amp; r);
    119. 

  119. template&lt;class Y&gt; weak_ptr(weak_ptr&lt;Y&gt; const &amp; r);</pre>
    120. 

  120. 		<blockquote>
    121. 

  121. 			<p><b>Effects:</b> If <STRONG>r</STRONG> is <EM>empty</EM>, constructs an <EM>empty</EM>
    122. 

  122. 				<STRONG>weak_ptr</STRONG>; otherwise, constructs a <b>weak_ptr</b> that <EM>shares 
    123. 

  123. 					ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the 
    124. 

  124. 				pointer stored in <b>r</b>.</p>
    125. 

  125. 			<p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p>
    126. 

  126. 			<p><b>Throws:</b> nothing.</p>
    127. 

  127. 		</blockquote>
    128. 

  128. 		<h3><a name="destructor">destructor</a></h3>
    129. 

  129. 		<pre>~weak_ptr();</pre>
    130. 

  130. 		<BLOCKQUOTE>
    131. 

  131. 			<P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object 
    132. 

  132. 				its stored pointer points to.</P>
    133. 

  133. 			<P><B>Throws:</B> nothing.</P>
    134. 

  134. 		</BLOCKQUOTE>
    135. 

  135. 		<h3><a name="assignment">assignment</a></h3>
    136. 

  136. 		<pre>weak_ptr &amp; operator=(weak_ptr const &amp; r);
    137. 

  137. template&lt;class Y&gt; weak_ptr &amp; operator=(weak_ptr&lt;Y&gt; const &amp; r);
    138. 

  138. template&lt;class Y&gt; weak_ptr &amp; operator=(shared_ptr&lt;Y&gt; const &amp; r);</pre>
    139. 

  139. 		<BLOCKQUOTE>
    140. 

  140. 			<P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
    141. 

  141. 			<P><B>Throws:</B> nothing.</P>
    142. 

  142. 			<P><B>Notes:</B> The implementation is free to meet the effects (and the implied 
    143. 

  143. 				guarantees) via different means, without creating a temporary.</P>
    144. 

  144. 		</BLOCKQUOTE>
    145. 

  145. 		<h3><a name="use_count">use_count</a></h3>
    146. 

  146. 		<pre>long use_count() const;</pre>
    147. 

  147. 		<blockquote>
    148. 

  148. 			<p><b>Returns:</b> 0 if <STRONG>*this</STRONG> is <EM>empty</EM>; otherwise, the 
    149. 

  149. 				number of <b>shared_ptr</b> objects that <EM>share ownership</EM> with <STRONG>*this</STRONG>.</p>
    150. 

  150. 			<p><b>Throws:</b> nothing.</p>
    151. 

  151. 			<P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only 
    152. 

  152. 				for debugging and testing purposes, not for production code.</P>
    153. 

  153. 		</blockquote>
    154. 

  154. 		<h3><a name="expired">expired</a></h3>
    155. 

  155. 		<pre>bool expired() const;</pre>
    156. 

  156. 		<blockquote>
    157. 

  157. 			<p><b>Returns:</b> <code>use_count() == 0</code>.</p>
    158. 

  158. 			<p><b>Throws:</b> nothing.</p>
    159. 

  159. 			<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
    160. 

  160. 		</blockquote>
    161. 

  161. 		<h3><a name="lock">lock</a></h3>
    162. 

  162. 		<pre>shared_ptr&lt;T&gt; lock() const;</pre>
    163. 

  163. 		<BLOCKQUOTE>
    164. 

  164. 			<P><B>Returns:</B> <code>expired()? shared_ptr&lt;T&gt;(): shared_ptr&lt;T&gt;(*this)</code>.</P>
    165. 

  165. 			<P><B>Throws:</B> nothing.</P>
    166. 

  166. 		</BLOCKQUOTE>
    167. 

  167. 		<h3><a name="reset">reset</a></h3>
    168. 

  168. 		<pre>void reset();</pre>
    169. 

  169. 		<BLOCKQUOTE>
    170. 

  170. 			<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
    171. 

  171. 		</BLOCKQUOTE>
    172. 

  172. 		<h3><a name="swap">swap</a></h3>
    173. 

  173. 		<pre>void swap(weak_ptr &amp; b);</pre>
    174. 

  174. 		<blockquote>
    175. 

  175. 			<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
    176. 

  176. 			<p><b>Throws:</b> nothing.</p>
    177. 

  177. 		</blockquote>
    178. 

  178. 		<h2><a name="functions">Free Functions</a></h2>
    179. 

  179. 		<h3><a name="comparison">comparison</a></h3>
    180. 

  180. 		<pre>template&lt;class T, class U&gt;
    181. 

  181.   bool operator&lt;(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b);</pre>
    182. 

  182. 		<blockquote>
    183. 

  183. 			<p><b>Returns:</b> an unspecified value such that</p>
    184. 

  184. 			<UL>
    185. 

  185. 				<LI>
    186. 

  186. 					<b>operator&lt;</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
    187. 

  187. 				of the C++ standard;
    188. 

  188. 				<LI>
    189. 

  189. 					under the equivalence relation defined by <STRONG>operator&lt;</STRONG>, <code>!(a 
    190. 

  190. 						&lt; b) &amp;&amp; !(b &lt; a)</code>, two <STRONG>weak_ptr</STRONG> instances 
    191. 

  191. 					are equivalent if and only if they <EM>share ownership</EM> or are both <EM>empty</EM>.</LI></UL>
    192. 

  192. 			<p><b>Throws:</b> nothing.</p>
    193. 

  193. 			<P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in 
    194. 

  194. 				associative containers.</P>
    195. 

  195. 		</blockquote>
    196. 

  196. 		<h3><a name="free-swap">swap</a></h3>
    197. 

  197. 		<pre>template&lt;class T&gt;
    198. 

  198.   void swap(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b)</pre>
    199. 

  199. 		<BLOCKQUOTE>
    200. 

  200. 			<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
    201. 

  201. 			<P><B>Throws:</B> nothing.</P>
    202. 

  202. 			<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to 
    203. 

  203. 				generic programming.</P>
    204. 

  204. 		</BLOCKQUOTE>
    205. 

  205. 		<h2><a name="FAQ">Frequently Asked Questions</a></h2>
    206. 

  206. 		<P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its 
    207. 

  207. 			constructor?</P>
    208. 

  208. 		<P><b>A.</b> No. A <STRONG>weak_ptr</STRONG> can only be created from a <STRONG>shared_ptr</STRONG>, 
    209. 

  209. 			and at object construction time no <STRONG>shared_ptr</STRONG> to the object 
    210. 

  210. 			exists yet. Even if you could create a temporary <STRONG>shared_ptr</STRONG> to <STRONG>
    211. 

  211. 				this</STRONG>, it would go out of scope at the end of the constructor, and 
    212. 

  212. 			all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P>
    213. 

  213. 		<P>The solution is to make the constructor private, and supply a factory function 
    214. 

  214. 			that returns a <STRONG>shared_ptr</STRONG>:<BR>
    215. 

  215. 		</P>
    216. 

  216. 		<pre>
    217. 

  217. class X
    218. 

  218. {
    219. 

  219. private:
    220. 

  220. 

  221.     X();
    222. 

  222. 

  223. public:
    224. 

  224. 

  225.     static shared_ptr&lt;X&gt; create()
    226. 

  226.     {
    227. 

  227.         shared_ptr&lt;X&gt; px(new X);
    228. 

  228.         // create weak pointers from px here
    229. 

  229.         return px;
    230. 

  230.     }
    231. 

  231. };
    232. 

  232. </pre>
    233. 

  233. 		<p><br>
    234. 

  234. 		</p>
    235. 

  235. 		<hr>
    236. 

  236. 		<p>$Date: 2005/07/18 20:33:59 $</p>
    237. 

  237. 		<p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. 
    238. 

  238. 				Copyright 2002-2005 Peter Dimov. Permission to copy, use, modify, sell and 
    239. 

  239. 				distribute this document is granted provided this copyright notice appears in 
    240. 

  240. 				all copies. This document is provided "as is" without express or implied 
    241. 

  241. 				warranty, and with no claim as to its suitability for any purpose.</small></p>
    242. 

  242. 		</A>
    243. 

  243. 	</body>
    244. 

  244. </html>
    245. 

  245.