ceph/src/boost/libs/smart_ptr/weak_ptr.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3     <head>
   4         <title>weak_ptr</title>
   5         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6     </head>
   7     <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
   8         <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
   9             width="277" align="middle" border="0">weak_ptr class template</h1>
  10         <p><A href="#Introduction">Introduction</A><br>
  11             <A href="#Synopsis">Synopsis</A><br>
  12             <A href="#Members">Members</A><br>
  13             <A href="#functions">Free Functions</A><br>
  14             <A href="#FAQ">Frequently Asked Questions</A>
  15         </p>
  16         <h2><a name="Introduction">Introduction</a></h2>
  17         <p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's
  18             already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>weak_ptr</STRONG>
  19             can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
  20                 the <STRONG>shared_ptr</STRONG> constructor</A> or the member function <STRONG><A href="#lock">
  21                 lock</A></STRONG>. When the last <b>shared_ptr</b> to the object goes
  22             away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
  23             from the <b>weak_ptr</b> instances that refer to the deleted object will fail:
  24             the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>,
  25             and <STRONG>weak_ptr::lock</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
  26         <p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements
  27             of the C++ Standard Library, and so can be used in standard library containers.
  28             Comparison operators are supplied so that <b>weak_ptr</b> works with the
  29             standard library's associative containers.</p>
  30         <P><STRONG>weak_ptr</STRONG> operations never throw&nbsp;exceptions.</P>
  31         <p>The class template is parameterized on <b>T</b>, the type of the object pointed
  32             to.</p>
  33         <P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a
  34             very limited subset of operations since accessing its stored pointer is often
  35             dangerous in multithreaded programs, and sometimes unsafe even within a single
  36             thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b>
  37             has a <b>get</b> member function that returns a raw pointer, and consider this
  38             innocent piece of code:</P>
  39         <pre>shared_ptr&lt;int&gt; p(new int(5));
  40 weak_ptr&lt;int&gt; q(p);
  41
  42 // some time later
  43
  44 if(int * r = q.get())
  45 {
  46     // use *r
  47 }
  48 </pre>
  49         <P>Imagine that after the <STRONG>if</STRONG>, but immediately before <STRONG>r</STRONG>
  50             is used, another thread executes the statement <code>p.reset()</code>. Now <STRONG>r</STRONG>
  51             is a dangling pointer.</P>
  52         <P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
  53             from <STRONG>q</STRONG>:</P>
  54         <pre>shared_ptr&lt;int&gt; p(new int(5));
  55 weak_ptr&lt;int&gt; q(p);
  56
  57 // some time later
  58
  59 if(shared_ptr&lt;int&gt; r = q.<A href="#lock" >lock</A>())
  60 {
  61     // use *r
  62 }
  63 </pre>
  64         <p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>.
  65             Even if <code>p.reset()</code> is executed in another thread, the object will
  66             stay alive until <STRONG>r</STRONG> goes out of scope or is reset. By obtaining
  67             a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it
  68             against destruction.</p>
  69         <h2><a name="Synopsis">Synopsis</a></h2>
  70         <pre>namespace boost {
  71
  72   template&lt;class T&gt; class weak_ptr {
  73
  74     public:
  75       typedef T <A href="#element_type" >element_type</A>;
  76
  77       <A href="#default-constructor" >weak_ptr</A>();
  78
  79       template&lt;class Y&gt; <A href="#constructors" >weak_ptr</A>(shared_ptr&lt;Y&gt; const &amp; r);
  80       <A href="#constructors" >weak_ptr</A>(weak_ptr const &amp; r);
  81       template&lt;class Y&gt; <A href="#constructors" >weak_ptr</A>(weak_ptr&lt;Y&gt; const &amp; r);
  82
  83       <A href="#destructor" >~weak_ptr</A>();
  84
  85       weak_ptr &amp; <A href="#assignment" >operator=</A>(weak_ptr const &amp; r);
  86       template&lt;class Y&gt; weak_ptr &amp; <A href="#assignment" >operator=</A>(weak_ptr&lt;Y&gt; const &amp; r);
  87       template&lt;class Y&gt; weak_ptr &amp; <A href="#assignment" >operator=</A>(shared_ptr&lt;Y&gt; const &amp; r);
  88
  89       long <A href="#use_count" >use_count</A>() const;
  90       bool <A href="#expired" >expired</A>() const;
  91       shared_ptr&lt;T&gt; <A href="#lock" >lock</A>() const;
  92
  93       void <A href="#reset" >reset</A>();
  94       void <A href="#swap" >swap</A>(weak_ptr&lt;T&gt; &amp; b);
  95   };
  96
  97   template&lt;class T, class U&gt;
  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
 100   template&lt;class T&gt;
 101     void <A href="#free-swap" >swap</A>(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b);
 102 }
 103 </pre>
 104         <h2><a name="Members">Members</a></h2>
 105         <h3><a name="element_type">element_type</a></h3>
 106         <pre>typedef T element_type;</pre>
 107         <blockquote>
 108             <p>Provides the type of the template parameter T.</p>
 109         </blockquote>
 110         <h3><a name="constructors">constructors</a></h3>
 111         <pre><a name="default-constructor">weak_ptr();</a></pre>
 112         <blockquote>
 113             <p><b>Effects:</b> Constructs an <EM>empty</EM> <b>weak_ptr</b>.</p>
 114             <p><b>Postconditions:</b> <code>use_count() == 0</code>.</p>
 115             <p><b>Throws:</b> nothing.</p>
 116         </blockquote>
 117         <pre>template&lt;class Y&gt; weak_ptr(shared_ptr&lt;Y&gt; const &amp; r);
 118 weak_ptr(weak_ptr const &amp; r);
 119 template&lt;class Y&gt; weak_ptr(weak_ptr&lt;Y&gt; const &amp; r);</pre>
 120         <blockquote>
 121             <p><b>Effects:</b> If <STRONG>r</STRONG> is <EM>empty</EM>, constructs an <EM>empty</EM>
 122                 <STRONG>weak_ptr</STRONG>; otherwise, constructs a <b>weak_ptr</b> that <EM>shares
 123                 ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the
 124                 pointer stored in <b>r</b>.</p>
 125             <p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p>
 126             <p><b>Throws:</b> nothing.</p>
 127         </blockquote>
 128         <h3><a name="destructor">destructor</a></h3>
 129         <pre>~weak_ptr();</pre>
 130         <BLOCKQUOTE>
 131             <P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object
 132                 its stored pointer points to.</P>
 133             <P><B>Throws:</B> nothing.</P>
 134         </BLOCKQUOTE>
 135         <h3><a name="assignment">assignment</a></h3>
 136         <pre>weak_ptr &amp; operator=(weak_ptr const &amp; r);
 137 template&lt;class Y&gt; weak_ptr &amp; operator=(weak_ptr&lt;Y&gt; const &amp; r);
 138 template&lt;class Y&gt; weak_ptr &amp; operator=(shared_ptr&lt;Y&gt; const &amp; r);</pre>
 139         <BLOCKQUOTE>
 140             <P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
 141             <P><B>Throws:</B> nothing.</P>
 142             <P><B>Notes:</B> The implementation is free to meet the effects (and the implied
 143                 guarantees) via different means, without creating a temporary.</P>
 144         </BLOCKQUOTE>
 145         <h3><a name="use_count">use_count</a></h3>
 146         <pre>long use_count() const;</pre>
 147         <blockquote>
 148             <p><b>Returns:</b> 0 if <STRONG>*this</STRONG> is <EM>empty</EM>; otherwise, the
 149                 number of <b>shared_ptr</b> objects that <EM>share ownership</EM> with <STRONG>*this</STRONG>.</p>
 150             <p><b>Throws:</b> nothing.</p>
 151             <P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only
 152                 for debugging and testing purposes, not for production code.</P>
 153         </blockquote>
 154         <h3><a name="expired">expired</a></h3>
 155         <pre>bool expired() const;</pre>
 156         <blockquote>
 157             <p><b>Returns:</b> <code>use_count() == 0</code>.</p>
 158             <p><b>Throws:</b> nothing.</p>
 159             <P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
 160         </blockquote>
 161         <h3><a name="lock">lock</a></h3>
 162         <pre>shared_ptr&lt;T&gt; lock() const;</pre>
 163         <BLOCKQUOTE>
 164             <P><B>Returns:</B> <code>expired()? shared_ptr&lt;T&gt;(): shared_ptr&lt;T&gt;(*this)</code>.</P>
 165             <P><B>Throws:</B> nothing.</P>
 166         </BLOCKQUOTE>
 167         <h3><a name="reset">reset</a></h3>
 168         <pre>void reset();</pre>
 169         <BLOCKQUOTE>
 170             <P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
 171         </BLOCKQUOTE>
 172         <h3><a name="swap">swap</a></h3>
 173         <pre>void swap(weak_ptr &amp; b);</pre>
 174         <blockquote>
 175             <p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
 176             <p><b>Throws:</b> nothing.</p>
 177         </blockquote>
 178         <h2><a name="functions">Free Functions</a></h2>
 179         <h3><a name="comparison">comparison</a></h3>
 180         <pre>template&lt;class T, class U&gt;
 181   bool operator&lt;(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b);</pre>
 182         <blockquote>
 183             <p><b>Returns:</b> an unspecified value such that</p>
 184             <UL>
 185                 <LI>
 186                     <b>operator&lt;</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
 187                 of the C++ standard;
 188                 <LI>
 189                     under the equivalence relation defined by <STRONG>operator&lt;</STRONG>, <code>!(a
 190                     &lt; b) &amp;&amp; !(b &lt; a)</code>, two <STRONG>weak_ptr</STRONG> instances
 191                     are equivalent if and only if they <EM>share ownership</EM> or are both <EM>empty</EM>.</LI></UL>
 192             <p><b>Throws:</b> nothing.</p>
 193             <P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in
 194                 associative containers.</P>
 195         </blockquote>
 196         <h3><a name="free-swap">swap</a></h3>
 197         <pre>template&lt;class T&gt;
 198   void swap(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b)</pre>
 199         <BLOCKQUOTE>
 200             <P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
 201             <P><B>Throws:</B> nothing.</P>
 202             <P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
 203                 generic programming.</P>
 204         </BLOCKQUOTE>
 205         <h2><a name="FAQ">Frequently Asked Questions</a></h2>
 206         <P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its
 207             constructor?</P>
 208         <P><b>A.</b> No. A <STRONG>weak_ptr</STRONG> can only be created from a <STRONG>shared_ptr</STRONG>,
 209             and at object construction time no <STRONG>shared_ptr</STRONG> to the object
 210             exists yet. Even if you could create a temporary <STRONG>shared_ptr</STRONG> to <STRONG>
 211                 this</STRONG>, it would go out of scope at the end of the constructor, and
 212             all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P>
 213         <P>The solution is to make the constructor private, and supply a factory function
 214             that returns a <STRONG>shared_ptr</STRONG>:<BR>
 215         </P>
 216         <pre>
 217 class X
 218 {
 219 private:
 220
 221     X();
 222
 223 public:
 224
 225     static shared_ptr&lt;X&gt; create()
 226     {
 227         shared_ptr&lt;X&gt; px(new X);
 228         // create weak pointers from px here
 229         return px;
 230     }
 231 };
 232 </pre>
 233         <hr>
 234         <p>$Date$</p>
 235         <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
 236             Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version
 237             1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
 238             copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
 239     </body>
 240 </html>