forked from boostorg/smart_ptr
get_shared_ptr renamed to weak_ptr::lock.
[SVN r17307]
This commit is contained in:
Peter Dimov committed
1 parent
34f423f811
commit
851d87a1bb
7 files changed
+69
-73
No files matched your search
+23
-25
@@ -17,12 +17,12 @@
|
||||
<p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's
|
||||
already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>weak_ptr</STRONG>
|
||||
can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
|
||||
the <STRONG>shared_ptr</STRONG> constructor</A> or the function <STRONG><A href="#get_shared_ptr">
|
||||
get_shared_ptr</A></STRONG>. When the last <b>shared_ptr</b> to the
|
||||
object goes away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
|
||||
the <STRONG>shared_ptr</STRONG> constructor</A> or the member function <STRONG><A href="#lock">
|
||||
lock</A></STRONG>. When the last <b>shared_ptr</b> to the object goes
|
||||
away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
|
||||
from the <b>weak_ptr</b> instances that refer to the deleted object will fail:
|
||||
the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>,
|
||||
and <STRONG>get_shared_ptr</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
|
||||
and <STRONG>weak_ptr::lock</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
|
||||
<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements
|
||||
of the C++ Standard Library, and so can be used in standard library containers.
|
||||
Comparison operators are supplied so that <b>weak_ptr</b> works with the
|
||||
@@ -33,7 +33,8 @@
|
||||
<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a
|
||||
very limited subset of operations since accessing its stored pointer is often
|
||||
dangerous in multithreaded programs, and sometimes unsafe even within a single
|
||||
thread (that is, it may invoke undefined behavior.) Consider, for example, this
|
||||
thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b>
|
||||
has a <b>get</b> member function that returns a raw pointer, and consider this
|
||||
innocent piece of code:</P>
|
||||
<pre>shared_ptr<int> p(new int(5));
|
||||
weak_ptr<int> q(p);
|
||||
@@ -55,14 +56,16 @@ weak_ptr<int> q(p);
|
||||
|
||||
// some time later
|
||||
|
||||
if(shared_ptr<int> r = <A href="#get_shared_ptr" >get_shared_ptr</A>(q))
|
||||
if(shared_ptr<int> r = q.<A href="#lock" >lock</A>())
|
||||
{
|
||||
// use *r
|
||||
}
|
||||
</pre>
|
||||
<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>.
|
||||
Even if <code>p.reset()</code> is executed in another thread, the object will
|
||||
stay alive until <STRONG>r</STRONG> goes out of scope (or is reset.)</p>
|
||||
stay alive until <STRONG>r</STRONG> goes out of scope or is reset. By obtaining
|
||||
a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it
|
||||
against destruction.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
@@ -83,11 +86,11 @@ if(shared_ptr<int> r = <A href="#get_shared_ptr" >get_shared_ptr</A>(q))
|
||||
template<class Y> weak_ptr & <A href="#assignment" >operator=</A>(weak_ptr<Y> const & r);
|
||||
template<class Y> weak_ptr & <A href="#assignment" >operator=</A>(shared_ptr<Y> const & r);
|
||||
|
||||
void <A href="#reset" >reset</A>();
|
||||
|
||||
long <A href="#use_count" >use_count</A>() const;
|
||||
bool <A href="#expired" >expired</A>() const;
|
||||
shared_ptr<T> <A href="#lock" >lock</A>() const;
|
||||
|
||||
void <A href="#reset" >reset</A>();
|
||||
void <A href="#swap" >swap</A>(weak_ptr<T> & b);
|
||||
};
|
||||
|
||||
@@ -96,10 +99,6 @@ if(shared_ptr<int> r = <A href="#get_shared_ptr" >get_shared_ptr</A>(q))
|
||||
|
||||
template<class T>
|
||||
void <A href="#free-swap" >swap</A>(weak_ptr<T> & a, weak_ptr<T> & b);
|
||||
|
||||
template<class T>
|
||||
shared_ptr<T> <A href="#get_shared_ptr" >get_shared_ptr</A>(weak_ptr<T> const & r);
|
||||
|
||||
}
|
||||
</pre>
|
||||
<h2><a name="Members">Members</a></h2>
|
||||
@@ -143,11 +142,6 @@ template<class Y> weak_ptr & operator=(shared_ptr<Y> const &
|
||||
<P><B>Notes:</B> The implementation is free to meet the effects (and the implied
|
||||
guarantees) via different means, without creating a temporary.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset();</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="use_count">use_count</a></h3>
|
||||
<pre>long use_count() const;</pre>
|
||||
<blockquote>
|
||||
@@ -165,6 +159,17 @@ template<class Y> weak_ptr & operator=(shared_ptr<Y> const &
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
|
||||
</blockquote>
|
||||
<h3><a name="lock">lock</a></h3>
|
||||
<pre>shared_ptr<T> lock() const;</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Returns:</B> <code>expired()? shared_ptr<T>(): shared_ptr<T>(*this)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset();</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(weak_ptr & b);</pre>
|
||||
<blockquote>
|
||||
@@ -198,13 +203,6 @@ template<class Y> weak_ptr & operator=(shared_ptr<Y> const &
|
||||
<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
|
||||
generic programming.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="get_shared_ptr">get_shared_ptr</a></h3>
|
||||
<pre>template<class T>
|
||||
shared_ptr<T> get_shared_ptr(weak_ptr<T> & const r)</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Returns:</B> <code>r.expired()? shared_ptr<T>(): shared_ptr<T>(r)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h2><a name="FAQ">Frequently Asked Questions</a></h2>
|
||||
<P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its
|
||||
constructor?</P>
|
||||
|
||||
Reference in new issue
Block a user