feedc0de/boost_smart_ptr
1
0
Fork 0
forked from boostorg/smart_ptr
Code Pull Requests Activity

weak_ptr documentation updates; get() declared deprecated.

Browse Source 
[SVN r15111]
This commit is contained in:
Peter Dimov
2002-08-29 15:18:04 +00:00
parent c02fee7013
commit b916445dd8
2 changed files with 28 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
include/boost/weak_ptr.hpp
View File

@ -76,7 +76,7 @@ public:
this_type().swap(*this); this_type().swap(*this);
} }
T * get() const // never throws; unsafe in multithreaded programs! T * get() const // never throws; deprecated, removal pending, don't use
{ {
return pn.use_count() == 0? 0: px; return pn.use_count() == 0? 0: px;
} }
@ -168,6 +168,10 @@ template<class T> shared_ptr<T> make_shared(weak_ptr<T> const & r) // never thro
} }
} }
// Note: there is no get_pointer overload for weak_ptr.
// This is intentional. Even get() will disappear in a
// future release; these accessors are too error-prone.
} // namespace boost } // namespace boost
#ifdef BOOST_MSVC #ifdef BOOST_MSVC

31
weak_ptr.htm
View File

@ -7,10 +7,15 @@
<body bgcolor="#ffffff" text="#000000"> <body bgcolor="#ffffff" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">weak_ptr <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">weak_ptr
class template</h1> class template</h1>
<p>The <b>weak_ptr</b> class template stores a pointer to an object that's already <p>The <b>weak_ptr</b> class template stores a&nbsp;"weak reference"&nbsp;to an
managed by a <b>shared_ptr</b>. When the last <b>shared_ptr</b> to the object object that's already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>
goes away and the object is deleted, all <b>weak_ptr</b> objects have their weak_ptr</STRONG> can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
stored pointers set to 0.</p> the <STRONG>shared_ptr</STRONG> constructor</A> or the function <STRONG><A href="#make_shared">
make_shared</A></STRONG>. When the last <b>shared_ptr</b> to the object
goes away and the object is deleted,&nbsp;the attempt to obtain a <STRONG>shared_ptr</STRONG>
&nbsp;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::use_count_is_zero</STRONG>,
and <STRONG>make_shared</STRONG> will return a default constructed (null) <STRONG>shared_ptr</STRONG>.</p>
<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements <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. 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 Comparison operators are supplied so that <b>weak_ptr</b> works with the
@ -20,8 +25,9 @@
common requirements</a>.</p> common requirements</a>.</p>
<P>Compared to&nbsp;<STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides <P>Compared to&nbsp;<STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides
a very limited subset of operations since accessing its stored pointer is a very limited subset of operations since accessing its stored pointer is
unsafe in multithreaded&nbsp;programs (that is, it may invoke undefined often&nbsp;dangerous in multithreaded&nbsp;programs, and sometimes unsafe even
behavior.) Consider, for example, this innocent piece of code:</P> within a single thread&nbsp;(that is, it may invoke undefined behavior.)
Consider, for example, this innocent piece of code:</P>
<pre> <pre>
shared_ptr&lt;int&gt; p(new int(5)); shared_ptr&lt;int&gt; p(new int(5));
weak_ptr&lt;int&gt; q(p); weak_ptr&lt;int&gt; q(p);
@ -72,7 +78,7 @@ if(shared_ptr&lt;int&gt; r = <a href="#make_shared">make_shared</a>(q))
template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws
void <a href="#reset">reset</a>(); void <a href="#reset">reset</a>();
T * <a href="#get">get</a>() const; // never throws; unsafe in multithreaded code! T * <a href="#get">get</a>() const; // never throws; deprecated, will disappear
long <a href="#use_count">use_count</a>() const; // never throws long <a href="#use_count">use_count</a>() const; // never throws
bool <a href="#expired">expired</a>() const; // never throws bool <a href="#expired">expired</a>() const; // never throws
@ -164,6 +170,11 @@ template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(sh
function returns, the pointed-to object may be destroyed by a different thread, function returns, the pointed-to object may be destroyed by a different thread,
since the <b>weak_ptr</b> doesn't affect its <b>use_count</b>.</P> since the <b>weak_ptr</b> doesn't affect its <b>use_count</b>.</P>
</blockquote> </blockquote>
<P><EM>[<b>get</b> is&nbsp;very error-prone. Even single-threaded code may experience
problems, as the returned pointer may be invalidated at any time, for example,
indirectly by a member function of the pointee.</EM></P>
<P><EM><STRONG>get</STRONG>&nbsp;is deprecated, and it will disappear in a future
release. Do not use it.]</EM></P>
<h3><a name="use_count">use_count</a></h3> <h3><a name="use_count">use_count</a></h3>
<pre>long use_count() const; // never throws</pre> <pre>long use_count() const; // never throws</pre>
<blockquote> <blockquote>
@ -231,8 +242,12 @@ template&lt;typename T, typename U&gt;
<P><B>Returns:</B> <code>r.expired()? shared_ptr&lt;T&gt;(): shared_ptr&lt;T&gt;(r)</code>.</P> <P><B>Returns:</B> <code>r.expired()? shared_ptr&lt;T&gt;(): shared_ptr&lt;T&gt;(r)</code>.</P>
<P><B>Throws:</B> nothing.</P> <P><B>Throws:</B> nothing.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<P><EM>[The current implementation of <STRONG>make_shared</STRONG> can&nbsp;propagate
an exception&nbsp;thrown by the <STRONG>shared_ptr</STRONG> default
constructor, so it doesn't meet the stated requirements</EM><EM>. In a future
release, this default constructor will not throw.]</EM></P>
<hr> <hr>
<p>Revised 12 March 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p> <p>Revised 29 August 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Copyright 2002 Peter Dimov. Permission to copy, use, modify, sell and Copyright 2002 Peter Dimov. Permission to copy, use, modify, sell and
distribute this document is granted provided this copyright notice appears in distribute this document is granted provided this copyright notice appears in