boostorg/smart_ptr
1
0
Fork 1
mirror of https://github.com/boostorg/smart_ptr.git synced 2025-07-30 20:57:21 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation fixes, make_shared -> get_shared_ptr.

Browse Source 
[SVN r17230]
This commit is contained in:
Peter Dimov
2003-02-05 12:56:48 +00:00
parent 98fa979aef
commit 86e9a322ba
10 changed files with 85 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
enable_shared_from_this.html
View File

@ -71,9 +71,9 @@ public:
<p> <p>
<b>Requires:</b> <STRONG>enable_shared_from_this&lt;T&gt;</STRONG> must be an <b>Requires:</b> <STRONG>enable_shared_from_this&lt;T&gt;</STRONG> must be an
accessible base class of <b>T</b>. <STRONG>*this</STRONG> must be a subobject accessible base class of <b>T</b>. <STRONG>*this</STRONG> must be a subobject
of an instance <STRONG>t</STRONG> of type <STRONG>T</STRONG>. There must have of an instance <STRONG>t</STRONG> of type <STRONG>T</STRONG> . There must exist
existed at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> pointing at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> that <EM>owns</EM>
to <STRONG>t</STRONG>. <STRONG>t</STRONG>.
</p> </p>
<p> <p>
<b>Returns:</b> A <b>shared_ptr&lt;T&gt;</b> instance <b>r</b> that shares <b>Returns:</b> A <b>shared_ptr&lt;T&gt;</b> instance <b>r</b> that shares
@ -85,9 +85,9 @@ public:
</blockquote> </blockquote>
<p> <p>
<br> <br>
<small>Copyright <20> 2002 by Peter Dimov. Permission to copy, use, modify, sell and <small>Copyright <20> 2002, 2003 by Peter Dimov. Permission to copy, use, modify, sell
distribute this document is granted provided this copyright notice appears in and distribute this document is granted provided this copyright notice appears
all copies. This document is provided "as is" without express or implied in all copies. This document is provided "as is" without express or implied
warranty, and with no claim as to its suitability for any purpose.</small></p> warranty, and with no claim as to its suitability for any purpose.</small></p>
</body> </body>
</html> </html>

14
include/boost/weak_ptr.hpp
View File

@ -24,7 +24,7 @@
namespace boost namespace boost
{ {
template<class T> shared_ptr<T> make_shared(weak_ptr<T> const & r); // never throws template<class T> shared_ptr<T> get_shared_ptr(weak_ptr<T> const & r); // never throws
template<class T> class weak_ptr template<class T> class weak_ptr
{ {
@ -64,7 +64,7 @@ public:
template<class Y> template<class Y>
weak_ptr(weak_ptr<Y> const & r): pn(r.pn) // never throws weak_ptr(weak_ptr<Y> const & r): pn(r.pn) // never throws
{ {
px = boost::make_shared(r).get(); px = boost::get_shared_ptr(r).get();
} }
template<class Y> template<class Y>
@ -77,7 +77,7 @@ public:
template<class Y> template<class Y>
weak_ptr & operator=(weak_ptr<Y> const & r) // never throws weak_ptr & operator=(weak_ptr<Y> const & r) // never throws
{ {
px = boost::make_shared(r).get(); px = boost::get_shared_ptr(r).get();
pn = r.pn; pn = r.pn;
return *this; return *this;
} }
@ -151,7 +151,7 @@ template<class T> void swap(weak_ptr<T> & a, weak_ptr<T> & b)
a.swap(b); a.swap(b);
} }
template<class T> shared_ptr<T> make_shared(weak_ptr<T> const & r) // never throws template<class T> shared_ptr<T> get_shared_ptr(weak_ptr<T> const & r) // never throws
{ {
#if defined(BOOST_HAS_THREADS) #if defined(BOOST_HAS_THREADS)
@ -180,6 +180,12 @@ template<class T> shared_ptr<T> make_shared(weak_ptr<T> const & r) // never thro
#endif #endif
} }
// deprecated, provided for backward compatibility
template<class T> shared_ptr<T> make_shared(weak_ptr<T> const & r)
{
return boost::get_shared_ptr(r);
}
} // namespace boost } // namespace boost
#ifdef BOOST_MSVC #ifdef BOOST_MSVC

8
index.htm
View File

@ -33,6 +33,10 @@
Header <a href="../../boost/shared_array.hpp">shared_array.hpp</a>.</li> Header <a href="../../boost/shared_array.hpp">shared_array.hpp</a>.</li>
<li> <li>
Header <a href="../../boost/weak_ptr.hpp">weak_ptr.hpp</a>.</li> Header <a href="../../boost/weak_ptr.hpp">weak_ptr.hpp</a>.</li>
<li>
Header <a href="../../boost/enable_shared_from_this.hpp">enable_shared_from_this.hpp</a>.</li>
<li>
Header <a href="../../boost/intrusive_ptr.hpp">intrusive_ptr.hpp</a>.</li>
<li> <li>
Test program <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>.</li> Test program <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>.</li>
<li> <li>
@ -41,7 +45,7 @@
by <a href="../../people/peter_dimov.htm">Peter Dimov</a> and <a href="../../people/darin_adler.htm"> by <a href="../../people/peter_dimov.htm">Peter Dimov</a> and <a href="../../people/darin_adler.htm">
Darin Adler</a>.</li> Darin Adler</a>.</li>
</ul> </ul>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan --> <hr>
1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="14885" --> .</p> <p>$Date$</p>
</body> </body>
</html> </html>

14
intrusive_ptr.html
View File

@ -19,9 +19,9 @@
the reference count by using an unqualified call to the function <STRONG>intrusive_ptr_add_ref</STRONG>, the reference count by using an unqualified call to the function <STRONG>intrusive_ptr_add_ref</STRONG>,
passing it the pointer as an argument. Similarly, when an <STRONG>intrusive_ptr</STRONG> passing it the pointer as an argument. Similarly, when an <STRONG>intrusive_ptr</STRONG>
is destroyed, it calls <STRONG>intrusive_ptr_release</STRONG>; this function is is destroyed, it calls <STRONG>intrusive_ptr_release</STRONG>; this function is
responsible for destroying the object when its reference count drops to responsible for destroying the object when its reference count drops to zero.
zero. The user is expected to provide suitable definitions of these two The user is expected to provide suitable definitions of these two functions. On
functions. On compilers that support argument-dependent lookup, <STRONG>intrusive_ptr_add_ref</STRONG> compilers that support argument-dependent lookup, <STRONG>intrusive_ptr_add_ref</STRONG>
and <STRONG>intrusive_ptr_release</STRONG> should be defined in the namespace and <STRONG>intrusive_ptr_release</STRONG> should be defined in the namespace
that corresponds to their parameter; otherwise, the definitions need to go in that corresponds to their parameter; otherwise, the definitions need to go in
namespace <STRONG>boost</STRONG>.</p> namespace <STRONG>boost</STRONG>.</p>
@ -39,8 +39,8 @@
<LI> <LI>
<STRONG>intrusive_ptr&lt;T&gt;</STRONG> can be constructed from an arbitrary <STRONG>intrusive_ptr&lt;T&gt;</STRONG> can be constructed from an arbitrary
raw pointer of type <STRONG>T *</STRONG>.</LI></UL> raw pointer of type <STRONG>T *</STRONG>.</LI></UL>
<P>As a general rule, if it isn't obvious whether <STRONG>intrusive_ptr</STRONG> <P>As a general rule, if it isn't obvious whether <STRONG>intrusive_ptr</STRONG> better
better fits your needs than <STRONG>shared_ptr</STRONG>, try a <STRONG>shared_ptr</STRONG>-based fits your needs than <STRONG>shared_ptr</STRONG>, try a <STRONG>shared_ptr</STRONG>-based
design first.</P> design first.</P>
<h2><a name="Synopsis">Synopsis</a></h2> <h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost { <pre>namespace boost {
@ -268,9 +268,9 @@ intrusive_ptr &amp; operator=(T * r);</pre>
<p> <p>
$Date$</p> $Date$</p>
<p> <p>
Copyright <20> 2003 Peter Dimov. Permission to copy, use, modify, sell and <small>Copyright <20> 2003 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
all copies. This document is provided "as is" without express or implied all copies. This document is provided "as is" without express or implied
warranty, and with no claim as to its suitability for any purpose.</p> warranty, and with no claim as to its suitability for any purpose.</small></p>
</body> </body>
</html> </html>

57
shared_ptr.htm
View File

@ -8,7 +8,6 @@
<h1><IMG height="86" alt="c++boost.gif (8819 bytes)" src="../../c++boost.gif" width="277" align="middle">shared_ptr <h1><IMG height="86" alt="c++boost.gif (8819 bytes)" src="../../c++boost.gif" width="277" align="middle">shared_ptr
class template</h1> class template</h1>
<p><A href="#Introduction">Introduction</A><br> <p><A href="#Introduction">Introduction</A><br>
<A href="#Motivation">Motivation</A><br>
<A href="#BestPractices">Best Practices</A><br> <A href="#BestPractices">Best Practices</A><br>
<A href="#Synopsis">Synopsis</A><br> <A href="#Synopsis">Synopsis</A><br>
<A href="#Members">Members</A><br> <A href="#Members">Members</A><br>
@ -47,8 +46,6 @@
to <STRONG>shared_ptr&lt;T const&gt;</STRONG>, to <STRONG>shared_ptr&lt;U&gt;</STRONG> to <STRONG>shared_ptr&lt;T const&gt;</STRONG>, to <STRONG>shared_ptr&lt;U&gt;</STRONG>
where <STRONG>U</STRONG> is an accessible base of <STRONG>T</STRONG>, and to <STRONG> where <STRONG>U</STRONG> is an accessible base of <STRONG>T</STRONG>, and to <STRONG>
shared_ptr&lt;void&gt;</STRONG>.</P> shared_ptr&lt;void&gt;</STRONG>.</P>
<h2><a name="Motivation">Motivation</a></h2>
<p>[...]</p>
<h2><a name="BestPractices">Best Practices</a></h2> <h2><a name="BestPractices">Best Practices</a></h2>
<P>A simple guideline that nearly eliminates the possibility of memory leaks is: <P>A simple guideline that nearly eliminates the possibility of memory leaks is:
always use a named smart pointer variable to hold the result of <STRONG>new. </STRONG> always use a named smart pointer variable to hold the result of <STRONG>new. </STRONG>
@ -83,8 +80,8 @@ void bad()
evaluated in unspecified order, it is possible for <STRONG>new int(2)</STRONG> to evaluated in unspecified order, it is possible for <STRONG>new int(2)</STRONG> to
be evaluated first, <STRONG>g()</STRONG> second, and we may never get to the <STRONG> be evaluated first, <STRONG>g()</STRONG> second, and we may never get to the <STRONG>
shared_ptr </STRONG>constructor if <STRONG>g</STRONG> throws an exception. shared_ptr </STRONG>constructor if <STRONG>g</STRONG> throws an exception.
See <A href="http://www.gotw.ca/gotw/056.htm">Herb Sutter's treatment</A> of See <A href="http://www.gotw.ca/gotw/056.htm">Herb Sutter's treatment</A> (also <A href="http://www.cuj.com/reference/articles/2002/0212/0212_sutter.htm">
the issue for more information.</P> here</A>) of the issue for more information.</P>
<h2><a name="Synopsis">Synopsis</a></h2> <h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost { <pre>namespace boost {
@ -150,6 +147,8 @@ void bad()
template&lt;class E, class T, class Y&gt; template&lt;class E, class T, class Y&gt;
std::basic_ostream&lt;E, T&gt; &amp; <A href="#insertion-operator" >operator&lt;&lt;</A> (std::basic_ostream&lt;E, T&gt; &amp; os, shared_ptr&lt;Y&gt; const &amp; p); std::basic_ostream&lt;E, T&gt; &amp; <A href="#insertion-operator" >operator&lt;&lt;</A> (std::basic_ostream&lt;E, T&gt; &amp; os, shared_ptr&lt;Y&gt; const &amp; p);
template&lt;class D, class T&gt;
D * <A href="#get_deleter">get_deleter</A>(shared_ptr&lt;T&gt; const &amp; p);
}</pre> }</pre>
<P><EM>[It might be convenient to relax the requirements on <STRONG>shared_ptr</STRONG>'s <P><EM>[It might be convenient to relax the requirements on <STRONG>shared_ptr</STRONG>'s
signature, allowing an additional, defaulted, template parameter; the parameter signature, allowing an additional, defaulted, template parameter; the parameter
@ -193,7 +192,7 @@ void bad()
must be a complete type. The expression <code>delete p</code> must be must be a complete type. The expression <code>delete p</code> must be
well-formed, must not invoke undefined behavior, and must not throw exceptions. well-formed, must not invoke undefined behavior, and must not throw exceptions.
</p> </p>
<p><b>Effects:</b> Constructs a <b>shared_ptr</b>, storing a copy of <b>p</b>.</p> <p><b>Effects:</b> Constructs a <b>shared_ptr</b> that <EM>owns</EM> the pointer <b>p</b>.</p>
<p><b>Postconditions:</b> <code>use_count() == 1 &amp;&amp; get() == p</code>.</p> <p><b>Postconditions:</b> <code>use_count() == 1 &amp;&amp; get() == p</code>.</p>
<p><b>Throws:</b> <b>std::bad_alloc</b> or an implementation-defined exception when <p><b>Throws:</b> <b>std::bad_alloc</b> or an implementation-defined exception when
a resource other than memory could not be obtained.</p> a resource other than memory could not be obtained.</p>
@ -220,7 +219,8 @@ void bad()
of <b>D</b> must not throw. The expression <code>d(p)</code> must be of <b>D</b> must not throw. The expression <code>d(p)</code> must be
well-formed, must not invoke undefined behavior, and must not throw exceptions. well-formed, must not invoke undefined behavior, and must not throw exceptions.
</p> </p>
<p><b>Effects:</b> Constructs a <b>shared_ptr</b>, storing a copy of <b>p</b> and <b>d</b>.</p> <p><b>Effects:</b> Constructs a <b>shared_ptr</b> that <EM>owns</EM> the pointer <STRONG>
p</STRONG> and the deleter <b>d</b>.</p>
<p><b>Postconditions:</b> <code>use_count() == 1 &amp;&amp; get() == p</code>.</p> <p><b>Postconditions:</b> <code>use_count() == 1 &amp;&amp; get() == p</code>.</p>
<p><b>Throws:</b> <b>std::bad_alloc</b> or an implementation-defined exception when <p><b>Throws:</b> <b>std::bad_alloc</b> or an implementation-defined exception when
a resource other than memory could not be obtained.</p> a resource other than memory could not be obtained.</p>
@ -288,9 +288,19 @@ template&lt;class Y&gt; shared_ptr(shared_ptr&lt;Y&gt; const &amp; r); // never
<h3><a name="destructor">destructor</a></h3> <h3><a name="destructor">destructor</a></h3>
<pre>~shared_ptr(); // never throws</pre> <pre>~shared_ptr(); // never throws</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<P><B>Effects:</B> If <STRONG>*this</STRONG> is the sole owner (<code>use_count() == 1</code>), <P><B>Effects:</B></P>
destroys the object pointed to by the stored pointer as specified at <UL>
construction time.</P> <LI>
If <STRONG>*this</STRONG> is <EM>empty</EM>, or <EM>shares ownership</EM> with
another <STRONG>shared_ptr</STRONG> instance (<code>use_count() &gt; 1</code>),
there are no side effects.
<LI>
Otherwise, if <STRONG>*this</STRONG> <EM>owns</EM> a pointer <STRONG>p</STRONG>
and a deleter <STRONG>d</STRONG>, <code>d(p)</code>
is called.
<LI>
Otherwise, <STRONG>*this</STRONG> <EM>owns</EM> a pointer <STRONG>p</STRONG>,
and <code>delete p</code> is called.</LI></UL>
<P><B>Throws:</B> nothing.</P> <P><B>Throws:</B> nothing.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<H3><a name="assignment">assignment</a></H3> <H3><a name="assignment">assignment</a></H3>
@ -381,7 +391,7 @@ q = p;
</blockquote> </blockquote>
<P><EM>[The conversion to bool is not merely syntactic sugar. It allows <STRONG>shared_ptr</STRONG>s <P><EM>[The conversion to bool is not merely syntactic sugar. It allows <STRONG>shared_ptr</STRONG>s
to be declared in conditions when using <STRONG>dynamic_pointer_cast </STRONG>or to be declared in conditions when using <STRONG>dynamic_pointer_cast </STRONG>or
<STRONG>make_shared</STRONG>.]</EM></P> <STRONG>get_shared_ptr</STRONG>.]</EM></P>
<h3><a name="swap">swap</a></h3> <h3><a name="swap">swap</a></h3>
<pre>void swap(shared_ptr &amp; b); // never throws</pre> <pre>void swap(shared_ptr &amp; b); // never throws</pre>
<blockquote> <blockquote>
@ -489,6 +499,14 @@ q = p;
<p><STRONG>Effects:</STRONG> <code>os &lt;&lt; p.get();</code>.</p> <p><STRONG>Effects:</STRONG> <code>os &lt;&lt; p.get();</code>.</p>
<P><B>Returns:</B> <b>os</b>.</P> <P><B>Returns:</B> <b>os</b>.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<h3><a name="get_deleter">get_deleter</a></h3>
<pre>template&lt;class D, class T&gt;
D * get_deleter(shared_ptr&lt;T&gt; const &amp; p);</pre>
<BLOCKQUOTE>
<P><B>Returns:</B> If <STRONG>*this</STRONG> <EM>owns</EM> a deleter <STRONG>d</STRONG>
of type (cv-unqualified) <STRONG>D</STRONG>, returns <code>&amp;d</code>;
otherwise returns 0.</P>
</BLOCKQUOTE>
<h2><a name="example">Example</a></h2> <h2><a name="example">Example</a></h2>
<p>See <A href="example/shared_ptr_example.cpp">shared_ptr_example.cpp</A> for a <p>See <A href="example/shared_ptr_example.cpp">shared_ptr_example.cpp</A> for a
complete example program. The program builds a <b>std::vector</b> and <b>std::set</b> complete example program. The program builds a <b>std::vector</b> and <b>std::set</b>
@ -648,20 +666,15 @@ int * p = a.release();
obtain a non-const pointer from a const one and then proceed to modify the obtain a non-const pointer from a const one and then proceed to modify the
object through it.<b>shared_ptr</b> is "as close to raw pointers as possible object through it.<b>shared_ptr</b> is "as close to raw pointers as possible
but no closer".<BR> but no closer".<BR>
</P> <BR>
<P><b>Q.</b> Why doesn't <b>shared_ptr</b> provide (your pet feature here)?</P>
<P>
<b>A.</b> Because (your pet feature here) would mandate a reference counted
implementation or a linked list implementation, or some other specific
implementation. This is not the intent.<BR>
</P> </P>
<hr> <hr>
<p> <p>
$Date$</p> $Date$</p>
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and Copyright 2002, 2003 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
all copies. This document is provided "as is" without express or implied all copies. This document is provided "as is" without express or implied
warranty, and with no claim as to its suitability for any purpose.</p> warranty, and with no claim as to its suitability for any purpose.</small></p>
</body> </body>
</html> </html>

2
sp_techniques.html
View File

@ -413,7 +413,7 @@ public:
virtual shared_ptr&lt;X&gt; getX() virtual shared_ptr&lt;X&gt; getX()
{ {
shared_ptr&lt;X&gt; px = make_shared(weak_this); shared_ptr&lt;X&gt; px = get_shared_ptr(weak_this);
return px; return px;
} }
}; };

10
test/shared_ptr_basic_test.cpp
View File

@ -94,7 +94,7 @@ template<class T> void test_is_Y(boost::shared_ptr<T> const & p)
template<class T> void test_is_Y(boost::weak_ptr<T> const & p) template<class T> void test_is_Y(boost::weak_ptr<T> const & p)
{ {
boost::shared_ptr<T> q = boost::make_shared(p); boost::shared_ptr<T> q = boost::get_shared_ptr(p);
BOOST_TEST(q.get() != 0); BOOST_TEST(q.get() != 0);
BOOST_TEST(q->id() == 2); BOOST_TEST(q->id() == 2);
} }
@ -221,7 +221,7 @@ int main()
{ {
} }
test_is_zero(boost::make_shared(wp1)); test_is_zero(boost::get_shared_ptr(wp1));
weak_ptr<X> wp2 = static_pointer_cast<X>(p5); weak_ptr<X> wp2 = static_pointer_cast<X>(p5);
@ -232,10 +232,10 @@ int main()
// Scoped to not affect the subsequent use_count() tests. // Scoped to not affect the subsequent use_count() tests.
{ {
shared_ptr<X> sp2(wp2); shared_ptr<X> sp2(wp2);
test_is_nonzero(boost::make_shared(wp2)); test_is_nonzero(boost::get_shared_ptr(wp2));
} }
weak_ptr<Y> wp3 = dynamic_pointer_cast<Y>(boost::make_shared(wp2)); weak_ptr<Y> wp3 = dynamic_pointer_cast<Y>(boost::get_shared_ptr(wp2));
BOOST_TEST(wp3.use_count() == 1); BOOST_TEST(wp3.use_count() == 1);
test_shared(wp2, wp3); test_shared(wp2, wp3);
@ -246,7 +246,7 @@ int main()
test_shared(wp2, wp4); test_shared(wp2, wp4);
wp1 = p2; wp1 = p2;
test_is_zero(boost::make_shared(wp1)); test_is_zero(boost::get_shared_ptr(wp1));
wp1 = p4; wp1 = p4;
wp1 = wp3; wp1 = wp3;

2
test/shared_ptr_test.cpp
View File

@ -3094,7 +3094,7 @@ public:
virtual boost::shared_ptr<X> getX() virtual boost::shared_ptr<X> getX()
{ {
boost::shared_ptr<X> px = boost::make_shared(weak_this); boost::shared_ptr<X> px = boost::get_shared_ptr(weak_this);
return px; return px;
} }
}; };

6
test/weak_ptr_test.cpp
View File

@ -1183,14 +1183,14 @@ void test()
} // namespace n_comparison } // namespace n_comparison
namespace n_make_shared namespace n_get_shared_ptr
{ {
void test() void test()
{ {
} }
} // namespace n_make_shared } // namespace n_get_shared_ptr
namespace n_map namespace n_map
{ {
@ -1272,7 +1272,7 @@ int main()
n_use_count::test(); n_use_count::test();
n_swap::test(); n_swap::test();
n_comparison::test(); n_comparison::test();
n_make_shared::test(); n_get_shared_ptr::test();
n_map::test(); n_map::test();

32
weak_ptr.htm
View File

@ -8,7 +8,6 @@
<h1><IMG height="86" alt="c++boost.gif (8819 bytes)" src="../../c++boost.gif" width="277" align="middle">weak_ptr <h1><IMG height="86" alt="c++boost.gif (8819 bytes)" src="../../c++boost.gif" width="277" align="middle">weak_ptr
class template</h1> class template</h1>
<p><A href="#Introduction">Introduction</A><br> <p><A href="#Introduction">Introduction</A><br>
<A href="#Motivation">Motivation</A><br>
<A href="#Synopsis">Synopsis</A><br> <A href="#Synopsis">Synopsis</A><br>
<A href="#Members">Members</A><br> <A href="#Members">Members</A><br>
<A href="#functions">Free Functions</A><br> <A href="#functions">Free Functions</A><br>
@ -18,12 +17,12 @@
<p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's <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> 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"> 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="#make_shared"> the <STRONG>shared_ptr</STRONG> constructor</A> or the function <STRONG><A href="#get_shared_ptr">
make_shared</A></STRONG>. When the last <b>shared_ptr</b> to the object get_shared_ptr</A></STRONG>. When the last <b>shared_ptr</b> to the
goes away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG> 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: 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>, the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>,
and <STRONG>make_shared</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p> and <STRONG>get_shared_ptr</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 <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
@ -56,7 +55,7 @@ weak_ptr&lt;int&gt; q(p);
// some time later // some time later
if(shared_ptr&lt;int&gt; r = <A href="#make_shared" >make_shared</A>(q)) if(shared_ptr&lt;int&gt; r = <A href="#get_shared_ptr" >get_shared_ptr</A>(q))
{ {
// use *r // use *r
} }
@ -64,17 +63,6 @@ if(shared_ptr&lt;int&gt; r = <A href="#make_shared" >make_shared</A>(q))
<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>. <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 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.)</p>
<h2><a name="Motivation">Motivation</a></h2>
<p>[a mechanism to avoid dangling pointers]</p>
<P>[a way to break shared_ptr cycles]</P>
<P>[weak pointer to this - a technique to obtain a shared_ptr to this from within a
member function]</P>
<P>[map&lt;weak_ptr, ...&gt; - a technique to associate arbitrary data with
shared_ptr managed objects]</P>
<P>[gameobject/tank example]</P>
<P>[cache example]</P>
<P>[comparison: weak_ptr vs observer and other approaches]</P>
<P>[hard to reinvent, subtle implementation, with many pitfalls]</P>
<h2><a name="Synopsis">Synopsis</a></h2> <h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost { <pre>namespace boost {
@ -110,7 +98,7 @@ if(shared_ptr&lt;int&gt; r = <A href="#make_shared" >make_shared</A>(q))
void <A href="#free-swap" >swap</A>(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b); void <A href="#free-swap" >swap</A>(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b);
template&lt;class T&gt; template&lt;class T&gt;
shared_ptr&lt;T&gt; <A href="#make_shared" >make_shared</A>(weak_ptr&lt;T&gt; const &amp; r); shared_ptr&lt;T&gt; <A href="#get_shared_ptr" >get_shared_ptr</A>(weak_ptr&lt;T&gt; const &amp; r);
} }
</pre> </pre>
@ -210,9 +198,9 @@ template&lt;class Y&gt; weak_ptr &amp; <A href="#assignment" >operator=</A>(shar
<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to <P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
generic programming.</P> generic programming.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<h3><a name="make_shared">make_shared</a></h3> <h3><a name="get_shared_ptr">get_shared_ptr</a></h3>
<pre>template&lt;class T&gt; <pre>template&lt;class T&gt;
shared_ptr&lt;T&gt; make_shared(weak_ptr&lt;T&gt; &amp; const r)</pre> shared_ptr&lt;T&gt; get_shared_ptr(weak_ptr&lt;T&gt; &amp; const r)</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<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>
@ -249,11 +237,11 @@ public:
</p> </p>
<hr> <hr>
<p>$Date$</p> <p>$Date$</p>
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and Copyright 2002, 2003 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
all copies. This document is provided "as is" without express or implied all copies. This document is provided "as is" without express or implied
warranty, and with no claim as to its suitability for any purpose.</p> warranty, and with no claim as to its suitability for any purpose.</small></p>
</A> </A>
</body> </body>
</html> </html>