boostorg/smart_ptr
1
0
Fork 1
mirror of https://github.com/boostorg/smart_ptr.git synced 2025-07-29 20:37:13 +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>
<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
of an instance <STRONG>t</STRONG> of type <STRONG>T</STRONG>. There must have
existed at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> pointing
to <STRONG>t</STRONG>.
of an instance <STRONG>t</STRONG> of type <STRONG>T</STRONG> . There must exist
at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> that <EM>owns</EM>
<STRONG>t</STRONG>.
</p>
<p>
<b>Returns:</b> A <b>shared_ptr&lt;T&gt;</b> instance <b>r</b> that shares
@ -85,9 +85,9 @@ public:
</blockquote>
<p>
<br>
<small>Copyright <20> 2002 by Peter Dimov. Permission to copy, use, modify, sell and
distribute this document is granted provided this copyright notice appears in
all copies. This document is provided "as is" without express or implied
<small>Copyright <20> 2002, 2003 by Peter Dimov. Permission to copy, use, modify, sell
and distribute this document is granted provided this copyright notice appears
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>
</body>
</html>

14
include/boost/weak_ptr.hpp
View File

@ -24,7 +24,7 @@
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
{
@ -64,7 +64,7 @@ public:
template<class Y>
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>
@ -77,7 +77,7 @@ public:
template<class Y>
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;
return *this;
}
@ -151,7 +151,7 @@ template<class T> void swap(weak_ptr<T> & a, weak_ptr<T> & 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)
@ -180,6 +180,12 @@ template<class T> shared_ptr<T> make_shared(weak_ptr<T> const & r) // never thro
#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
#ifdef BOOST_MSVC

8
index.htm
View File

@ -33,6 +33,10 @@
Header <a href="../../boost/shared_array.hpp">shared_array.hpp</a>.</li>
<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>
Test program <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>.</li>
<li>
@ -41,7 +45,7 @@
by <a href="../../people/peter_dimov.htm">Peter Dimov</a> and <a href="../../people/darin_adler.htm">
Darin Adler</a>.</li>
</ul>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->
1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="14885" --> .</p>
<hr>
<p>$Date$</p>
</body>
</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>,
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
responsible for destroying the object when its reference count drops to
zero. The user is expected to provide suitable definitions of these two
functions. On compilers that support argument-dependent lookup, <STRONG>intrusive_ptr_add_ref</STRONG>
responsible for destroying the object when its reference count drops to zero.
The user is expected to provide suitable definitions of these two functions. On
compilers that support argument-dependent lookup, <STRONG>intrusive_ptr_add_ref</STRONG>
and <STRONG>intrusive_ptr_release</STRONG> should be defined in the namespace
that corresponds to their parameter; otherwise, the definitions need to go in
namespace <STRONG>boost</STRONG>.</p>
@ -39,8 +39,8 @@
<LI>
<STRONG>intrusive_ptr&lt;T&gt;</STRONG> can be constructed from an arbitrary
raw pointer of type <STRONG>T *</STRONG>.</LI></UL>
<P>As a general rule, if it isn't obvious whether <STRONG>intrusive_ptr</STRONG>
better fits your needs than <STRONG>shared_ptr</STRONG>, try a <STRONG>shared_ptr</STRONG>-based
<P>As a general rule, if it isn't obvious whether <STRONG>intrusive_ptr</STRONG> better
fits your needs than <STRONG>shared_ptr</STRONG>, try a <STRONG>shared_ptr</STRONG>-based
design first.</P>
<h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost {
@ -268,9 +268,9 @@ intrusive_ptr &amp; operator=(T * r);</pre>
<p>
$Date$</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
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>
</html>

59
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
class template</h1>
<p><A href="#Introduction">Introduction</A><br>
<A href="#Motivation">Motivation</A><br>
<A href="#BestPractices">Best Practices</A><br>
<A href="#Synopsis">Synopsis</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>
where <STRONG>U</STRONG> is an accessible base of <STRONG>T</STRONG>, and to <STRONG>
shared_ptr&lt;void&gt;</STRONG>.</P>
<h2><a name="Motivation">Motivation</a></h2>
<p>[...]</p>
<h2><a name="BestPractices">Best Practices</a></h2>
<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>
@ -83,8 +80,8 @@ void bad()
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>
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
the issue for more information.</P>
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">
here</A>) of the issue for more information.</P>
<h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost {
@ -150,6 +147,8 @@ void bad()
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);
template&lt;class D, class T&gt;
D * <A href="#get_deleter">get_deleter</A>(shared_ptr&lt;T&gt; const &amp; p);
}</pre>
<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
@ -193,7 +192,7 @@ void bad()
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.
</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>Throws:</b> <b>std::bad_alloc</b> or an implementation-defined exception when
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
well-formed, must not invoke undefined behavior, and must not throw exceptions.
</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>Throws:</b> <b>std::bad_alloc</b> or an implementation-defined exception when
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>
<pre>~shared_ptr(); // never throws</pre>
<BLOCKQUOTE>
<P><B>Effects:</B> If <STRONG>*this</STRONG> is the sole owner (<code>use_count() == 1</code>),
destroys the object pointed to by the stored pointer as specified at
construction time.</P>
<P><B>Effects:</B></P>
<UL>
<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>
</BLOCKQUOTE>
<H3><a name="assignment">assignment</a></H3>
@ -381,7 +391,7 @@ q = p;
</blockquote>
<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
<STRONG>make_shared</STRONG>.]</EM></P>
<STRONG>get_shared_ptr</STRONG>.]</EM></P>
<h3><a name="swap">swap</a></h3>
<pre>void swap(shared_ptr &amp; b); // never throws</pre>
<blockquote>
@ -489,6 +499,14 @@ q = p;
<p><STRONG>Effects:</STRONG> <code>os &lt;&lt; p.get();</code>.</p>
<P><B>Returns:</B> <b>os</b>.</P>
</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>
<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>
@ -505,7 +523,7 @@ q = p;
<p>One common usage of <b>shared_ptr</b> is to implement a handle/body (also called
pimpl) idiom which avoids exposing the body (implementation) in the header
file.</p>
<p>The <A href="example/shared_ptr_example2_test.cpp">shared_ptr_example2_test.cpp</A>
<p>The <A href="example/shared_ptr_example2_test.cpp">shared_ptr_example2_test.cpp</A>
sample program includes a header file, <A href="example/shared_ptr_example2.hpp">shared_ptr_example2.hpp</A>,
which uses a <b>shared_ptr&lt;&gt;</b> to an incomplete type to hide the
implementation. The instantiation of member functions which require a complete
@ -648,20 +666,15 @@ int * p = a.release();
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
but no closer".<BR>
</P>
<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>
<BR>
</P>
<hr>
<p>
$Date$</p>
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and
distribute this document is granted provided this copyright notice appears 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.</p>
<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
distribute this document is granted provided this copyright notice appears 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>
</body>
</html>

2
sp_techniques.html
View File

@ -413,7 +413,7 @@ public:
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;
}
};

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)
{
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->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);
@ -232,10 +232,10 @@ int main()
// Scoped to not affect the subsequent use_count() tests.
{
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);
test_shared(wp2, wp3);
@ -246,7 +246,7 @@ int main()
test_shared(wp2, wp4);
wp1 = p2;
test_is_zero(boost::make_shared(wp1));
test_is_zero(boost::get_shared_ptr(wp1));
wp1 = p4;
wp1 = wp3;

2
test/shared_ptr_test.cpp
View File

@ -3094,7 +3094,7 @@ public:
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;
}
};

6
test/weak_ptr_test.cpp
View File

@ -1183,14 +1183,14 @@ void test()
} // namespace n_comparison
namespace n_make_shared
namespace n_get_shared_ptr
{
void test()
{
}
} // namespace n_make_shared
} // namespace n_get_shared_ptr
namespace n_map
{
@ -1272,7 +1272,7 @@ int main()
n_use_count::test();
n_swap::test();
n_comparison::test();
n_make_shared::test();
n_get_shared_ptr::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
class template</h1>
<p><A href="#Introduction">Introduction</A><br>
<A href="#Motivation">Motivation</A><br>
<A href="#Synopsis">Synopsis</A><br>
<A href="#Members">Members</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
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="#make_shared">
make_shared</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 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>
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>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
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
@ -56,7 +55,7 @@ weak_ptr&lt;int&gt; q(p);
// 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
}
@ -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>.
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>
<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>
<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);
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>
@ -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
generic programming.</P>
</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;
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>
<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>
@ -249,11 +237,11 @@ public:
</p>
<hr>
<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
distribute this document is granted provided this copyright notice appears 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.</p>
warranty, and with no claim as to its suitability for any purpose.</small></p>
</A>
</body>
</html>