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

Tidy documentation in smart_ptr

Browse Source
This commit is contained in:
Glen Fernandes
2014-02-04 22:45:58 -08:00
parent 9f5822f427
commit 540149f019
18 changed files with 2197 additions and 2201 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
compatibility.htm
View File

@ -1,88 +1,88 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>Smart Pointer Changes</title> <title>Smart Pointer Changes</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#ffffff" text="#000000"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>Smart Pointer Changes</h1> width="277" align="middle" border="0">Smart Pointer Changes</h1>
<p>The February 2002 change to the Boost smart pointers introduced a number of <p>The February 2002 change to the Boost smart pointers introduced a number of
changes. Since the previous version of the smart pointers was in use for a long changes. Since the previous version of the smart pointers was in use for a long
time, it's useful to have a detailed list of what changed from a library user's time, it's useful to have a detailed list of what changed from a library user's
point of view.</p> point of view.</p>
<p>Note that for compilers that don't support member templates well enough, a <p>Note that for compilers that don't support member templates well enough, a
separate implementation is used that lacks many of the new features and is more separate implementation is used that lacks many of the new features and is more
like the old version.</p> like the old version.</p>
<h2>Features Requiring Code Changes to Take Advantage</h2> <h2>Features Requiring Code Changes to Take Advantage</h2>
<ul> <ul>
<li> <li>
The smart pointer class templates now each have their own header file. For The smart pointer class templates now each have their own header file. For
compatibility, the <a href="../../boost/smart_ptr.hpp">&lt;boost/smart_ptr.hpp&gt;</a> compatibility, the <a href="../../boost/smart_ptr.hpp">&lt;boost/smart_ptr.hpp&gt;</a>
header now includes the headers for the four classic smart pointer class header now includes the headers for the four classic smart pointer class
templates. templates.
<li> <li>
The <b>weak_ptr</b> The <b>weak_ptr</b>
template was added. template was added.
<li> <li>
The new <b>shared_ptr</b> and <b>shared_array</b> relax the requirement that The new <b>shared_ptr</b> and <b>shared_array</b> relax the requirement that
the pointed-to object's destructor must be visible when instantiating the <b>shared_ptr</b> the pointed-to object's destructor must be visible when instantiating the <b>shared_ptr</b>
destructor. This makes it easier to have shared_ptr members in classes without destructor. This makes it easier to have shared_ptr members in classes without
explicit destructors. explicit destructors.
<li> <li>
A custom deallocator can be passed in when creating a <b>shared_ptr</b> or <b>shared_array</b>. A custom deallocator can be passed in when creating a <b>shared_ptr</b> or <b>shared_array</b>.
<li> <li>
<b>shared_static_cast</b> and <b>shared_dynamic_cast</b> function templates are <b>shared_static_cast</b> and <b>shared_dynamic_cast</b> function templates are
provided which work for <b>shared_ptr</b> and <b>weak_ptr</b> as <b>static_cast</b> provided which work for <b>shared_ptr</b> and <b>weak_ptr</b> as <b>static_cast</b>
and <b>dynamic_cast</b> and <b>dynamic_cast</b>
do for pointers. do for pointers.
<li> <li>
The self-assignment misfeature has been removed from <b>shared_ptr::reset</b>, The self-assignment misfeature has been removed from <b>shared_ptr::reset</b>,
although it is still present in <b>scoped_ptr</b>, and in <b>std::auto_ptr</b>. although it is still present in <b>scoped_ptr</b>, and in <b>std::auto_ptr</b>.
Calling <b>reset</b> with a pointer to the object that's already owned by the <b>shared_ptr</b> Calling <b>reset</b> with a pointer to the object that's already owned by the <b>shared_ptr</b>
results in undefined behavior (an assertion, or eventually a double-delete if results in undefined behavior (an assertion, or eventually a double-delete if
assertions are off). assertions are off).
<li> <li>
The <b>BOOST_SMART_PTR_CONVERSION</b> The <b>BOOST_SMART_PTR_CONVERSION</b>
feature has been removed. feature has been removed.
<li> <li>
<b>shared_ptr&lt;void&gt;</b> is now allowed.</li> <b>shared_ptr&lt;void&gt;</b> is now allowed.</li>
</ul> </ul>
<h2>Features That Improve Robustness</h2> <h2>Features That Improve Robustness</h2>
<ul> <ul>
<li> <li>
The manipulation of use counts is now <a name="threadsafe">thread safe</a> on The manipulation of use counts is now <a name="threadsafe">thread safe</a> on
Windows, Linux, and platforms that support pthreads. See the <a href="../../boost/detail/atomic_count.hpp"> Windows, Linux, and platforms that support pthreads. See the <a href="../../boost/detail/atomic_count.hpp">
&lt;boost/detail/atomic_count.hpp&gt;</a> &lt;boost/detail/atomic_count.hpp&gt;</a>
file for details file for details
<li> <li>
The new shared_ptr will always delete the object using the pointer it was The new shared_ptr will always delete the object using the pointer it was
originally constructed with. This prevents subtle problems that could happen if originally constructed with. This prevents subtle problems that could happen if
the last <b>shared_ptr</b> was a pointer to a sub-object of a class that did the last <b>shared_ptr</b> was a pointer to a sub-object of a class that did
not have a virtual destructor.</li> not have a virtual destructor.</li>
</ul> </ul>
<h2>Implementation Details</h2> <h2>Implementation Details</h2>
<ul> <ul>
<li> <li>
Some bugs in the assignment operator implementations and in <b>reset</b> Some bugs in the assignment operator implementations and in <b>reset</b>
have been fixed by using the "copy and swap" idiom. have been fixed by using the "copy and swap" idiom.
<li> <li>
Assertions have been added to check preconditions of various functions; Assertions have been added to check preconditions of various functions;
however, since these use the new <a href="../../boost/assert.hpp">&lt;boost/assert.hpp&gt;</a> however, since these use the new <a href="../../boost/assert.hpp">&lt;boost/assert.hpp&gt;</a>
header, the assertions are disabled by default. header, the assertions are disabled by default.
<li> <li>
The partial specialization of <b>std::less</b> has been replaced by <b>operator&lt;</b> The partial specialization of <b>std::less</b> has been replaced by <b>operator&lt;</b>
overloads which accomplish the same thing without relying on undefined overloads which accomplish the same thing without relying on undefined
behavior. behavior.
<li> <li>
The incorrect overload of <b>std::swap</b> has been replaced by <b>boost::swap</b>, The incorrect overload of <b>std::swap</b> has been replaced by <b>boost::swap</b>,
which has many of the same advantages for generic programming but does not which has many of the same advantages for generic programming but does not
violate the C++ standard.</li> violate the C++ standard.</li>
</ul> </ul>
<hr> <hr>
<p>Revised 1 February 2002</p> <p>$Date$</p>
<p><small>Copyright 2002 Darin Adler. Distributed under the Boost Software License, Version <p><small>Copyright 2002 Darin Adler. Distributed under the Boost Software License, Version
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body> </body>
</html> </html>

106
enable_shared_from_this.html
View File

@ -1,34 +1,24 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>Boost: enable_shared_from_this.hpp documentation</title> <title>enable_shared_from_this</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="white" style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<table border="0" width="100%"> <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
<tr> width="277" align="middle" border="0">enable_shared_from_this</h1>
<td width="277"><A href="../../index.htm"> <img src="../../boost.png" alt="boost.png (6897 bytes)" width="277" height="86" border="0"></A> <h2><a name="Purpose">Purpose</a></h2>
</td> <p>
<td align="center"> The header <STRONG>&lt;boost/enable_shared_from_this.hpp&gt;</STRONG> defines
<h1>enable_shared_from_this.hpp</h1> the class template <STRONG>enable_shared_from_this</STRONG>. It is used as a
</td> base class that allows a <A href="shared_ptr.htm">shared_ptr</A> to the current
</tr> object to be obtained from within a member function.
<tr> </p>
<td colspan="2" height="64">&nbsp;</td> <P><STRONG>enable_shared_from_this&lt;T&gt;</STRONG> defines two member functions
</tr> called <STRONG>shared_from_this</STRONG> that return a <STRONG>shared_ptr&lt;T&gt;</STRONG>
</table> and <STRONG>shared_ptr&lt;T const&gt;</STRONG>, depending on constness, to <STRONG>this</STRONG>.</P>
<h3><a name="Purpose">Purpose</a></h3> <h2><a name="Example">Example</a></h2>
<p> <pre>
The header <STRONG>&lt;boost/enable_shared_from_this.hpp&gt;</STRONG> defines
the class template <STRONG>enable_shared_from_this</STRONG>. It is used as a
base class that allows a <A href="shared_ptr.htm">shared_ptr</A> to the current
object to be obtained from within a member function.
</p>
<P><STRONG>enable_shared_from_this&lt;T&gt;</STRONG> defines two member functions
called <STRONG>shared_from_this</STRONG> that return a <STRONG>shared_ptr&lt;T&gt;</STRONG>
and <STRONG>shared_ptr&lt;T const&gt;</STRONG>, depending on constness, to <STRONG>this</STRONG>.</P>
<h3><a name="Example">Example</a></h3>
<pre>
#include &lt;boost/enable_shared_from_this.hpp&gt; #include &lt;boost/enable_shared_from_this.hpp&gt;
#include &lt;boost/shared_ptr.hpp&gt; #include &lt;boost/shared_ptr.hpp&gt;
#include &lt;cassert&gt; #include &lt;cassert&gt;
@ -51,8 +41,8 @@ int main()
assert(!(p &lt; q || q &lt; p)); // p and q must share ownership assert(!(p &lt; q || q &lt; p)); // p and q must share ownership
} }
</pre> </pre>
<h3><a name="Synopsis">Synopsis</a></h3> <h3><a name="Synopsis">Synopsis</a></h3>
<pre> <pre>
namespace boost namespace boost
{ {
@ -66,30 +56,30 @@ public:
} }
</pre> </pre>
<h4>template&lt;class T&gt; shared_ptr&lt;T&gt; <h4>template&lt;class T&gt; shared_ptr&lt;T&gt;
enable_shared_from_this&lt;T&gt;::shared_from_this();</h4> enable_shared_from_this&lt;T&gt;::shared_from_this();</h4>
<h4>template&lt;class T&gt; shared_ptr&lt;T const&gt; <h4>template&lt;class T&gt; shared_ptr&lt;T const&gt;
enable_shared_from_this&lt;T&gt;::shared_from_this() const;</h4> enable_shared_from_this&lt;T&gt;::shared_from_this() const;</h4>
<blockquote> <blockquote>
<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 exist 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> at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> that <EM>owns</EM>
<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
ownership with <b>p</b>. ownership with <b>p</b>.
</p> </p>
<p> <p>
<b>Postconditions:</b> <tt>r.get() == this</tt>. <b>Postconditions:</b> <tt>r.get() == this</tt>.
</p> </p>
</blockquote> </blockquote>
<p> <p>$Date$</p>
<br> <p>
<small>Copyright <EFBFBD> 2002, 2003 by Peter Dimov. Distributed under the Boost Software License, Version <small>Copyright &copy; 2002, 2003 by Peter Dimov. Distributed under the Boost Software License, Version
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body> </body>
</html> </html>

13
index.html
View File

@ -1,15 +1,18 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>Smart Pointers</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="refresh" content="0; URL=smart_ptr.htm"> <meta http-equiv="refresh" content="0; URL=smart_ptr.htm">
</head> </head>
<body> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
Automatic redirection failed, please go to Automatic redirection failed, please go to
<a href="smart_ptr.htm">smart_ptr.htm</a>. <a href="smart_ptr.htm">smart_ptr.htm</a>.
</body> </body>
</html> </html>
<!-- <!--
<09> Copyright Beman Dawes, 2001 (C) Copyright Beman Dawes, 2001
Distributed under the Boost Software License, Version 1.0. Distributed under the Boost Software License, Version 1.0.
See accompanying file LICENSE_1_0.txt or copy at See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt http://www.boost.org/LICENSE_1_0.txt
--> -->

461
intrusive_ptr.html
View File

@ -1,51 +1,51 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>intrusive_ptr</title> <title>intrusive_ptr</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body text="#000000" bgcolor="#ffffff"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><a href="../../index.htm"><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0" /></a>intrusive_ptr class template</h1> width="277" align="middle" border="0">intrusive_ptr class template</h1>
<p> <p>
<a href="#Introduction">Introduction</a><br /> <a href="#Introduction">Introduction</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>
</p> </p>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>The <code>intrusive_ptr</code> class template stores a pointer to an object with an <p>The <code>intrusive_ptr</code> class template stores a pointer to an object with an
embedded reference count. Every new <code>intrusive_ptr</code> instance increments embedded reference count. Every new <code>intrusive_ptr</code> instance increments
the reference count by using an unqualified call to the function <code>intrusive_ptr_add_ref</code>, the reference count by using an unqualified call to the function <code>intrusive_ptr_add_ref</code>,
passing it the pointer as an argument. Similarly, when an <code>intrusive_ptr</code> passing it the pointer as an argument. Similarly, when an <code>intrusive_ptr</code>
is destroyed, it calls <code>intrusive_ptr_release</code>; this function is is destroyed, it calls <code>intrusive_ptr_release</code>; this function is
responsible for destroying the object when its reference count drops to zero. 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 The user is expected to provide suitable definitions of these two functions. On
compilers that support argument-dependent lookup, <code>intrusive_ptr_add_ref</code> compilers that support argument-dependent lookup, <code>intrusive_ptr_add_ref</code>
and <code>intrusive_ptr_release</code> should be defined in the namespace and <code>intrusive_ptr_release</code> 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 <code>boost</code>. The library provides a helper base class template namespace <code>boost</code>. The library provides a helper base class template
<code><a href="intrusive_ref_counter.html">intrusive_ref_counter</a></code> which may <code><a href="intrusive_ref_counter.html">intrusive_ref_counter</a></code> which may
help adding support for <code>intrusive_ptr</code> to user types.</p> help adding support for <code>intrusive_ptr</code> to user types.</p>
<p>The class template is parameterized on <code>T</code>, the type of the object pointed <p>The class template is parameterized on <code>T</code>, the type of the object pointed
to. <code>intrusive_ptr&lt;T&gt;</code> can be implicitly converted to <code>intrusive_ptr&lt;U&gt;</code> to. <code>intrusive_ptr&lt;T&gt;</code> can be implicitly converted to <code>intrusive_ptr&lt;U&gt;</code>
whenever <code>T*</code> can be implicitly converted to <code>U*</code>.</p> whenever <code>T*</code> can be implicitly converted to <code>U*</code>.</p>
<p>The main reasons to use <code>intrusive_ptr</code> are:</p> <p>The main reasons to use <code>intrusive_ptr</code> are:</p>
<ul> <ul>
<li> <li>
Some existing frameworks or OSes provide objects with embedded reference Some existing frameworks or OSes provide objects with embedded reference
counts;</li> counts;</li>
<li> <li>
The memory footprint of <code>intrusive_ptr</code> The memory footprint of <code>intrusive_ptr</code>
is the same as the corresponding raw pointer;</li> is the same as the corresponding raw pointer;</li>
<li> <li>
<code>intrusive_ptr&lt;T&gt;</code> can be constructed from an arbitrary <code>intrusive_ptr&lt;T&gt;</code> can be constructed from an arbitrary
raw pointer of type <code>T *</code>.</li></ul> raw pointer of type <code>T *</code>.</li></ul>
<p>As a general rule, if it isn't obvious whether <code>intrusive_ptr</code> better <p>As a general rule, if it isn't obvious whether <code>intrusive_ptr</code> better
fits your needs than <code>shared_ptr</code>, try a <code>shared_ptr</code>-based fits your needs than <code>shared_ptr</code>, try a <code>shared_ptr</code>-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 {
template&lt;class T&gt; class intrusive_ptr { template&lt;class T&gt; class intrusive_ptr {
@ -117,203 +117,204 @@
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, intrusive_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, intrusive_ptr&lt;Y&gt; const &amp; p);
}</pre> }</pre>
<h2><a name="Members">Members</a></h2> <h2><a name="Members">Members</a></h2>
<h3><a name="element_type">element_type</a></h3> <h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<blockquote> <blockquote>
<p>Provides the type of the template parameter <code>T</code>.</p> <p>Provides the type of the template parameter <code>T</code>.</p>
</blockquote> </blockquote>
<h3><a name="constructors">constructors</a></h3> <h3><a name="constructors">constructors</a></h3>
<pre>intrusive_ptr(); // never throws</pre> <pre>intrusive_ptr(); // never throws</pre>
<blockquote> <blockquote>
<p><b>Postconditions:</b> <code>get() == 0</code>.</p> <p><b>Postconditions:</b> <code>get() == 0</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>intrusive_ptr(T * p, bool add_ref = true);</pre> <pre>intrusive_ptr(T * p, bool add_ref = true);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> <code>if(p != 0 &amp;&amp; add_ref) intrusive_ptr_add_ref(p);</code>.</p> <p><b>Effects:</b> <code>if(p != 0 &amp;&amp; add_ref) intrusive_ptr_add_ref(p);</code>.</p>
<p><b>Postconditions:</b> <code>get() == p</code>.</p> <p><b>Postconditions:</b> <code>get() == p</code>.</p>
</blockquote> </blockquote>
<pre>intrusive_ptr(intrusive_ptr const &amp; r); <pre>intrusive_ptr(intrusive_ptr const &amp; r);
template&lt;class Y&gt; intrusive_ptr(intrusive_ptr&lt;Y&gt; const &amp; r);</pre> template&lt;class Y&gt; intrusive_ptr(intrusive_ptr&lt;Y&gt; const &amp; r);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> <code>if(r.get() != 0) intrusive_ptr_add_ref(r.get());</code>.</p> <p><b>Effects:</b> <code>if(r.get() != 0) intrusive_ptr_add_ref(r.get());</code>.</p>
<p><b>Postconditions:</b> <code>get() == r.get()</code>.</p> <p><b>Postconditions:</b> <code>get() == r.get()</code>.</p>
</blockquote> </blockquote>
<h3><a name="destructor">destructor</a></h3> <h3><a name="destructor">destructor</a></h3>
<pre>~intrusive_ptr();</pre> <pre>~intrusive_ptr();</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</p> <p><b>Effects:</b> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</p>
</blockquote> </blockquote>
<h3><a name="assignment">assignment</a></h3> <h3><a name="assignment">assignment</a></h3>
<pre>intrusive_ptr &amp; operator=(intrusive_ptr const &amp; r); <pre>intrusive_ptr &amp; operator=(intrusive_ptr const &amp; r);
template&lt;class Y&gt; intrusive_ptr &amp; operator=(intrusive_ptr&lt;Y&gt; const &amp; r); template&lt;class Y&gt; intrusive_ptr &amp; operator=(intrusive_ptr&lt;Y&gt; const &amp; r);
intrusive_ptr &amp; operator=(T * r);</pre> intrusive_ptr &amp; operator=(T * r);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p> <p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
<p><b>Returns:</b> <code>*this</code>.</p> <p><b>Returns:</b> <code>*this</code>.</p>
</blockquote> </blockquote>
<h3><a name="reset">reset</a></h3> <h3><a name="reset">reset</a></h3>
<pre>void reset();</pre> <pre>void reset();</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr().swap(*this)</code>.</p> <p><b>Effects:</b> Equivalent to <code>intrusive_ptr().swap(*this)</code>.</p>
</blockquote> </blockquote>
<pre>void reset(T * r);</pre> <pre>void reset(T * r);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p> <p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
</blockquote> </blockquote>
<pre>void reset(T * r, bool add_ref);</pre> <pre>void reset(T * r, bool add_ref);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r, add_ref).swap(*this)</code>.</p> <p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r, add_ref).swap(*this)</code>.</p>
</blockquote> </blockquote>
<h3><a name="indirection">indirection</a></h3> <h3><a name="indirection">indirection</a></h3>
<pre>T &amp; operator*() const; // never throws</pre> <pre>T &amp; operator*() const; // never throws</pre>
<blockquote> <blockquote>
<p><b>Requirements:</b> <code>get() != 0</code>.</p> <p><b>Requirements:</b> <code>get() != 0</code>.</p>
<p><b>Returns:</b> <code>*get()</code>.</p> <p><b>Returns:</b> <code>*get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>T * operator-&gt;() const; // never throws</pre> <pre>T * operator-&gt;() const; // never throws</pre>
<blockquote> <blockquote>
<p><b>Requirements:</b> <code>get() != 0</code>.</p> <p><b>Requirements:</b> <code>get() != 0</code>.</p>
<p><b>Returns:</b> <code>get()</code>.</p> <p><b>Returns:</b> <code>get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h3><a name="get">get</a></h3> <h3><a name="get">get</a></h3>
<pre>T * get() const; // never throws</pre> <pre>T * get() const; // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> the stored pointer.</p> <p><b>Returns:</b> the stored pointer.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h3><a name="detach">detach</a></h3> <h3><a name="detach">detach</a></h3>
<pre>T * detach(); // never throws</pre> <pre>T * detach(); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> the stored pointer.</p> <p><b>Returns:</b> the stored pointer.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<p><b>Postconditions:</b> <code>get() == 0</code>.</p> <p><b>Postconditions:</b> <code>get() == 0</code>.</p>
<p><b>Notes:</b> The returned pointer has an elevated reference count. This <p><b>Notes:</b> The returned pointer has an elevated reference count. This
allows conversion of an <code>intrusive_ptr</code> back to a raw pointer, allows conversion of an <code>intrusive_ptr</code> back to a raw pointer,
without the performance overhead of acquiring and dropping an extra without the performance overhead of acquiring and dropping an extra
reference. It can be viewed as the complement of the reference. It can be viewed as the complement of the
non-reference-incrementing constructor.</p> non-reference-incrementing constructor.</p>
<p><b>Caution:</b> Using <code>detach</code> escapes the safety of automatic <p><b>Caution:</b> Using <code>detach</code> escapes the safety of automatic
reference counting provided by <code>intrusive_ptr</code>. It should reference counting provided by <code>intrusive_ptr</code>. It should
by used only where strictly necessary (such as when interfacing to an by used only where strictly necessary (such as when interfacing to an
existing API), and when the implications are thoroughly understood.</p> existing API), and when the implications are thoroughly understood.</p>
</blockquote> </blockquote>
<h3><a name="conversions">conversions</a></h3> <h3><a name="conversions">conversions</a></h3>
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is <p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is
equivalent to <code>get() != 0</code>.</p> equivalent to <code>get() != 0</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<p><b>Notes:</b> This conversion operator allows <code>intrusive_ptr</code> objects to be <p><b>Notes:</b> This conversion operator allows <code>intrusive_ptr</code> objects to be
used in boolean contexts, like <code>if (p &amp;&amp; p-&gt;valid()) {}</code>. used in boolean contexts, like <code>if (p &amp;&amp; p-&gt;valid()) {}</code>.
The actual target type is typically a pointer to a member function, avoiding The actual target type is typically a pointer to a member function, avoiding
many of the implicit conversion pitfalls.</p> many of the implicit conversion pitfalls.</p>
</blockquote> </blockquote>
<h3><a name="swap">swap</a></h3> <h3><a name="swap">swap</a></h3>
<pre>void swap(intrusive_ptr &amp; b); // never throws</pre> <pre>void swap(intrusive_ptr &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p> <p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h2><a name="functions">Free Functions</a></h2> <h2><a name="functions">Free Functions</a></h2>
<h3><a name="comparison">comparison</a></h3> <h3><a name="comparison">comparison</a></h3>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator==(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre> bool operator==(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>a.get() == b.get()</code>.</p> <p><b>Returns:</b> <code>a.get() == b.get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator!=(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre> bool operator!=(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>a.get() != b.get()</code>.</p> <p><b>Returns:</b> <code>a.get() != b.get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator==(intrusive_ptr&lt;T&gt; const &amp; a, U * b); // never throws</pre> bool operator==(intrusive_ptr&lt;T&gt; const &amp; a, U * b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>a.get() == b</code>.</p> <p><b>Returns:</b> <code>a.get() == b</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator!=(intrusive_ptr&lt;T&gt; const &amp; a, U * b); // never throws</pre> bool operator!=(intrusive_ptr&lt;T&gt; const &amp; a, U * b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>a.get() != b</code>.</p> <p><b>Returns:</b> <code>a.get() != b</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator==(T * a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre> bool operator==(T * a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>a == b.get()</code>.</p> <p><b>Returns:</b> <code>a == b.get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator!=(T * a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre> bool operator!=(T * a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>a != b.get()</code>.</p> <p><b>Returns:</b> <code>a != b.get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator&lt;(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre> bool operator&lt;(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>std::less&lt;T *&gt;()(a.get(), b.get())</code>.</p> <p><b>Returns:</b> <code>std::less&lt;T *&gt;()(a.get(), b.get())</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<p><b>Notes:</b> Allows <code>intrusive_ptr</code> objects to be used as keys <p><b>Notes:</b> Allows <code>intrusive_ptr</code> objects to be used as keys
in associative containers.</p> in associative containers.</p>
</blockquote> </blockquote>
<h3><a name="free-swap">swap</a></h3> <h3><a name="free-swap">swap</a></h3>
<pre>template&lt;class T&gt; <pre>template&lt;class T&gt;
void swap(intrusive_ptr&lt;T&gt; &amp; a, intrusive_ptr&lt;T&gt; &amp; b); // never throws</pre> void swap(intrusive_ptr&lt;T&gt; &amp; a, intrusive_ptr&lt;T&gt; &amp; b); // never throws</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Equivalent to <code>a.swap(b)</code>.</p> <p><b>Effects:</b> Equivalent to <code>a.swap(b)</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<p><b>Notes:</b> Matches the interface of <code>std::swap</code>. Provided as an aid to <p><b>Notes:</b> Matches the interface of <code>std::swap</code>. Provided as an aid to
generic programming.</p> generic programming.</p>
</blockquote> </blockquote>
<h3><a name="get_pointer">get_pointer</a></h3> <h3><a name="get_pointer">get_pointer</a></h3>
<pre>template&lt;class T&gt; <pre>template&lt;class T&gt;
T * get_pointer(intrusive_ptr&lt;T&gt; const &amp; p); // never throws</pre> T * get_pointer(intrusive_ptr&lt;T&gt; const &amp; p); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>p.get()</code>.</p> <p><b>Returns:</b> <code>p.get()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<p><b>Notes:</b> Provided as an aid to generic programming. Used by <a href="../bind/mem_fn.html"> <p><b>Notes:</b> Provided as an aid to generic programming. Used by <a href="../bind/mem_fn.html">
mem_fn</a>.</p> mem_fn</a>.</p>
</blockquote> </blockquote>
<h3><a name="static_pointer_cast">static_pointer_cast</a></h3> <h3><a name="static_pointer_cast">static_pointer_cast</a></h3>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
intrusive_ptr&lt;T&gt; static_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r); // never throws</pre> intrusive_ptr&lt;T&gt; static_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(static_cast&lt;T*&gt;(r.get()))</code>.</p> <p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(static_cast&lt;T*&gt;(r.get()))</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h3><a name="const_pointer_cast">const_pointer_cast</a></h3> <h3><a name="const_pointer_cast">const_pointer_cast</a></h3>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
intrusive_ptr&lt;T&gt; const_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r); // never throws</pre> intrusive_ptr&lt;T&gt; const_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r); // never throws</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(const_cast&lt;T*&gt;(r.get()))</code>.</p> <p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(const_cast&lt;T*&gt;(r.get()))</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3> <h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
intrusive_ptr&lt;T&gt; dynamic_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r);</pre> intrusive_ptr&lt;T&gt; dynamic_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r);</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(dynamic_cast&lt;T*&gt;(r.get()))</code>.</p> <p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(dynamic_cast&lt;T*&gt;(r.get()))</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h3><a name="insertion-operator">operator&lt;&lt;</a></h3> <h3><a name="insertion-operator">operator&lt;&lt;</a></h3>
<pre>template&lt;class E, class T, class Y&gt; <pre>template&lt;class E, class T, class Y&gt;
std::basic_ostream&lt;E, T&gt; &amp; operator&lt;&lt; (std::basic_ostream&lt;E, T&gt; &amp; os, intrusive_ptr&lt;Y&gt; const &amp; p);</pre> std::basic_ostream&lt;E, T&gt; &amp; operator&lt;&lt; (std::basic_ostream&lt;E, T&gt; &amp; os, intrusive_ptr&lt;Y&gt; const &amp; p);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> <code>os &lt;&lt; p.get();</code>.</p> <p><b>Effects:</b> <code>os &lt;&lt; p.get();</code>.</p>
<p><b>Returns:</b> <code>os</code>.</p> <p><b>Returns:</b> <code>os</code>.</p>
</blockquote> </blockquote>
<hr /> <hr>
<p> <p>$Date$</p>
<small>Copyright <20> 2003-2005, 2013 Peter Dimov. Distributed under the Boost Software License, Version <p>
1.0. See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or <small>Copyright &copy; 2003-2005, 2013 Peter Dimov. Distributed under the Boost Software License, Version
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>.</small></p> 1.0. See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
</body> copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>.</small></p>
</body>
</html> </html>

21
intrusive_ref_counter.html
View File

@ -1,12 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>intrusive_ref_counter</title> <title>intrusive_ref_counter</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body text="#000000" bgColor="#ffffff"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>basic_intrusive_ref_counter class template</h1> width="277" align="middle" border="0">basic_intrusive_ref_counter class template</h1>
<p> <p>
<A href="#Introduction">Introduction</A><br> <A href="#Introduction">Introduction</A><br>
<A href="#Synopsis">Synopsis</A><br> <A href="#Synopsis">Synopsis</A><br>
@ -14,11 +14,11 @@
</p> </p>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>The <STRONG>intrusive_ref_counter</STRONG> class template implements a reference counter for a derived <p>The <STRONG>intrusive_ref_counter</STRONG> class template implements a reference counter for a derived
user&apos;s class that is intended to be used with <STRONG><a href="intrusive_ptr.html">intrusive_ptr</a></STRONG>. user's class that is intended to be used with <STRONG><a href="intrusive_ptr.html">intrusive_ptr</a></STRONG>.
The base class has associated <STRONG>intrusive_ptr_add_ref</STRONG> and <STRONG>intrusive_ptr_release</STRONG> functions The base class has associated <STRONG>intrusive_ptr_add_ref</STRONG> and <STRONG>intrusive_ptr_release</STRONG> functions
which modify the reference counter as needed and destroy the user's object when the counter drops to zero.</p> which modify the reference counter as needed and destroy the user's object when the counter drops to zero.</p>
<p>The class template is parameterized on <STRONG>DerivedT</STRONG> and <STRONG>CounterPolicyT</STRONG> parameters. <p>The class template is parameterized on <STRONG>DerivedT</STRONG> and <STRONG>CounterPolicyT</STRONG> parameters.
The first parameter is the user&apos;s class that derives from <STRONG>intrusive_ref_counter</STRONG>. This type The first parameter is the user's class that derives from <STRONG>intrusive_ref_counter</STRONG>. This type
is needed in order to destroy the object correctly when there are no references to it left.</p> is needed in order to destroy the object correctly when there are no references to it left.</p>
<p>The second parameter is a policy that defines the nature of the reference counter. <p>The second parameter is a policy that defines the nature of the reference counter.
Boost.SmartPtr provides two such policies: <STRONG>thread_unsafe_counter</STRONG> and <STRONG>thread_safe_counter</STRONG>. The former Boost.SmartPtr provides two such policies: <STRONG>thread_unsafe_counter</STRONG> and <STRONG>thread_safe_counter</STRONG>. The former
@ -85,11 +85,10 @@
<P><B>Notes:</B> The returned value may not be actual in multi-threaded applications.</P> <P><B>Notes:</B> The returned value may not be actual in multi-threaded applications.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<hr> <hr>
<p>$Date$</p>
<p> <p>
$Date$</p> <small>Copyright &copy; 2013 Andrey Semashev. Distributed under the Boost Software License, Version
<p> 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
<small>Copyright <20> 2013 Andrey Semashev. Distributed under the Boost Software License, Version copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body> </body>
</html> </html>

154
make_shared.html
View File

@ -1,37 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>make_shared and allocate_shared</title> <title>make_shared and allocate_shared</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body text="#000000" bgColor="#ffffff"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>make_shared and allocate_shared function templates</h1> width="277" align="middle" border="0">make_shared and allocate_shared
<p><A href="#Introduction">Introduction</A><br> function templates</h1>
<A href="#Synopsis">Synopsis</A><br> <p><A href="#Introduction">Introduction</A><br>
<A href="#functions">Free Functions</A><br> <A href="#Synopsis">Synopsis</A><br>
<A href="#example">Example</A><br> <A href="#functions">Free Functions</A><br>
<h2><a name="Introduction">Introduction</a></h2> <A href="#example">Example</A><br>
<p>Consistent use of <a href="shared_ptr.htm"><code>shared_ptr</code></a> <h2><a name="Introduction">Introduction</a></h2>
can eliminate the need to use an explicit <code>delete</code>, <p>Consistent use of <a href="shared_ptr.htm"><code>shared_ptr</code></a>
but alone it provides no support in avoiding explicit <code>new</code>. can eliminate the need to use an explicit <code>delete</code>,
There have been repeated requests from users for a factory function that creates but alone it provides no support in avoiding explicit <code>new</code>.
an object of a given type and returns a <code>shared_ptr</code> to it. There have been repeated requests from users for a factory function that creates
Besides convenience and style, such a function is also exception safe and an object of a given type and returns a <code>shared_ptr</code> to it.
considerably faster because it can use a single allocation for both the object Besides convenience and style, such a function is also exception safe and
and its corresponding control block, eliminating a significant portion of considerably faster because it can use a single allocation for both the object
<code>shared_ptr</code>'s construction overhead. and its corresponding control block, eliminating a significant portion of
This eliminates one of the major efficiency complaints about <code>shared_ptr</code>. <code>shared_ptr</code>'s construction overhead.
</p> This eliminates one of the major efficiency complaints about <code>shared_ptr</code>.
<p>The header file &lt;boost/make_shared.hpp&gt; provides a family of overloaded function templates, </p>
<code>make_shared</code> and <code>allocate_shared</code>, to address this need. <p>The header file &lt;boost/make_shared.hpp&gt; provides a family of overloaded function templates,
<code>make_shared</code> uses the global operator <code>new</code> to allocate memory, <code>make_shared</code> and <code>allocate_shared</code>, to address this need.
whereas <code>allocate_shared</code> uses an user-supplied allocator, allowing finer control.</p> <code>make_shared</code> uses the global operator <code>new</code> to allocate memory,
<p> whereas <code>allocate_shared</code> uses an user-supplied allocator, allowing finer control.</p>
The rationale for choosing the name <code>make_shared</code> is that the expression <p>
<code>make_shared&lt;Widget&gt;()</code> can be read aloud and conveys the intended meaning.</p> The rationale for choosing the name <code>make_shared</code> is that the expression
<h2><a name="Synopsis">Synopsis</a></h2> <code>make_shared&lt;Widget&gt;()</code> can be read aloud and conveys the intended meaning.</p>
<pre>namespace boost { <h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost {
template&lt;typename T&gt; class shared_ptr; template&lt;typename T&gt; class shared_ptr;
@ -41,7 +42,7 @@
template&lt;typename T, typename A&gt; template&lt;typename T, typename A&gt;
shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( A const &amp; ); shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( A const &amp; );
#if !defined( BOOST_NO_CXX11_VARIADIC_TEMPLATES ) && !defined( BOOST_NO_CXX11_RVALUE_REFERENCES ) // C++0x prototypes #if !defined( BOOST_NO_CXX11_VARIADIC_TEMPLATES ) && !defined( BOOST_NO_CXX11_RVALUE_REFERENCES ) // C++0x prototypes
template&lt;typename T, typename... Args&gt; template&lt;typename T, typename... Args&gt;
shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>( Args &amp;&amp; ... args ); shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>( Args &amp;&amp; ... args );
@ -69,51 +70,50 @@
#endif #endif
}</pre> }</pre>
<h2><a name="functions">Free Functions</a></h2> <h2><a name="functions">Free Functions</a></h2>
<pre>template&lt;class T, class... Args&gt; <pre>template&lt;class T, class... Args&gt;
shared_ptr&lt;T&gt; make_shared( Args &amp;&amp; ... args ); shared_ptr&lt;T&gt; make_shared( Args &amp;&amp; ... args );
template&lt;class T, class A, class... Args&gt; template&lt;class T, class A, class... Args&gt;
shared_ptr&lt;T&gt; allocate_shared( A const &amp; a, Args &amp;&amp; ... args );</pre> shared_ptr&lt;T&gt; allocate_shared( A const &amp; a, Args &amp;&amp; ... args );</pre>
<blockquote> <blockquote>
<p><b>Requires:</b> The expression <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>, <p><b>Requires:</b> The expression <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>,
where <code>pv</code> is a <code>void*</code> pointing to storage suitable where <code>pv</code> is a <code>void*</code> pointing to storage suitable
to hold an object of type <code>T</code>, to hold an object of type <code>T</code>,
shall be well-formed. <code>A</code> shall be an <em>Allocator</em>, shall be well-formed. <code>A</code> shall be an <em>Allocator</em>,
as described in section 20.1.5 (<stong>Allocator requirements</strong>) of the C++ Standard. as described in section 20.1.5 (<strong>Allocator requirements</strong>) of the C++ Standard.
The copy constructor and destructor of <code>A</code> shall not throw.</p> The copy constructor and destructor of <code>A</code> shall not throw.</p>
<p><b>Effects:</b> Allocates memory suitable for an object of type <code>T</code> <p><b>Effects:</b> Allocates memory suitable for an object of type <code>T</code>
and constructs an object in it via the placement new expression <code>new( pv ) T()</code> and constructs an object in it via the placement new expression <code>new( pv ) T()</code>
or <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>. or <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>.
<code>allocate_shared</code> uses a copy of <code>a</code> to allocate memory. <code>allocate_shared</code> uses a copy of <code>a</code> to allocate memory.
If an exception is thrown, has no effect.</p> If an exception is thrown, has no effect.</p>
<p><b>Returns:</b> A <code>shared_ptr</code> instance that stores and owns the address <p><b>Returns:</b> A <code>shared_ptr</code> instance that stores and owns the address
of the newly constructed object of type <code>T</code>.</p> of the newly constructed object of type <code>T</code>.</p>
<p><b>Postconditions:</b> <code>get() != 0 &amp;&amp; use_count() == 1</code>.</p> <p><b>Postconditions:</b> <code>get() != 0 &amp;&amp; use_count() == 1</code>.</p>
<p><b>Throws:</b> <code>bad_alloc</code>, or an exception thrown from <code>A::allocate</code> <p><b>Throws:</b> <code>bad_alloc</code>, or an exception thrown from <code>A::allocate</code>
or the constructor of <code>T</code>.</p> or the constructor of <code>T</code>.</p>
<p><b>Notes:</b> This implementation allocates the memory required for the <p><b>Notes:</b> This implementation allocates the memory required for the
returned <code>shared_ptr</code> and an object of type <code>T</code> in a single returned <code>shared_ptr</code> and an object of type <code>T</code> in a single
allocation. This provides efficiency equivalent to an intrusive smart pointer.</p> allocation. This provides efficiency equivalent to an intrusive smart pointer.</p>
<p>The prototypes shown above are used if your compiler supports rvalue references <p>The prototypes shown above are used if your compiler supports rvalue references
and variadic templates. They perfectly forward the <code>args</code> parameters to and variadic templates. They perfectly forward the <code>args</code> parameters to
the constructors of <code>T</code>.</p> the constructors of <code>T</code>.</p>
<p>Otherwise, the implementation will fall back on <p>Otherwise, the implementation will fall back on
forwarding the arguments to the constructors of <code>T</code> as const references. forwarding the arguments to the constructors of <code>T</code> as const references.
If you need to pass a non-const reference to a constructor of <code>T</code>, If you need to pass a non-const reference to a constructor of <code>T</code>,
you may do so by wrapping the parameter in a call to <code>boost::ref</code>. you may do so by wrapping the parameter in a call to <code>boost::ref</code>.
In addition, you will be In addition, you will be
limited to a maximum of 9 arguments (not counting the allocator argument of limited to a maximum of 9 arguments (not counting the allocator argument of
allocate_shared).</p> allocate_shared).</p>
</blockquote> </blockquote>
<h2><a name="example">Example</a></h2> <h2><a name="example">Example</a></h2>
<pre>boost::shared_ptr&lt;std::string&gt; x = boost::make_shared&lt;std::string&gt;("hello, world!"); <pre>boost::shared_ptr&lt;std::string&gt; x = boost::make_shared&lt;std::string&gt;("hello, world!");
std::cout << *x;</pre> std::cout << *x;</pre>
<hr> <hr>
<p> <p>$Date$</p>
$Date: 2008-05-19 15:42:39 -0400 (Mon, 19 May 2008) $</p> <p><small>Copyright 2008 Peter Dimov. Copyright 2008 Frank Mori Hess.
<p><small>Copyright 2008 Peter Dimov. Copyright 2008 Frank Mori Hess. Distributed under the Boost Software License,
Distributed under the Boost Software License, Version 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
Version 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> </body>
</body>
</html> </html>

8
make_shared_array.html
View File

@ -250,8 +250,10 @@ boost::shared_ptr&lt;int[4][2]&gt; a2 = boost::make_shared_noinit&lt;int[4][2]&g
</blockquote> </blockquote>
</blockquote> </blockquote>
<h2><a name="history">History</a></h2> <h2><a name="history">History</a></h2>
<p>January 2014. Glen Fernandes reduced the overloads of make_shared and <p>February 2014. Glen Fernandes updated overloads of make_shared and
allocate_shared according to <a href="#N3870">N3870</a>.</p> allocate_shared to conform to the specification in C++ standard paper
<a href="#N3870">N3870</a> including resolving C++ standard library
defect report 2070.</p>
<p>November 2012. Glen Fernandes contributed implementations of <p>November 2012. Glen Fernandes contributed implementations of
make_shared and allocate_shared for arrays.</p> make_shared and allocate_shared for arrays.</p>
<h2><a name="references">References</a></h2> <h2><a name="references">References</a></h2>
@ -260,7 +262,7 @@ boost::shared_ptr&lt;int[4][2]&gt; a2 = boost::make_shared_noinit&lt;int[4][2]&g
Extending make_shared to Support Arrays, Revision 1</a>, Peter Dimov Extending make_shared to Support Arrays, Revision 1</a>, Peter Dimov
&amp; Glen Fernandes, January, 2014.</p> &amp; Glen Fernandes, January, 2014.</p>
<hr> <hr>
<p>$Date: 2014-01-20 11:10:00 -0800 (Mon, 20 Jan 2014) $</p> <p>$Date$</p>
<p><small>Copyright 2012-2014 Glen Fernandes. Distributed under the <p><small>Copyright 2012-2014 Glen Fernandes. Distributed under the
Boost Software License, Version 1.0. See accompanying file Boost Software License, Version 1.0. See accompanying file
<a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at

2
make_unique.html
View File

@ -142,7 +142,7 @@ unique_ptr&lt;int[][2]&gt; p2 = boost::make_unique_noinit&lt;int[][2]&gt;(2);</p
<p>January 2014. Glen Fernandes contributed implementations of <p>January 2014. Glen Fernandes contributed implementations of
make_unique for objects and arrays.</p> make_unique for objects and arrays.</p>
<hr> <hr>
<p>$Date: 2014-01-20 11:10:00 -0800 (Mon, 20 Jan 2014) $</p> <p>$Date$</p>
<p><small>Copyright 2012-2014 Glen Fernandes. Distributed under the <p><small>Copyright 2012-2014 Glen Fernandes. Distributed under the
Boost Software License, Version 1.0. See accompanying file Boost Software License, Version 1.0. See accompanying file
<a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at

83
pointer_cast.html
View File

@ -1,33 +1,34 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>pointer_cast.hpp</title> <title>pointer_cast</title>
</head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<body> </head>
<h1><IMG height="86" alt="C++ Boost" src="../../boost.png" width="277" align="middle" border="0">Pointer <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
cast functions</h1> <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
<p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code> width="277" align="middle" border="0">pointer_cast</h1>
<code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>) <p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code>
provide a way to write generic pointer castings for raw pointers. The functions <code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>)
are defined in <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A>.</CITE></p> provide a way to write generic pointer castings for raw pointers. The functions
<P>There is test/example code in <CITE><A href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</A></CITE>.</p> are defined in <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A>.</CITE></p>
<h2><a name="rationale">Rationale</a></h2> <P>There is test/example code in <CITE><A href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</A></CITE>.</p>
<P>Boost smart pointers usually overload those functions to provide a mechanism to <h2><a name="rationale">Rationale</a></h2>
emulate pointers casts. For example, <code>boost::shared_ptr&lt;...&gt;</code> implements <P>Boost smart pointers usually overload those functions to provide a mechanism to
a static pointer cast this way:</P> emulate pointers casts. For example, <code>boost::shared_ptr&lt;...&gt;</code> implements
<pre> a static pointer cast this way:</P>
<pre>
template&lt;class T, class U&gt; template&lt;class T, class U&gt;
shared_ptr&lt;T&gt; static_pointer_cast(shared_ptr&lt;U&gt; const &amp;r); shared_ptr&lt;T&gt; static_pointer_cast(shared_ptr&lt;U&gt; const &amp;r);
</pre> </pre>
<P>Pointer cast functions from <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A></CITE> <P>Pointer cast functions from <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A></CITE>
are overloads of <code>boost::static_pointer_cast</code>, <code>boost::dynamic_pointer_cast</code>, are overloads of <code>boost::static_pointer_cast</code>, <code>boost::dynamic_pointer_cast</code>,
<code>boost::reinterpret_pointer_cast</code> and <code>boost::const_pointer_cast</code> <code>boost::reinterpret_pointer_cast</code> and <code>boost::const_pointer_cast</code>
for raw pointers. This way when developing pointer type independent classes, for raw pointers. This way when developing pointer type independent classes,
for example, memory managers or shared memory compatible classes, the same code for example, memory managers or shared memory compatible classes, the same code
can be used for raw and smart pointers.</p> can be used for raw and smart pointers.</p>
<H2><A name="synopsis">Synopsis</A></H2> <H2><A name="synopsis">Synopsis</A></H2>
<BLOCKQUOTE> <BLOCKQUOTE>
<PRE> <PRE>
namespace boost { namespace boost {
template&lt;class T, class U&gt; template&lt;class T, class U&gt;
@ -48,12 +49,12 @@ inline T* reinterpret_pointer_cast(U *ptr)
} // namespace boost } // namespace boost
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
<P>As you can see from the above synopsis, the pointer cast functions are just <P>As you can see from the above synopsis, the pointer cast functions are just
wrappers around standard C++ cast operators.</P> wrappers around standard C++ cast operators.</P>
<H2><A name="example">Example</A></H2> <H2><A name="example">Example</A></H2>
<BLOCKQUOTE> <BLOCKQUOTE>
<PRE> <PRE>
#include &lt;boost/pointer_cast.hpp&gt; #include &lt;boost/pointer_cast.hpp&gt;
#include &lt;boost/shared_ptr.hpp&gt; #include &lt;boost/shared_ptr.hpp&gt;
@ -93,13 +94,13 @@ int main()
delete ptr; delete ptr;
return 0; return 0;
}</PRE> }</PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
<P>The example demonstrates how the generic pointer casts help us create pointer <P>The example demonstrates how the generic pointer casts help us create pointer
independent code.</P> independent code.</P>
<hr> <hr>
<p>Revised: $Date$</p> <p>$Date$</p>
<p>Copyright 2005 Ion Gazta<74>aga. Use, modification, and distribution are subject to <p>Copyright 2005 Ion Gazta<74>aga. Use, modification, and distribution are subject to
the Boost Software License, Version 1.0. (See accompanying file <A href="../../LICENSE_1_0.txt"> the Boost Software License, Version 1.0. (See accompanying file <A href="../../LICENSE_1_0.txt">
LICENSE_1_0.txt</A> or a copy at &lt;<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>&gt;.)</p> LICENSE_1_0.txt</A> or a copy at &lt;<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>&gt;.)</p>
</body> </body>
</html> </html>

84
pointer_to_other.html
View File

@ -1,33 +1,33 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>pointer_to_other.hpp</title> <title>pointer_to_other</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#ffffff" text="#000000"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" WIDTH="277" HEIGHT="86">Header <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
<a href="../../boost/pointer_to_other.hpp">boost/pointer_to_other.hpp</a></h1> width="277" align="middle" border="0">pointer_to_other</h1>
<p> <p>
The pointer to other utility provides a way, given a source pointer type, The pointer to other utility provides a way, given a source pointer type,
to obtain a pointer of the same type to another pointee type. The utility is to obtain a pointer of the same type to another pointee type. The utility is
defined in <cite><a href="../../boost/pointer_to_other.hpp">boost/pointer_to_other.hpp</a>.</cite></p> defined in <cite><a href="../../boost/pointer_to_other.hpp">boost/pointer_to_other.hpp</a>.</cite></p>
<p>There is test/example code in <cite><a href="test/pointer_to_other_test.cpp">pointer_to_other_test.cpp</a></cite>.</p> <p>There is test/example code in <cite><a href="test/pointer_to_other_test.cpp">pointer_to_other_test.cpp</a></cite>.</p>
<h2><a name="contents">Contents</a></h2> <h2><a name="contents">Contents</a></h2>
<ul> <ul>
<li> <li>
<a href="#rationale">Rationale</a> <a href="#rationale">Rationale</a>
<li> <li>
<a href="#synopsis">Synopsis</a> <a href="#synopsis">Synopsis</a>
<li> <li>
<a href="#example">Example</a></li> <a href="#example">Example</a></li>
</ul> </ul>
<h2><a name="rationale">Rationale</a></h2> <h2><a name="rationale">Rationale</a></h2>
<p>When building pointer independent classes, like memory managers, allocators, or <p>When building pointer independent classes, like memory managers, allocators, or
containers, there is often a need to define pointers generically, so that if a containers, there is often a need to define pointers generically, so that if a
template parameter represents a pointer (for example, a raw or smart pointer to template parameter represents a pointer (for example, a raw or smart pointer to
an int), we can define another pointer of the same type to another pointee (a an int), we can define another pointer of the same type to another pointee (a
raw or smart pointer to a float.)</p> raw or smart pointer to a float.)</p>
<pre>template &lt;class IntPtr&gt; <pre>template &lt;class IntPtr&gt;
class FloatPointerHolder class FloatPointerHolder
{ {
<em>// Let's define a pointer to a float</em> <em>// Let's define a pointer to a float</em>
@ -35,8 +35,8 @@ class FloatPointerHolder
&lt;IntPtr, float&gt;::type float_ptr_t; &lt;IntPtr, float&gt;::type float_ptr_t;
float_ptr_t float_ptr; float_ptr_t float_ptr;
};</pre> };</pre>
<h2><a name="synopsis">Synopsis</a></h2> <h2><a name="synopsis">Synopsis</a></h2>
<pre> <pre>
namespace boost { namespace boost {
template&lt;class T, class U&gt; template&lt;class T, class U&gt;
@ -69,10 +69,10 @@ struct pointer_to_other&lt; T*, U &gt;
}; };
} <em>// namespace boost</em></pre> } <em>// namespace boost</em></pre>
<p>If these definitions are not correct for a specific smart pointer, we can define <p>If these definitions are not correct for a specific smart pointer, we can define
a specialization of pointer_to_other.</p> a specialization of pointer_to_other.</p>
<h2><a name="example">Example</a></h2> <h2><a name="example">Example</a></h2>
<pre><em>// Let's define a memory allocator that can <pre><em>// Let's define a memory allocator that can
// work with raw and smart pointers</em> // work with raw and smart pointers</em>
#include &lt;boost/pointer_to_other.hpp&gt; #include &lt;boost/pointer_to_other.hpp&gt;
@ -97,12 +97,12 @@ class memory_allocator
block_ptr_t free_blocks; block_ptr_t free_blocks;
};</pre> };</pre>
<p>As we can see, using pointer_to_other we can create pointer independent code.</p> <p>As we can see, using pointer_to_other we can create pointer independent code.</p>
<hr> <hr>
<p>Last revised: $Date$</p> <p>$Date$</p>
<p><small>Copyright 2005, 2006 Ion Gazta<74>aga and Peter Dimov. Use, modification, <p><small>Copyright 2005, 2006 Ion Gazta<74>aga and Peter Dimov. Use, modification,
and distribution are subject to the Boost Software License, Version 1.0.<br> and distribution are subject to the Boost Software License, Version 1.0.<br>
(See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or a (See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or a
copy at &lt; <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>&gt;.)</small></p> copy at &lt; <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>&gt;.)</small></p>
</body> </body>
</html> </html>

183
scoped_array.htm
View File

@ -1,38 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>scoped_array</title> <title>scoped_array</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#ffffff" text="#000000"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>scoped_array class template</h1> width="277" align="middle" border="0">scoped_array class template</h1>
<p>The <b>scoped_array</b> class template stores a pointer to a dynamically <p>The <b>scoped_array</b> class template stores a pointer to a dynamically
allocated array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b> allocated array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b>
expression.) The array pointed to is guaranteed to be deleted, either on expression.) The array pointed to is guaranteed to be deleted, either on
destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p> destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p>
<p>The <b>scoped_array</b> template is a simple solution for simple needs. It <p>The <b>scoped_array</b> template is a simple solution for simple needs. It
supplies a basic "resource acquisition is initialization" facility, without supplies a basic "resource acquisition is initialization" facility, without
shared-ownership or transfer-of-ownership semantics. Both its name and shared-ownership or transfer-of-ownership semantics. Both its name and
enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable"> enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
noncopyable</a>) signal its intent to retain ownership solely within the noncopyable</a>) signal its intent to retain ownership solely within the
current scope. Because it is <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>, current scope. Because it is <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>,
it is safer than <b>shared_array</b> for pointers which should not be copied.</p> it is safer than <b>shared_array</b> for pointers which should not be copied.</p>
<p>Because <b>scoped_array</b> is so simple, in its usual implementation every <p>Because <b>scoped_array</b> is so simple, in its usual implementation every
operation is as fast as a built-in array pointer and it has no more space operation is as fast as a built-in array pointer and it has no more space
overhead that a built-in array pointer.</p> overhead that a built-in array pointer.</p>
<p>It cannot be used in C++ standard library containers. See <a href="shared_array.htm"> <p>It cannot be used in C++ standard library containers. See <a href="shared_array.htm">
<b>shared_array</b></a> if <b>scoped_array</b> does not meet your needs.</p> <b>shared_array</b></a> if <b>scoped_array</b> does not meet your needs.</p>
<p>It cannot correctly hold a pointer to a single object. See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a> <p>It cannot correctly hold a pointer to a single object. See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
for that usage.</p> for that usage.</p>
<p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is a bit <p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is a bit
heavier duty but far more flexible. A <b>boost::array</b> is an alternative heavier duty but far more flexible. A <b>boost::array</b> is an alternative
that does not use dynamic allocation.</p> that does not use dynamic allocation.</p>
<p>The class template is parameterized on <b>T</b>, the type of the object pointed <p>The class template is parameterized on <b>T</b>, the type of the object pointed
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements"> to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
common requirements</a>.</p> common requirements</a>.</p>
<h2>Synopsis</h2> <h2>Synopsis</h2>
<pre>namespace boost { <pre>namespace boost {
template&lt;class T&gt; class scoped_array : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> { template&lt;class T&gt; class scoped_array : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
@ -55,62 +55,61 @@
template&lt;class T&gt; void <a href="#free-swap">swap</a>(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws template&lt;class T&gt; void <a href="#free-swap">swap</a>(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws
}</pre> }</pre>
<h2>Members</h2> <h2>Members</h2>
<h3> <h3>
<a name="element_type">element_type</a></h3> <a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="ctor">constructors</a></h3> <h3><a name="ctor">constructors</a></h3>
<pre>explicit scoped_array(T * p = 0); // never throws</pre> <pre>explicit scoped_array(T * p = 0); // never throws</pre>
<p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must have <p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must have
been allocated via a C++ <b>new</b>[] expression or be 0. <b>T</b> is not been allocated via a C++ <b>new</b>[] expression or be 0. <b>T</b> is not
required be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements"> required be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">
common requirements</a>.</p> common requirements</a>.</p>
<h3><a name="destructor">destructor</a></h3> <h3><a name="destructor">destructor</a></h3>
<pre>~scoped_array(); // never throws</pre> <pre>~scoped_array(); // never throws</pre>
<p>Deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on <p>Deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
a pointer with a value of 0 is harmless. The guarantee that this does not throw a pointer with a value of 0 is harmless. The guarantee that this does not throw
exceptions depends on the requirement that the deleted array's objects' exceptions depends on the requirement that the deleted array's objects'
destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#common_requirements"> destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#common_requirements">
common requirements</a>.</p> common requirements</a>.</p>
<h3><a name="reset">reset</a></h3> <h3><a name="reset">reset</a></h3>
<pre>void reset(T * p = 0); // never throws</pre> <pre>void reset(T * p = 0); // never throws</pre>
<p> <p>
Deletes the array pointed to by the stored pointer and then stores a copy of p, Deletes the array pointed to by the stored pointer and then stores a copy of p,
which must have been allocated via a C++ <b>new[]</b> expression or be 0. The which must have been allocated via a C++ <b>new[]</b> expression or be 0. The
guarantee that this does not throw exceptions depends on the requirement that guarantee that this does not throw exceptions depends on the requirement that
the deleted array's objects' destructors do not throw exceptions. See the smart the deleted array's objects' destructors do not throw exceptions. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
<h3><a name="operator[]">subscripting</a></h3> <h3><a name="operator[]">subscripting</a></h3>
<pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre> <pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
<p>Returns a reference to element <b>i</b> of the array pointed to by the stored <p>Returns a reference to element <b>i</b> of the array pointed to by the stored
pointer. Behavior is undefined and almost certainly undesirable if the stored pointer. Behavior is undefined and almost certainly undesirable if the stored
pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
number of elements in the array.</p> number of elements in the array.</p>
<h3><a name="get">get</a></h3> <h3><a name="get">get</a></h3>
<pre>T * get() const; // never throws</pre> <pre>T * get() const; // never throws</pre>
<p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
<h3><a name="conversions">conversions</a></h3> <h3><a name="conversions">conversions</a></h3>
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent <p>Returns an unspecified value that, when used in boolean contexts, is equivalent
to <code>get() != 0</code>.</p> to <code>get() != 0</code>.</p>
<h3><a name="swap">swap</a></h3> <h3><a name="swap">swap</a></h3>
<pre>void swap(scoped_array &amp; b); // never throws</pre> <pre>void swap(scoped_array &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
requirements</a>.</p> requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2> <h2><a name="functions">Free Functions</a></h2>
<h3><a name="free-swap">swap</a></h3> <h3><a name="free-swap">swap</a></h3>
<pre>template&lt;class T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws</pre> <pre>template&lt;class T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>. <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p> Provided as an aid to generic programming.</p>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan--> <p>$Date$</p>
09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310"--></p> <p><small>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-2005 Peter Dimov. Distributed under the Boost Software License, Version
Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> </body>
</body>
</html> </html>

271
scoped_ptr.htm
View File

@ -1,38 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>scoped_ptr</title> <title>scoped_ptr</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#ffffff" text="#000000"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>scoped_ptr class template</h1> width="277" align="middle" border="0">scoped_ptr class template</h1>
<p>The <b>scoped_ptr</b> class template stores a pointer to a dynamically allocated <p>The <b>scoped_ptr</b> class template stores a pointer to a dynamically allocated
object. (Dynamically allocated objects are allocated with the C++ <b>new</b> expression.) object. (Dynamically allocated objects are allocated with the C++ <b>new</b> expression.)
The object pointed to is guaranteed to be deleted, either on destruction of the <b>scoped_ptr</b>, The object pointed to is guaranteed to be deleted, either on destruction of the <b>scoped_ptr</b>,
or via an explicit <b>reset</b>. See the <a href="#example">example</a>.</p> or via an explicit <b>reset</b>. See the <a href="#example">example</a>.</p>
<p>The <b>scoped_ptr</b> template is a simple solution for simple needs. It <p>The <b>scoped_ptr</b> template is a simple solution for simple needs. It
supplies a basic "resource acquisition is initialization" facility, without supplies a basic "resource acquisition is initialization" facility, without
shared-ownership or transfer-of-ownership semantics. Both its name and shared-ownership or transfer-of-ownership semantics. Both its name and
enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable"> enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
noncopyable</a>) signal its intent to retain ownership solely within the noncopyable</a>) signal its intent to retain ownership solely within the
current scope. Because it is <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>, current scope. Because it is <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>,
it is safer than <b>shared_ptr</b> or <b>std::auto_ptr</b> for pointers which it is safer than <b>shared_ptr</b> or <b>std::auto_ptr</b> for pointers which
should not be copied.</p> should not be copied.</p>
<p>Because <b>scoped_ptr</b> is simple, in its usual implementation every operation <p>Because <b>scoped_ptr</b> is simple, in its usual implementation every operation
is as fast as for a built-in pointer and it has no more space overhead that a is as fast as for a built-in pointer and it has no more space overhead that a
built-in pointer.</p> built-in pointer.</p>
<p><STRONG>scoped_ptr</STRONG> cannot be used in C++ Standard Library containers. <p><STRONG>scoped_ptr</STRONG> cannot be used in C++ Standard Library containers.
Use <a href="shared_ptr.htm"><b>shared_ptr</b></a> if you need a smart pointer Use <a href="shared_ptr.htm"><b>shared_ptr</b></a> if you need a smart pointer
that can.</p> that can.</p>
<p><STRONG>scoped_ptr</STRONG> cannot correctly hold a pointer to a dynamically <p><STRONG>scoped_ptr</STRONG> cannot correctly hold a pointer to a dynamically
allocated array. See <a href="scoped_array.htm"><b>scoped_array</b></a> for allocated array. See <a href="scoped_array.htm"><b>scoped_array</b></a> for
that usage.</p> that usage.</p>
<p>The class template is parameterized on <b>T</b>, the type of the object pointed <p>The class template is parameterized on <b>T</b>, the type of the object pointed
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements"> to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
common requirements</a>.</p> common requirements</a>.</p>
<h2>Synopsis</h2> <h2>Synopsis</h2>
<pre>namespace boost { <pre>namespace boost {
template&lt;class T&gt; class scoped_ptr : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> { template&lt;class T&gt; class scoped_ptr : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
@ -56,60 +56,60 @@
template&lt;class T&gt; void <a href="#free-swap">swap</a>(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws template&lt;class T&gt; void <a href="#free-swap">swap</a>(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws
}</pre> }</pre>
<h2>Members</h2> <h2>Members</h2>
<h3><a name="element_type">element_type</a></h3> <h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="constructors">constructors</a></h3> <h3><a name="constructors">constructors</a></h3>
<pre>explicit scoped_ptr(T * p = 0); // never throws</pre> <pre>explicit scoped_ptr(T * p = 0); // never throws</pre>
<p>Constructs a <b>scoped_ptr</b>, storing a copy of <b>p</b>, which must have been <p>Constructs a <b>scoped_ptr</b>, storing a copy of <b>p</b>, which must have been
allocated via a C++ <b>new</b> expression or be 0. <b>T</b> is not required be allocated via a C++ <b>new</b> expression or be 0. <b>T</b> is not required be
a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
requirements</a>.</p> requirements</a>.</p>
<h3><a name="destructor">destructor</a></h3> <h3><a name="destructor">destructor</a></h3>
<pre>~scoped_ptr(); // never throws</pre> <pre>~scoped_ptr(); // never throws</pre>
<p>Destroys the object pointed to by the stored pointer, if any, as if by using <tt>delete <p>Destroys the object pointed to by the stored pointer, if any, as if by using <tt>delete
this-&gt;get()</tt>.</p> this-&gt;get()</tt>.</p>
<P> <P>
The guarantee that this does not throw exceptions depends on the requirement The guarantee that this does not throw exceptions depends on the requirement
that the deleted object's destructor does not throw exceptions. See the smart that the deleted object's destructor does not throw exceptions. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</P> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</P>
<h3><a name="reset">reset</a></h3> <h3><a name="reset">reset</a></h3>
<pre>void reset(T * p = 0); // never throws</pre> <pre>void reset(T * p = 0); // never throws</pre>
<p> <p>
Deletes the object pointed to by the stored pointer and then stores a copy of Deletes the object pointed to by the stored pointer and then stores a copy of
p, which must have been allocated via a C++ <b>new</b> expression or be 0. The p, which must have been allocated via a C++ <b>new</b> expression or be 0. The
guarantee that this does not throw exceptions depends on the requirement that guarantee that this does not throw exceptions depends on the requirement that
the deleted object's destructor does not throw exceptions. See the smart the deleted object's destructor does not throw exceptions. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
<h3><a name="indirection">indirection</a></h3> <h3><a name="indirection">indirection</a></h3>
<pre>T &amp; operator*() const; // never throws</pre> <pre>T &amp; operator*() const; // never throws</pre>
<p>Returns a reference to the object pointed to by the stored pointer. Behavior is <p>Returns a reference to the object pointed to by the stored pointer. Behavior is
undefined if the stored pointer is 0.</p> undefined if the stored pointer is 0.</p>
<pre>T * operator-&gt;() const; // never throws</pre> <pre>T * operator-&gt;() const; // never throws</pre>
<p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p> <p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p>
<h3><a name="get">get</a></h3> <h3><a name="get">get</a></h3>
<pre>T * get() const; // never throws</pre> <pre>T * get() const; // never throws</pre>
<p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
<h3><a name="conversions">conversions</a></h3> <h3><a name="conversions">conversions</a></h3>
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent <p>Returns an unspecified value that, when used in boolean contexts, is equivalent
to <code>get() != 0</code>.</p> to <code>get() != 0</code>.</p>
<h3><a name="swap">swap</a></h3> <h3><a name="swap">swap</a></h3>
<pre>void swap(scoped_ptr &amp; b); // never throws</pre> <pre>void swap(scoped_ptr &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
requirements</a>.</p> requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2> <h2><a name="functions">Free Functions</a></h2>
<h3><a name="free-swap">swap</a></h3> <h3><a name="free-swap">swap</a></h3>
<pre>template&lt;class T&gt; void swap(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws</pre> <pre>template&lt;class T&gt; void swap(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>. <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p> Provided as an aid to generic programming.</p>
<h2><a name="example">Example</a></h2> <h2><a name="example">Example</a></h2>
<p>Here's an example that uses <b>scoped_ptr</b>.</p> <p>Here's an example that uses <b>scoped_ptr</b>.</p>
<blockquote> <blockquote>
<pre>#include &lt;boost/scoped_ptr.hpp&gt; <pre>#include &lt;boost/scoped_ptr.hpp&gt;
#include &lt;iostream&gt; #include &lt;iostream&gt;
struct Shoe { ~Shoe() { std::cout &lt;&lt; "Buckle my shoe\n"; } }; struct Shoe { ~Shoe() { std::cout &lt;&lt; "Buckle my shoe\n"; } };
@ -128,54 +128,53 @@ int main()
std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n'; std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n';
std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n'; std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n';
}</pre> }</pre>
</blockquote> </blockquote>
<p>The example program produces the beginning of a child's nursery rhyme:</p> <p>The example program produces the beginning of a child's nursery rhyme:</p>
<blockquote> <blockquote>
<pre>1 <pre>1
2 2
Buckle my shoe</pre> Buckle my shoe</pre>
</blockquote> </blockquote>
<h2>Rationale</h2> <h2>Rationale</h2>
<p>The primary reason to use <b>scoped_ptr</b> rather than <b>auto_ptr</b> is to <p>The primary reason to use <b>scoped_ptr</b> rather than <b>auto_ptr</b> is to
let readers of your code know that you intend "resource acquisition is let readers of your code know that you intend "resource acquisition is
initialization" to be applied only for the current scope, and have no intent to initialization" to be applied only for the current scope, and have no intent to
transfer ownership.</p> transfer ownership.</p>
<p>A secondary reason to use <b>scoped_ptr</b> is to prevent a later maintenance <p>A secondary reason to use <b>scoped_ptr</b> is to prevent a later maintenance
programmer from adding a function that transfers ownership by returning the <b>auto_ptr</b>, programmer from adding a function that transfers ownership by returning the <b>auto_ptr</b>,
because the maintenance programmer saw <b>auto_ptr</b>, and assumed ownership because the maintenance programmer saw <b>auto_ptr</b>, and assumed ownership
could safely be transferred.</p> could safely be transferred.</p>
<p>Think of <b>bool</b> vs <b>int</b>. We all know that under the covers <b>bool</b> <p>Think of <b>bool</b> vs <b>int</b>. We all know that under the covers <b>bool</b>
is usually just an <b>int</b>. Indeed, some argued against including <b>bool</b> is usually just an <b>int</b>. Indeed, some argued against including <b>bool</b>
in the C++ standard because of that. But by coding <b>bool</b> rather than <b>int</b>, in the C++ standard because of that. But by coding <b>bool</b> rather than <b>int</b>,
you tell your readers what your intent is. Same with <b>scoped_ptr</b>; by you tell your readers what your intent is. Same with <b>scoped_ptr</b>; by
using it you are signaling intent.</p> using it you are signaling intent.</p>
<p>It has been suggested that <b>scoped_ptr&lt;T&gt;</b> is equivalent to <b>std::auto_ptr&lt;T&gt; <p>It has been suggested that <b>scoped_ptr&lt;T&gt;</b> is equivalent to <b>std::auto_ptr&lt;T&gt;
const</b>. Ed Brey pointed out, however, that <b>reset</b> will not work on const</b>. Ed Brey pointed out, however, that <b>reset</b> will not work on
a <b>std::auto_ptr&lt;T&gt; const.</b></p> a <b>std::auto_ptr&lt;T&gt; const.</b></p>
<h2><a name="Handle/Body">Handle/Body</a> Idiom</h2> <h2><a name="Handle/Body">Handle/Body</a> Idiom</h2>
<p>One common usage of <b>scoped_ptr</b> is to implement a handle/body (also called <p>One common usage of <b>scoped_ptr</b> is to implement a handle/body (also called
pimpl) idiom which avoids exposing the body (implementation) in the header pimpl) idiom which avoids exposing the body (implementation) in the header
file.</p> file.</p>
<p>The <a href="example/scoped_ptr_example_test.cpp">scoped_ptr_example_test.cpp</a> <p>The <a href="example/scoped_ptr_example_test.cpp">scoped_ptr_example_test.cpp</a>
sample program includes a header file, <a href="example/scoped_ptr_example.hpp">scoped_ptr_example.hpp</a>, sample program includes a header file, <a href="example/scoped_ptr_example.hpp">scoped_ptr_example.hpp</a>,
which uses a <b>scoped_ptr&lt;&gt;</b> to an incomplete type to hide the which uses a <b>scoped_ptr&lt;&gt;</b> to an incomplete type to hide the
implementation. The instantiation of member functions which require a complete implementation. The instantiation of member functions which require a complete
type occurs in the <a href="example/scoped_ptr_example.cpp">scoped_ptr_example.cpp</a> type occurs in the <a href="example/scoped_ptr_example.cpp">scoped_ptr_example.cpp</a>
implementation file.</p> implementation file.</p>
<h2>Frequently Asked Questions</h2> <h2>Frequently Asked Questions</h2>
<p><b>Q</b>. Why doesn't <b>scoped_ptr</b> have a release() member?<br> <p><b>Q</b>. Why doesn't <b>scoped_ptr</b> have a release() member?<br>
<b>A</b>. When reading source code, it is valuable to be able to draw <b>A</b>. When reading source code, it is valuable to be able to draw
conclusions about program behavior based on the types being used. If <STRONG>scoped_ptr</STRONG> conclusions about program behavior based on the types being used. If <STRONG>scoped_ptr</STRONG>
had a release() member, it would become possible to transfer ownership of the had a release() member, it would become possible to transfer ownership of the
held pointer, weakening its role as a way of limiting resource lifetime to a held pointer, weakening its role as a way of limiting resource lifetime to a
given context. Use <STRONG>std::auto_ptr</STRONG> where transfer of ownership given context. Use <STRONG>std::auto_ptr</STRONG> where transfer of ownership
is required. (supplied by Dave Abrahams)</p> is required. (supplied by Dave Abrahams)</p>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan --> <p>$Date</p>
09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310" --></p> <p><small>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-2005 Peter Dimov. Distributed under the Boost Software License, Version
Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> </body>
</body>
</html> </html>

276
shared_array.htm
View File

@ -1,35 +1,35 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>shared_array</title> <title>shared_array</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#ffffff" text="#000000"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>shared_array class template</h1> width="277" align="middle" border="0">shared_array class template</h1>
<p>The <b>shared_array</b> class template stores a pointer to a dynamically <p>The <b>shared_array</b> class template stores a pointer to a dynamically
allocated array. (Dynamically allocated array are allocated with the C++ <b>new[]</b> allocated array. (Dynamically allocated array are allocated with the C++ <b>new[]</b>
expression.) The object pointed to is guaranteed to be deleted when the last <b>shared_array</b> expression.) The object pointed to is guaranteed to be deleted when the last <b>shared_array</b>
pointing to it is destroyed or reset.</p> pointing to it is destroyed or reset.</p>
<p>Every <b>shared_array</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> <p>Every <b>shared_array</b> meets the <b>CopyConstructible</b> and <b>Assignable</b>
requirements of the C++ Standard Library, and so can be used in standard requirements of the C++ Standard Library, and so can be used in standard
library containers. Comparison operators are supplied so that <b>shared_array</b> library containers. Comparison operators are supplied so that <b>shared_array</b>
works with the standard library's associative containers.</p> works with the standard library's associative containers.</p>
<p>Normally, a <b>shared_array</b> cannot correctly hold a pointer to an object <p>Normally, a <b>shared_array</b> cannot correctly hold a pointer to an object
that has been allocated with the non-array form of <STRONG>new</STRONG>. See <a href="shared_ptr.htm"> that has been allocated with the non-array form of <STRONG>new</STRONG>. See <a href="shared_ptr.htm">
<b>shared_ptr</b></a> for that usage.</p> <b>shared_ptr</b></a> for that usage.</p>
<p>Because the implementation uses reference counting, cycles of <b>shared_array</b> <p>Because the implementation uses reference counting, cycles of <b>shared_array</b>
instances will not be reclaimed. For example, if <b>main()</b> holds a <b>shared_array</b> instances will not be reclaimed. For example, if <b>main()</b> holds a <b>shared_array</b>
to <b>A</b>, which directly or indirectly holds a <b>shared_array</b> back to <b>A</b>, to <b>A</b>, which directly or indirectly holds a <b>shared_array</b> back to <b>A</b>,
<b>A</b>'s use count will be 2. Destruction of the original <b>shared_array</b> <b>A</b>'s use count will be 2. Destruction of the original <b>shared_array</b>
will leave <b>A</b> dangling with a use count of 1.</p> will leave <b>A</b> dangling with a use count of 1.</p>
<p>A <b>shared_ptr</b> to a <b>std::vector</b> is an alternative to a <b>shared_array</b> <p>A <b>shared_ptr</b> to a <b>std::vector</b> is an alternative to a <b>shared_array</b>
that is a bit heavier duty but far more flexible.</p> that is a bit heavier duty but far more flexible.</p>
<p>The class template is parameterized on <b>T</b>, the type of the object pointed <p>The class template is parameterized on <b>T</b>, the type of the object pointed
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements"> to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
common requirements</a>.</p> common requirements</a>.</p>
<h2>Synopsis</h2> <h2>Synopsis</h2>
<pre>namespace boost { <pre>namespace boost {
template&lt;class T&gt; class shared_array { template&lt;class T&gt; class shared_array {
@ -68,118 +68,116 @@
template&lt;class T&gt; void <a href="#free-swap">swap</a>(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b); // never throws template&lt;class T&gt; void <a href="#free-swap">swap</a>(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b); // never throws
}</pre> }</pre>
<h2>Members</h2> <h2>Members</h2>
<h3><a name="element_type">element_type</a></h3> <h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="constructors">constructors</a></h3> <h3><a name="constructors">constructors</a></h3>
<pre>explicit shared_array(T * p = 0);</pre> <pre>explicit shared_array(T * p = 0);</pre>
<p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b>, which must be a <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b>, which must be a
pointer to an array that was allocated via a C++ <b>new[]</b> expression or be pointer to an array that was allocated via a C++ <b>new[]</b> expression or be
0. Afterwards, the <a href="#use_count">use count</a> is 1 (even if p == 0; see <a href="#destructor"> 0. Afterwards, the <a href="#use_count">use count</a> is 1 (even if p == 0; see <a href="#destructor">
~shared_array</a>). The only exception which may be thrown by this ~shared_array</a>). The only exception which may be thrown by this
constructor is <b>std::bad_alloc</b>. If an exception is thrown, <b>delete[] p</b> constructor is <b>std::bad_alloc</b>. If an exception is thrown, <b>delete[] p</b>
is called.</p> is called.</p>
<pre>template&lt;class D&gt; shared_array(T * p, D d);</pre> <pre>template&lt;class D&gt; shared_array(T * p, D d);</pre>
<p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b> and of <b>d</b>. <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b> and of <b>d</b>.
Afterwards, the <a href="#use_count">use count</a> is 1. <b>D</b>'s copy Afterwards, the <a href="#use_count">use count</a> is 1. <b>D</b>'s copy
constructor and destructor must not throw. When the the time comes to delete constructor and destructor must not throw. When the the time comes to delete
the array pointed to by <b>p</b>, the object <b>d</b> is used in the statement <b>d(p)</b>. the array pointed to by <b>p</b>, the object <b>d</b> is used in the statement <b>d(p)</b>.
Invoking the object <b>d</b> with parameter <b>p</b> in this way must not Invoking the object <b>d</b> with parameter <b>p</b> in this way must not
throw. The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>. throw. The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
If an exception is thrown, <b>d(p)</b> is called.</p> If an exception is thrown, <b>d(p)</b> is called.</p>
<pre>shared_array(shared_array const &amp; r); // never throws</pre> <pre>shared_array(shared_array const &amp; r); // never throws</pre>
<p>Constructs a <b>shared_array</b>, as if by storing a copy of the pointer stored <p>Constructs a <b>shared_array</b>, as if by storing a copy of the pointer stored
in <b>r</b>. Afterwards, the <a href="#use_count">use count</a> for all copies in <b>r</b>. Afterwards, the <a href="#use_count">use count</a> for all copies
is 1 more than the initial use count.</p> is 1 more than the initial use count.</p>
<h3><a name="destructor">destructor</a></h3> <h3><a name="destructor">destructor</a></h3>
<pre>~shared_array(); // never throws</pre> <pre>~shared_array(); // never throws</pre>
<p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0, <p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0,
deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
a pointer with a value of 0 is harmless. <b>T</b> need not be a complete type. a pointer with a value of 0 is harmless. <b>T</b> need not be a complete type.
The guarantee that this does not throw exceptions depends on the requirement The guarantee that this does not throw exceptions depends on the requirement
that the deleted object's destructor does not throw exceptions. See the smart that the deleted object's destructor does not throw exceptions. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
<h3><a name="assignment">assignment</a></h3> <h3><a name="assignment">assignment</a></h3>
<pre>shared_array &amp; operator=(shared_array const &amp; r); // never throws</pre> <pre>shared_array &amp; operator=(shared_array const &amp; r); // never throws</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
then replaces this <b>shared_array</b> with the new one, destroying the then replaces this <b>shared_array</b> with the new one, destroying the
replaced object.</p> replaced object.</p>
<h3><a name="reset">reset</a></h3> <h3><a name="reset">reset</a></h3>
<pre>void reset(T * p = 0);</pre> <pre>void reset(T * p = 0);</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
then replaces this <b>shared_array</b> with the new one, destroying the then replaces this <b>shared_array</b> with the new one, destroying the
replaced object. The only exception which may be thrown is <b>std::bad_alloc</b>. replaced object. The only exception which may be thrown is <b>std::bad_alloc</b>.
If an exception is thrown, <b>delete[] p</b> is called.</p> If an exception is thrown, <b>delete[] p</b> is called.</p>
<pre>template&lt;class D&gt; void reset(T * p, D d);</pre> <pre>template&lt;class D&gt; void reset(T * p, D d);</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
then replaces this <b>shared_array</b> with the new one, destroying the then replaces this <b>shared_array</b> with the new one, destroying the
replaced object. <b>D</b>'s copy constructor must not throw. The only exception replaced object. <b>D</b>'s copy constructor must not throw. The only exception
which may be thrown is <b>std::bad_alloc</b>. If an exception is thrown, <b>d(p)</b> which may be thrown is <b>std::bad_alloc</b>. If an exception is thrown, <b>d(p)</b>
is called.</p> is called.</p>
<h3><a name="indexing">indexing</a></h3> <h3><a name="indexing">indexing</a></h3>
<pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre> <pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
<p>Returns a reference to element <b>i</b> of the array pointed to by the stored <p>Returns a reference to element <b>i</b> of the array pointed to by the stored
pointer. Behavior is undefined and almost certainly undesirable if the stored pointer. Behavior is undefined and almost certainly undesirable if the stored
pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
number of elements in the array.</p> number of elements in the array.</p>
<h3><a name="get">get</a></h3> <h3><a name="get">get</a></h3>
<pre>T * get() const; // never throws</pre> <pre>T * get() const; // never throws</pre>
<p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
<h3><a name="unique">unique</a></h3> <h3><a name="unique">unique</a></h3>
<pre>bool unique() const; // never throws</pre> <pre>bool unique() const; // never throws</pre>
<p>Returns true if no other <b>shared_array</b> is sharing ownership of the stored <p>Returns true if no other <b>shared_array</b> is sharing ownership of the stored
pointer, false otherwise. <b>T</b> need not be a complete type. See the smart pointer, false otherwise. <b>T</b> need not be a complete type. See the smart
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</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>
<p>Returns the number of <b>shared_array</b> objects sharing ownership of the <p>Returns the number of <b>shared_array</b> objects sharing ownership of the
stored pointer. <b>T</b> need not be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements"> stored pointer. <b>T</b> need not be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">
common requirements</a>.</p> common requirements</a>.</p>
<p>Because <b>use_count</b> is not necessarily efficient to implement for <p>Because <b>use_count</b> is not necessarily efficient to implement for
implementations of <b>shared_array</b> that do not use an explicit reference implementations of <b>shared_array</b> that do not use an explicit reference
count, it might be removed from some future version. Thus it should be used for count, it might be removed from some future version. Thus it should be used for
debugging purposes only, and not production code.</p> debugging purposes only, and not production code.</p>
<h3><a name="conversions">conversions</a></h3> <h3><a name="conversions">conversions</a></h3>
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent <p>Returns an unspecified value that, when used in boolean contexts, is equivalent
to <code>get() != 0</code>.</p> to <code>get() != 0</code>.</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>
<p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
requirements</a>.</p> requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2> <h2><a name="functions">Free Functions</a></h2>
<h3><a name="comparison">comparison</a></h3> <h3><a name="comparison">comparison</a></h3>
<pre>template&lt;class T&gt; <pre>template&lt;class T&gt;
bool operator==(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws bool operator==(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
template&lt;class T&gt; template&lt;class T&gt;
bool operator!=(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws bool operator!=(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
template&lt;class T&gt; template&lt;class T&gt;
bool operator&lt;(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws</pre> bool operator&lt;(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws</pre>
<p>Compares the stored pointers of the two smart pointers. <b>T</b> need not be a <p>Compares the stored pointers of the two smart pointers. <b>T</b> need not be a
complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
requirements</a>.</p> requirements</a>.</p>
<p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>shared_array</b> <p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>shared_array</b>
objects can be used in associative containers such as <b>std::map</b>. The objects can be used in associative containers such as <b>std::map</b>. The
implementation uses <b>std::less&lt;T *&gt;</b> to perform the comparison. This implementation uses <b>std::less&lt;T *&gt;</b> to perform the comparison. This
ensures that the comparison is handled correctly, since the standard mandates ensures that the comparison is handled correctly, since the standard mandates
that relational operations on pointers are unspecified (5.9 [expr.rel] that relational operations on pointers are unspecified (5.9 [expr.rel]
paragraph 2) but <b>std::less&lt;&gt;</b> on pointers is well-defined (20.3.3 paragraph 2) but <b>std::less&lt;&gt;</b> on pointers is well-defined (20.3.3
[lib.comparisons] paragraph 8).</p> [lib.comparisons] paragraph 8).</p>
<h3><a name="free-swap">swap</a></h3> <h3><a name="free-swap">swap</a></h3>
<pre>template&lt;class T&gt; <pre>template&lt;class T&gt;
void swap(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b) // never throws</pre> void swap(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b) // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>. <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p> Provided as an aid to generic programming.</p>
<hr> <hr>
<p>Revised <p>$Date</p>
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan --> <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310" --></p> Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version
<p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or </body>
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body>
</html> </html>

1216
shared_ptr.htm
View File

File diff suppressed because it is too large Load Diff

431
smart_ptr.htm
View File

@ -1,216 +1,221 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>Smart Pointers</title> <title>Smart Pointers</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#ffffff" text="#000000"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>Smart Pointers</h1> width="277" align="middle" border="0">Smart Pointers</h1>
<p><a href="#Introduction">Introduction</a><br> <p><a href="#Introduction">Introduction</a><br>
<a href="#common_requirements">Common Requirements</a><br> <a href="#common_requirements">Common Requirements</a><br>
<a href="#Exception_Safety">Exception Safety</a><br> <a href="#Exception_Safety">Exception Safety</a><br>
<a href="#Exception-specifications">Exception-specifications</a><br> <a href="#Exception-specifications">Exception-specifications</a><br>
<a href="#History">History and Acknowledgements</a><br> <a href="#History">History and Acknowledgements</a><br>
<a href="#References">References</a></p> <a href="#References">References</a></p>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>Smart pointers are objects which store pointers to dynamically allocated (heap) <p>Smart pointers are objects which store pointers to dynamically allocated (heap)
objects. They behave much like built-in C++ pointers except that they objects. They behave much like built-in C++ pointers except that they
automatically delete the object pointed to at the appropriate time. Smart automatically delete the object pointed to at the appropriate time. Smart
pointers are particularly useful in the face of exceptions as they ensure pointers are particularly useful in the face of exceptions as they ensure
proper destruction of dynamically allocated objects. They can also be used to proper destruction of dynamically allocated objects. They can also be used to
keep track of dynamically allocated objects shared by multiple owners.</p> keep track of dynamically allocated objects shared by multiple owners.</p>
<p>Conceptually, smart pointers are seen as owning the object pointed to, and thus <p>Conceptually, smart pointers are seen as owning the object pointed to, and thus
responsible for deletion of the object when it is no longer needed.</p> responsible for deletion of the object when it is no longer needed.</p>
<p>The smart pointer library provides six smart pointer class templates:</p> <p>The smart pointer library provides six smart pointer class templates:</p>
<div align="left"> <div align="left">
<table border="1" cellpadding="4" cellspacing="0"> <table border="1" cellpadding="4" cellspacing="0">
<tr> <tr>
<td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td> <td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td>
<td><a href="../../boost/scoped_ptr.hpp">&lt;boost/scoped_ptr.hpp&gt;</a></td> <td><a href="../../boost/scoped_ptr.hpp">&lt;boost/scoped_ptr.hpp&gt;</a></td>
<td>Simple sole ownership of single objects. Noncopyable.</td> <td>Simple sole ownership of single objects. Noncopyable.</td>
</tr> </tr>
<tr> <tr>
<td><a href="scoped_array.htm"><b>scoped_array</b></a></td> <td><a href="scoped_array.htm"><b>scoped_array</b></a></td>
<td><a href="../../boost/scoped_array.hpp">&lt;boost/scoped_array.hpp&gt;</a></td> <td><a href="../../boost/scoped_array.hpp">&lt;boost/scoped_array.hpp&gt;</a></td>
<td>Simple sole ownership of arrays. Noncopyable.</td> <td>Simple sole ownership of arrays. Noncopyable.</td>
</tr> </tr>
<tr> <tr>
<td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td> <td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
<td><a href="../../boost/shared_ptr.hpp">&lt;boost/shared_ptr.hpp&gt;</a></td> <td><a href="../../boost/shared_ptr.hpp">&lt;boost/shared_ptr.hpp&gt;</a></td>
<td>Object ownership shared among multiple pointers.</td> <td>Object ownership shared among multiple pointers.</td>
</tr> </tr>
<tr> <tr>
<td><a href="shared_array.htm"><b>shared_array</b></a></td> <td><a href="shared_array.htm"><b>shared_array</b></a></td>
<td><a href="../../boost/shared_array.hpp">&lt;boost/shared_array.hpp&gt;</a></td> <td><a href="../../boost/shared_array.hpp">&lt;boost/shared_array.hpp&gt;</a></td>
<td>Array ownership shared among multiple pointers.</td> <td>Array ownership shared among multiple pointers.</td>
</tr> </tr>
<tr> <tr>
<td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td> <td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td>
<td><a href="../../boost/weak_ptr.hpp">&lt;boost/weak_ptr.hpp&gt;</a></td> <td><a href="../../boost/weak_ptr.hpp">&lt;boost/weak_ptr.hpp&gt;</a></td>
<td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td> <td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td>
</tr> </tr>
<tr> <tr>
<td><a href="intrusive_ptr.html"><b>intrusive_ptr</b></a></td> <td><a href="intrusive_ptr.html"><b>intrusive_ptr</b></a></td>
<td><a href="../../boost/intrusive_ptr.hpp">&lt;boost/intrusive_ptr.hpp&gt;</a></td> <td><a href="../../boost/intrusive_ptr.hpp">&lt;boost/intrusive_ptr.hpp&gt;</a></td>
<td>Shared ownership of objects with an embedded reference count.</td> <td>Shared ownership of objects with an embedded reference count.</td>
</tr> </tr>
</table> </table>
</div> </div>
<p>These templates are designed to complement the <b>std::auto_ptr</b> template.</p> <p>These templates are designed to complement the <b>std::auto_ptr</b> template.</p>
<p>They are examples of the "resource acquisition is initialization" idiom <p>They are examples of the "resource acquisition is initialization" idiom
described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition, described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition,
Section 14.4, Resource Management.</p> Section 14.4, Resource Management.</p>
<p>Additionally, the smart pointer library provides efficient factory functions <p>Additionally, the smart pointer library provides efficient factory functions
for creating smart pointer objects:</p> for creating smart pointer objects:</p>
<div align="left"> <div align="left">
<table border="1" cellpadding="4" cellspacing="0"> <table border="1" cellpadding="4" cellspacing="0">
<tr> <tr>
<td><a href="make_shared.html"><b>make_shared and allocate_shared for objects</b></a></td> <td><a href="make_shared.html"><b>make_shared, allocate_shared</b></a> for objects</td>
<td><a href="../../boost/make_shared.hpp">&lt;boost/make_shared.hpp&gt;</a></td> <td><a href="../../boost/make_shared.hpp">&lt;boost/make_shared.hpp&gt;</a></td>
<td>Efficient creation of <code>shared_ptr</code> objects.</td> <td>Efficient creation of <code>shared_ptr</code> objects.</td>
</tr> </tr>
<tr> <tr>
<td><a href="make_shared_array.html"><b>make_shared and allocate_shared for arrays</b></a></td> <td><a href="make_shared_array.html"><b>make_shared, allocate_shared</b></a> for arrays</td>
<td><a href="../../boost/make_shared.hpp">&lt;boost/make_shared.hpp&gt;</a></td> <td><a href="../../boost/make_shared.hpp">&lt;boost/make_shared.hpp&gt;</a></td>
<td>Efficient creation of <code>shared_ptr</code> arrays.</td> <td>Efficient creation of <code>shared_ptr</code> arrays.</td>
</tr> </tr>
<tr> <tr>
<td><a href="make_unique.html"><b>make_unique</b></a></td> <td><a href="make_unique.html"><b>make_unique</b></a></td>
<td><a href="../../boost/make_unique.hpp">&lt;boost/make_unique.hpp&gt;</a></td> <td><a href="../../boost/make_unique.hpp">&lt;boost/make_unique.hpp&gt;</a></td>
<td>Creation of <code>unique_ptr</code> objects and arrays.</td> <td>Creation of <code>unique_ptr</code> objects and arrays.</td>
</tr> </tr>
</table> </table>
</div> </div>
<p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is <p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
provided to verify correct operation.</p> provided to verify correct operation.</p>
<p>A page on <a href="compatibility.htm">compatibility</a> with older versions of <p>A page on <a href="compatibility.htm">compatibility</a> with older versions of
the Boost smart pointer library describes some of the changes since earlier the Boost smart pointer library describes some of the changes since earlier
versions of the smart pointer implementation.</p> versions of the smart pointer implementation.</p>
<p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of interest <p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of interest
to those curious about performance issues.</p> to those curious about performance issues.</p>
<P>A page on <A href="sp_techniques.html">smart pointer programming techniques</A> lists <P>A page on <A href="sp_techniques.html">smart pointer programming techniques</A> lists
some advanced applications of <code>shared_ptr</code> and <code>weak_ptr</code>.</P> some advanced applications of <code>shared_ptr</code> and <code>weak_ptr</code>.</P>
<h2><a name="common_requirements">Common Requirements</a></h2> <h2><a name="common_requirements">Common Requirements</a></h2>
<p>These smart pointer class templates have a template parameter, <b>T</b>, which <p>These smart pointer class templates have a template parameter, <b>T</b>, which
specifies the type of the object pointed to by the smart pointer. The behavior specifies the type of the object pointed to by the smart pointer. The behavior
of the smart pointer templates is undefined if the destructor or <b>operator delete</b> of the smart pointer templates is undefined if the destructor or <b>operator delete</b>
for objects of type <b>T</b> throw exceptions.</p> for objects of type <b>T</b> throw exceptions.</p>
<p><b>T</b> may be an incomplete type at the point of smart pointer declaration. <p><b>T</b> may be an incomplete type at the point of smart pointer declaration.
Unless otherwise specified, it is required that <b>T</b> be a complete type at Unless otherwise specified, it is required that <b>T</b> be a complete type at
points of smart pointer instantiation. Implementations are required to diagnose points of smart pointer instantiation. Implementations are required to diagnose
(treat as an error) all violations of this requirement, including deletion of (treat as an error) all violations of this requirement, including deletion of
an incomplete type. See the description of the <a href="../utility/utility.htm#checked_delete"> an incomplete type. See the description of the <a href="../utility/utility.htm#checked_delete">
<b>checked_delete</b></a> function template.</p> <b>checked_delete</b></a> function template.</p>
<P>Note that <STRONG>shared_ptr</STRONG> does not have this restriction, as most of <P>Note that <STRONG>shared_ptr</STRONG> does not have this restriction, as most of
its member functions do not require <STRONG>T</STRONG> to be a complete type.</P> its member functions do not require <STRONG>T</STRONG> to be a complete type.</P>
<h3>Rationale</h3> <h3>Rationale</h3>
<p>The requirements on <b>T</b> are carefully crafted to maximize safety yet allow <p>The requirements on <b>T</b> are carefully crafted to maximize safety yet allow
handle-body (also called pimpl) and similar idioms. In these idioms a smart handle-body (also called pimpl) and similar idioms. In these idioms a smart
pointer may appear in translation units where <b>T</b> is an incomplete type. pointer may appear in translation units where <b>T</b> is an incomplete type.
This separates interface from implementation and hides implementation from This separates interface from implementation and hides implementation from
translation units which merely use the interface. Examples described in the translation units which merely use the interface. Examples described in the
documentation for specific smart pointers illustrate use of smart pointers in documentation for specific smart pointers illustrate use of smart pointers in
these idioms.</p> these idioms.</p>
<p>Note that <b>scoped_ptr</b> requires that <b>T</b> be a complete type at <p>Note that <b>scoped_ptr</b> requires that <b>T</b> be a complete type at
destruction time, but <b>shared_ptr</b> does not.</p> destruction time, but <b>shared_ptr</b> does not.</p>
<h2><a name="Exception_Safety">Exception Safety</a></h2> <h2><a name="Exception_Safety">Exception Safety</a></h2>
<p>Several functions in these smart pointer classes are specified as having "no <p>Several functions in these smart pointer classes are specified as having "no
effect" or "no effect except such-and-such" if an exception is thrown. This effect" or "no effect except such-and-such" if an exception is thrown. This
means that when an exception is thrown by an object of one of these classes, means that when an exception is thrown by an object of one of these classes,
the entire program state remains the same as it was prior to the function call the entire program state remains the same as it was prior to the function call
which resulted in the exception being thrown. This amounts to a guarantee that which resulted in the exception being thrown. This amounts to a guarantee that
there are no detectable side effects. Other functions never throw exceptions. there are no detectable side effects. Other functions never throw exceptions.
The only exception ever thrown by functions which do throw (assuming <b>T</b> meets The only exception ever thrown by functions which do throw (assuming <b>T</b> meets
the <a href="#common_requirements">common requirements</a>) is <b>std::bad_alloc</b>, the <a href="#common_requirements">common requirements</a>) is <b>std::bad_alloc</b>,
and that is thrown only by functions which are explicitly documented as and that is thrown only by functions which are explicitly documented as
possibly throwing <b>std::bad_alloc</b>.</p> possibly throwing <b>std::bad_alloc</b>.</p>
<h2><a name="Exception-specifications">Exception-specifications</a></h2> <h2><a name="Exception-specifications">Exception-specifications</a></h2>
<p>Exception-specifications are not used; see <a href="http://www.boost.org/more/lib_guide.htm#Exception-specification"> <p>Exception-specifications are not used; see <a href="http://www.boost.org/more/lib_guide.htm#Exception-specification">
exception-specification rationale</a>.</p> exception-specification rationale</a>.</p>
<p>All the smart pointer templates contain member functions which can never throw <p>All the smart pointer templates contain member functions which can never throw
exceptions, because they neither throw exceptions themselves nor call other exceptions, because they neither throw exceptions themselves nor call other
functions which may throw exceptions. These members are indicated by a comment: <code> functions which may throw exceptions. These members are indicated by a comment: <code>
// never throws</code>. // never throws</code>.
</p> </p>
<p>Functions which destroy objects of the pointed to type are prohibited from <p>Functions which destroy objects of the pointed to type are prohibited from
throwing exceptions by the <a href="#common_requirements">common requirements</a>.</p> throwing exceptions by the <a href="#common_requirements">common requirements</a>.</p>
<h2><a name="History">History</a> and Acknowledgements</h2> <h2><a name="History">History</a> and Acknowledgements</h2>
<p>January 2014. Glen Fernandes confined the overloads of <b>make_shared</b> <p>February 2014. Glen Fernandes updated overloads of <b>make_shared</b> and
and <b>allocate_shared</b> for arrays to the specification in <b>allocate_shared</b> to conform to the specification in C++ standard paper
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html">N3870</a> <a href="#D&amp;F-14">[D&amp;F-14]</a>, and implemented <b>make_unique</b> for
and implemented <b>make_unique</b> for arrays and objects.</p> arrays and objects. Peter Dimov and Glen Fernandes updated the scalar and
<p>November 2012. Glen Fernandes provided implementations of <b>make_shared</b> array implementations, respectively, to resolve C++ standard library defect
and <b>allocate_shared</b> for arrays. They achieve a single allocation for an 2070.</p>
array that can be initialized with constructor arguments or initializer lists <p>November 2012. Glen Fernandes provided implementations of <b>make_shared</b>
as well as overloads for default initialization and no value initialization. and <b>allocate_shared</b> for arrays. They achieve a single allocation for an
See the <a href="make_shared_array.html">make_shared and allocate_shared for array that can be initialized with constructor arguments or initializer lists
arrays</a> page for more information.</p> as well as overloads for default initialization and no value initialization.
<p>January 2002. Peter Dimov reworked all four classes, adding features, fixing See the <a href="make_shared_array.html">make_shared and allocate_shared for
bugs, and splitting them into four separate headers, and added <b>weak_ptr</b>. arrays</a> page for more information.</p>
See the <a href="compatibility.htm">compatibility</a> page for a summary of the <p>January 2002. Peter Dimov reworked all four classes, adding features, fixing
changes.</p> bugs, and splitting them into four separate headers, and added <b>weak_ptr</b>.
<p>May 2001. Vladimir Prus suggested requiring a complete type on destruction. See the <a href="compatibility.htm">compatibility</a> page for a summary of the
Refinement evolved in discussions including Dave Abrahams, Greg Colvin, Beman changes.</p>
Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, Shankar Sai, and <p>May 2001. Vladimir Prus suggested requiring a complete type on destruction.
others.</p> Refinement evolved in discussions including Dave Abrahams, Greg Colvin, Beman
<p>November 1999. Darin Adler provided <b>operator ==</b>, <b>operator !=</b>, and <b>std::swap</b> Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, Shankar Sai, and
and <b>std::less</b> specializations for shared types.</p> others.</p>
<p>September 1999. Luis Coelho provided <b>shared_ptr::swap</b> and <b>shared_array::swap</b></p> <p>November 1999. Darin Adler provided <b>operator ==</b>, <b>operator !=</b>, and <b>std::swap</b>
<p>May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a and <b>std::less</b> specializations for shared types.</p>
number of suggestions resulting in numerous improvements.</p> <p>September 1999. Luis Coelho provided <b>shared_ptr::swap</b> and <b>shared_array::swap</b></p>
<p>October 1998. Beman Dawes proposed reviving the original semantics under the <p>May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a
names <b>safe_ptr</b> and <b>counted_ptr</b>, meeting of Per Andersson, Matt number of suggestions resulting in numerous improvements.</p>
Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar K&uuml;hl, <p>October 1998. Beman Dawes proposed reviving the original semantics under the
Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new names <b>safe_ptr</b> and <b>counted_ptr</b>, meeting of Per Andersson, Matt
class names were finalized, it was decided that there was no need to exactly Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar K&uuml;hl,
follow the <b>std::auto_ptr</b> interface, and various function signatures and Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new
semantics were finalized.</p> class names were finalized, it was decided that there was no need to exactly
<p>Over the next three months, several implementations were considered for <b>shared_ptr</b>, follow the <b>std::auto_ptr</b> interface, and various function signatures and
and discussed on the <a href="http://www.boost.org">boost.org</a> mailing list. semantics were finalized.</p>
The implementation questions revolved around the reference count which must be <p>Over the next three months, several implementations were considered for <b>shared_ptr</b>,
kept, either attached to the pointed to object, or detached elsewhere. Each of and discussed on the <a href="http://www.boost.org">boost.org</a> mailing list.
those variants have themselves two major variants: The implementation questions revolved around the reference count which must be
<ul> kept, either attached to the pointed to object, or detached elsewhere. Each of
<li> those variants have themselves two major variants:
Direct detached: the shared_ptr contains a pointer to the object, and a pointer <ul>
to the count. <li>
<li> Direct detached: the shared_ptr contains a pointer to the object, and a pointer
Indirect detached: the shared_ptr contains a pointer to a helper object, which to the count.
in turn contains a pointer to the object and the count. <li>
<li> Indirect detached: the shared_ptr contains a pointer to a helper object, which
Embedded attached: the count is a member of the object pointed to. in turn contains a pointer to the object and the count.
<li> <li>
Placement attached: the count is attached via operator new manipulations.</li> Embedded attached: the count is a member of the object pointed to.
</ul> <li>
<p>Each implementation technique has advantages and disadvantages. We went so far Placement attached: the count is attached via operator new manipulations.</li>
as to run various timings of the direct and indirect approaches, and found that </ul>
at least on Intel Pentium chips there was very little measurable difference. <p>Each implementation technique has advantages and disadvantages. We went so far
Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar as to run various timings of the direct and indirect approaches, and found that
K&uuml;hl suggested an elegant partial template specialization technique to allow at least on Intel Pentium chips there was very little measurable difference.
users to choose which implementation they preferred, and that was also Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar
experimented with.</p> K&uuml;hl suggested an elegant partial template specialization technique to allow
<p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage users to choose which implementation they preferred, and that was also
users", and in the end we choose to supply only the direct implementation.</p> experimented with.</p>
<p>Summer, 1994. Greg Colvin proposed to the C++ Standards Committee classes named <b>auto_ptr</b> <p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage
and <b>counted_ptr</b> which were very similar to what we now call <b>scoped_ptr</b> users", and in the end we choose to supply only the direct implementation.</p>
and <b>shared_ptr</b>. <a href="#Col-94">[Col-94]</a> In one of the very few <p>Summer, 1994. Greg Colvin proposed to the C++ Standards Committee classes named <b>auto_ptr</b>
cases where the Library Working Group's recommendations were not followed by and <b>counted_ptr</b> which were very similar to what we now call <b>scoped_ptr</b>
the full committee, <b>counted_ptr</b> was rejected and surprising and <b>shared_ptr</b>. <a href="#Col-94">[Col-94]</a> In one of the very few
transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p> cases where the Library Working Group's recommendations were not followed by
<h2><a name="References">References</a></h2> the full committee, <b>counted_ptr</b> was rejected and surprising
<p>[<a name="Col-94">Col-94</a>] Gregory Colvin, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1994/N0555.pdf"> transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p>
Exception Safe Smart Pointers</a>, C++ committee document 94-168/N0555, <h2><a name="References">References</a></h2>
July, 1994.</p> <p>[<a name="D&amp;F-14">D&amp;F-14</a>] Peter Dimov &amp; Glen Fernandes, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html">
<p>[<a name="E&amp;D-94">E&amp;D-94</a>] John R. Ellis &amp; David L. Detlefs, <a href="http://www.usenix.org/publications/library/proceedings/c++94/full_papers/ellis.a"> Extending make_shared to Support Arrays, Revision 1</a>, C++ committee document N3870,
Safe, Efficient Garbage Collection for C++</a>, Usenix Proceedings, January, 2014.</p>
February, 1994. This paper includes an extensive discussion of weak pointers <p>[<a name="Col-94">Col-94</a>] Gregory Colvin, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1994/N0555.pdf">
and an extensive bibliography.</p> Exception Safe Smart Pointers</a>, C++ committee document 94-168/N0555,
<hr> July, 1994.</p>
<p>$Date$</p> <p>[<a name="E&amp;D-94">E&amp;D-94</a>] John R. Ellis &amp; David L. Detlefs, <a href="http://www.usenix.org/publications/library/proceedings/c++94/full_papers/ellis.a">
<p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. Safe, Efficient Garbage Collection for C++</a>, Usenix Proceedings,
Distributed under the Boost Software License, Version 1.0. See accompanying February, 1994. This paper includes an extensive discussion of weak pointers
file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at and an extensive bibliography.</p>
<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> <hr>
</body> <p>$Date$</p>
<p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Distributed under the Boost Software License, Version 1.0. See accompanying
file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at
<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body>
</html> </html>

11
smarttests.htm
View File

@ -7,9 +7,9 @@
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body bgcolor="#FFFFFF"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" WIDTH="277" HEIGHT="86">Smart Pointer Timings</h1> <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" border="0">Smart Pointer Timings</h1>
<p>In late January 2000, Mark Borgerding put forward a suggestion to boost for <p>In late January 2000, Mark Borgerding put forward a suggestion to boost for
a new design of smart pointer whereby an intrusive doubly linked list is used a new design of smart pointer whereby an intrusive doubly linked list is used
@ -533,9 +533,8 @@ Gavin Collings,
spreads its information as in the case of linked pointer.</li> spreads its information as in the case of linked pointer.</li>
</ul> </ul>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->19 August 2001<!--webbot bot="Timestamp" endspan i-checksum="14767" --> <p>$Date$</p>
</p> <p>&copy; Copyright Gavin Collings 2000. Permission to copy, use, modify, sell
<p><EFBFBD> Copyright Gavin Collings 2000. Permission to copy, use, modify, sell
and distribute this document is granted provided this copyright notice appears in all and distribute this document is granted provided this copyright notice appears in all
copies. This document is provided &quot;as is&quot; without express or implied warranty, copies. This document is provided &quot;as is&quot; without express or implied warranty,
and with no claim as to its suitability for any purpose.</p> and with no claim as to its suitability for any purpose.</p>

574
sp_techniques.html
View File

@ -1,67 +1,67 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>Smart Pointer Programming Techniques</title> <title>Smart Pointer Programming Techniques</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body text="#000000" bgColor="#ffffff"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>Smart Pointer Programming Techniques</h1> width="277" align="middle" border="0">Smart Pointer Programming Techniques</h1>
<p><A href="#incomplete">Using incomplete classes for implementation hiding</A><br> <p><A href="#incomplete">Using incomplete classes for implementation hiding</A><br>
<A href="#pimpl">The "Pimpl" idiom</A><br> <A href="#pimpl">The "Pimpl" idiom</A><br>
<A href="#abstract">Using abstract classes for implementation hiding</A><br> <A href="#abstract">Using abstract classes for implementation hiding</A><br>
<A href="#preventing_delete">Preventing <code>delete px.get()</code></A><br> <A href="#preventing_delete">Preventing <code>delete px.get()</code></A><br>
<A href="#array">Using a <code>shared_ptr</code> to hold a pointer to an array</A><br> <A href="#array">Using a <code>shared_ptr</code> to hold a pointer to an array</A><br>
<A href="#encapsulation">Encapsulating allocation details, wrapping factory <A href="#encapsulation">Encapsulating allocation details, wrapping factory
functions</A><br> functions</A><br>
<A href="#static">Using a <code>shared_ptr</code> to hold a pointer to a statically <A href="#static">Using a <code>shared_ptr</code> to hold a pointer to a statically
allocated object</A><br> allocated object</A><br>
<A href="#com">Using a <code>shared_ptr</code> to hold a pointer to a COM object</A><br> <A href="#com">Using a <code>shared_ptr</code> to hold a pointer to a COM object</A><br>
<A href="#intrusive">Using a <code>shared_ptr</code> to hold a pointer to an object <A href="#intrusive">Using a <code>shared_ptr</code> to hold a pointer to an object
with an embedded reference count</A><br> with an embedded reference count</A><br>
<A href="#another_sp">Using a <code>shared_ptr</code> to hold another shared <A href="#another_sp">Using a <code>shared_ptr</code> to hold another shared
ownership smart pointer</A><br> ownership smart pointer</A><br>
<A href="#from_raw">Obtaining a <code>shared_ptr</code> from a raw pointer</A><br> <A href="#from_raw">Obtaining a <code>shared_ptr</code> from a raw pointer</A><br>
<A href="#in_constructor">Obtaining a <code>shared_ptr</code> (<code>weak_ptr</code>) <A href="#in_constructor">Obtaining a <code>shared_ptr</code> (<code>weak_ptr</code>)
to <code>this</code> in a constructor</A><br> to <code>this</code> in a constructor</A><br>
<A href="#from_this">Obtaining a <code>shared_ptr</code> to <code>this</code></A><br> <A href="#from_this">Obtaining a <code>shared_ptr</code> to <code>this</code></A><br>
<A href="#handle">Using <code>shared_ptr</code> as a smart counted handle</A><br> <A href="#handle">Using <code>shared_ptr</code> as a smart counted handle</A><br>
<A href="#on_block_exit">Using <code>shared_ptr</code> to execute code on block <A href="#on_block_exit">Using <code>shared_ptr</code> to execute code on block
exit</A><br> exit</A><br>
<A href="#pvoid">Using <code>shared_ptr&lt;void&gt;</code> to hold an arbitrary <A href="#pvoid">Using <code>shared_ptr&lt;void&gt;</code> to hold an arbitrary
object</A><br> object</A><br>
<A href="#extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code> <A href="#extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code>
instances</A><br> instances</A><br>
<A href="#as_lock">Using <code>shared_ptr</code> as a CopyConstructible mutex lock</A><br> <A href="#as_lock">Using <code>shared_ptr</code> as a CopyConstructible mutex lock</A><br>
<A href="#wrapper">Using <code>shared_ptr</code> to wrap member function calls</A><br> <A href="#wrapper">Using <code>shared_ptr</code> to wrap member function calls</A><br>
<A href="#delayed">Delayed deallocation</A><br> <A href="#delayed">Delayed deallocation</A><br>
<A href="#weak_without_shared">Weak pointers to objects not managed by a <code>shared_ptr</code></A><br> <A href="#weak_without_shared">Weak pointers to objects not managed by a <code>shared_ptr</code></A><br>
</p> </p>
<h2><A name="incomplete">Using incomplete classes for implementation hiding</A></h2> <h2><A name="incomplete">Using incomplete classes for implementation hiding</A></h2>
<p>A proven technique (that works in C, too) for separating interface from <p>A proven technique (that works in C, too) for separating interface from
implementation is to use a pointer to an incomplete class as an opaque handle:</p> implementation is to use a pointer to an incomplete class as an opaque handle:</p>
<pre>class FILE; <pre>class FILE;
FILE * fopen(char const * name, char const * mode); FILE * fopen(char const * name, char const * mode);
void fread(FILE * f, void * data, size_t size); void fread(FILE * f, void * data, size_t size);
void fclose(FILE * f); void fclose(FILE * f);
</pre> </pre>
<p>It is possible to express the above interface using <code>shared_ptr</code>, <p>It is possible to express the above interface using <code>shared_ptr</code>,
eliminating the need to manually call <code>fclose</code>:</p> eliminating the need to manually call <code>fclose</code>:</p>
<pre>class FILE; <pre>class FILE;
shared_ptr&lt;FILE&gt; fopen(char const * name, char const * mode); shared_ptr&lt;FILE&gt; fopen(char const * name, char const * mode);
void fread(shared_ptr&lt;FILE&gt; f, void * data, size_t size); void fread(shared_ptr&lt;FILE&gt; f, void * data, size_t size);
</pre> </pre>
<p>This technique relies on <code>shared_ptr</code>'s ability to execute a custom <p>This technique relies on <code>shared_ptr</code>'s ability to execute a custom
deleter, eliminating the explicit call to <code>fclose</code>, and on the fact deleter, eliminating the explicit call to <code>fclose</code>, and on the fact
that <code>shared_ptr&lt;X&gt;</code> can be copied and destroyed when <code>X</code> that <code>shared_ptr&lt;X&gt;</code> can be copied and destroyed when <code>X</code>
is incomplete.</p> is incomplete.</p>
<h2><A name="pimpl">The "Pimpl" idiom</A></h2> <h2><A name="pimpl">The "Pimpl" idiom</A></h2>
<p>A C++ specific variation of the incomplete class pattern is the "Pimpl" idiom. <p>A C++ specific variation of the incomplete class pattern is the "Pimpl" idiom.
The incomplete class is not exposed to the user; it is hidden behind a The incomplete class is not exposed to the user; it is hidden behind a
forwarding facade. <code>shared_ptr</code> can be used to implement a "Pimpl":</p> forwarding facade. <code>shared_ptr</code> can be used to implement a "Pimpl":</p>
<pre>// file.hpp: <pre>// file.hpp:
class file class file
{ {
@ -79,7 +79,7 @@ public:
void read(void * data, size_t size); void read(void * data, size_t size);
}; };
</pre> </pre>
<pre>// file.cpp: <pre>// file.cpp:
#include "file.hpp" #include "file.hpp"
@ -108,17 +108,17 @@ void file::read(void * data, size_t size)
pimpl_-&gt;read(data, size); pimpl_-&gt;read(data, size);
} }
</pre> </pre>
<p>The key thing to note here is that the compiler-generated copy constructor, <p>The key thing to note here is that the compiler-generated copy constructor,
assignment operator, and destructor all have a sensible meaning. As a result, <code> assignment operator, and destructor all have a sensible meaning. As a result, <code>
file</code> is <code>CopyConstructible</code> and <code>Assignable</code>, file</code> is <code>CopyConstructible</code> and <code>Assignable</code>,
allowing its use in standard containers.</p> allowing its use in standard containers.</p>
<h2><A name="abstract">Using abstract classes for implementation hiding</A></h2> <h2><A name="abstract">Using abstract classes for implementation hiding</A></h2>
<p>Another widely used C++ idiom for separating inteface and implementation is to <p>Another widely used C++ idiom for separating inteface and implementation is to
use abstract base classes and factory functions. The abstract classes are use abstract base classes and factory functions. The abstract classes are
sometimes called "interfaces" and the pattern is known as "interface-based sometimes called "interfaces" and the pattern is known as "interface-based
programming". Again, <code>shared_ptr</code> can be used as the return type of programming". Again, <code>shared_ptr</code> can be used as the return type of
the factory functions:</p> the factory functions:</p>
<pre>// X.hpp: <pre>// X.hpp:
class X class X
{ {
@ -134,7 +134,7 @@ protected:
shared_ptr&lt;X&gt; createX(); shared_ptr&lt;X&gt; createX();
</pre> </pre>
<pre>-- X.cpp: <pre>-- X.cpp:
class X_impl: public X class X_impl: public X
{ {
@ -162,18 +162,18 @@ shared_ptr&lt;X&gt; createX()
return px; return px;
} }
</pre> </pre>
<p>A key property of shared_ptr is that the allocation, construction, deallocation, <p>A key property of shared_ptr is that the allocation, construction, deallocation,
and destruction details are captured at the point of construction, inside the and destruction details are captured at the point of construction, inside the
factory function. Note the protected and nonvirtual destructor in the example factory function. Note the protected and nonvirtual destructor in the example
above. The client code cannot, and does not need to, delete a pointer to <code>X</code>; above. The client code cannot, and does not need to, delete a pointer to <code>X</code>;
the <code>shared_ptr&lt;X&gt;</code> instance returned from <code>createX</code> the <code>shared_ptr&lt;X&gt;</code> instance returned from <code>createX</code>
will correctly call <code>~X_impl</code>.</p> will correctly call <code>~X_impl</code>.</p>
<h2><A name="preventing_delete">Preventing <code>delete px.get()</code></A></h2> <h2><A name="preventing_delete">Preventing <code>delete px.get()</code></A></h2>
<p>It is often desirable to prevent client code from deleting a pointer that is <p>It is often desirable to prevent client code from deleting a pointer that is
being managed by <code>shared_ptr</code>. The previous technique showed one being managed by <code>shared_ptr</code>. The previous technique showed one
possible approach, using a protected destructor. Another alternative is to use possible approach, using a protected destructor. Another alternative is to use
a private deleter:</p> a private deleter:</p>
<pre>class X <pre>class X
{ {
private: private:
@ -198,48 +198,48 @@ public:
} }
}; };
</pre> </pre>
<h2><A name="array">Using a <code>shared_ptr</code> to hold a pointer to an array</A></h2> <h2><A name="array">Using a <code>shared_ptr</code> to hold a pointer to an array</A></h2>
<p>A <code>shared_ptr</code> can be used to hold a pointer to an array allocated <p>A <code>shared_ptr</code> can be used to hold a pointer to an array allocated
with <code>new[]</code>:</p> with <code>new[]</code>:</p>
<pre>shared_ptr&lt;X&gt; px(new X[1], <A href="../utility/checked_delete.html" >checked_array_deleter</A>&lt;X&gt;()); <pre>shared_ptr&lt;X&gt; px(new X[1], <A href="../utility/checked_delete.html" >checked_array_deleter</A>&lt;X&gt;());
</pre> </pre>
<p>Note, however, that <code><A href="shared_array.htm">shared_array</A></code> is <p>Note, however, that <code><A href="shared_array.htm">shared_array</A></code> is
often preferable, if this is an option. It has an array-specific interface, often preferable, if this is an option. It has an array-specific interface,
without <code>operator*</code> and <code>operator-&gt;</code>, and does not without <code>operator*</code> and <code>operator-&gt;</code>, and does not
allow pointer conversions.</p> allow pointer conversions.</p>
<h2><A name="encapsulation">Encapsulating allocation details, wrapping factory <h2><A name="encapsulation">Encapsulating allocation details, wrapping factory
functions</A></h2> functions</A></h2>
<p><code>shared_ptr</code> can be used in creating C++ wrappers over existing C <p><code>shared_ptr</code> can be used in creating C++ wrappers over existing C
style library interfaces that return raw pointers from their factory functions style library interfaces that return raw pointers from their factory functions
to encapsulate allocation details. As an example, consider this interface, to encapsulate allocation details. As an example, consider this interface,
where <code>CreateX</code> might allocate <code>X</code> from its own private where <code>CreateX</code> might allocate <code>X</code> from its own private
heap, <code>~X</code> may be inaccessible, or <code>X</code> may be incomplete:</p> heap, <code>~X</code> may be inaccessible, or <code>X</code> may be incomplete:</p>
<pre>X * CreateX(); <pre>X * CreateX();
void DestroyX(X *); void DestroyX(X *);
</pre> </pre>
<p>The only way to reliably destroy a pointer returned by <code>CreateX</code> is <p>The only way to reliably destroy a pointer returned by <code>CreateX</code> is
to call <code>DestroyX</code>.</p> to call <code>DestroyX</code>.</p>
<P>Here is how a <code>shared_ptr</code>-based wrapper may look like:</P> <P>Here is how a <code>shared_ptr</code>-based wrapper may look like:</P>
<pre>shared_ptr&lt;X&gt; createX() <pre>shared_ptr&lt;X&gt; createX()
{ {
shared_ptr&lt;X&gt; px(CreateX(), DestroyX); shared_ptr&lt;X&gt; px(CreateX(), DestroyX);
return px; return px;
} }
</pre> </pre>
<p>Client code that calls <code>createX</code> still does not need to know how the <p>Client code that calls <code>createX</code> still does not need to know how the
object has been allocated, but now the destruction is automatic.</p> object has been allocated, but now the destruction is automatic.</p>
<h2><A name="static">Using a <code>shared_ptr</code> to hold a pointer to a statically <h2><A name="static">Using a <code>shared_ptr</code> to hold a pointer to a statically
allocated object</A></h2> allocated object</A></h2>
<p>Sometimes it is desirable to create a <code>shared_ptr</code> to an already <p>Sometimes it is desirable to create a <code>shared_ptr</code> to an already
existing object, so that the <code>shared_ptr</code> does not attempt to existing object, so that the <code>shared_ptr</code> does not attempt to
destroy the object when there are no more references left. As an example, the destroy the object when there are no more references left. As an example, the
factory function:</p> factory function:</p>
<pre>shared_ptr&lt;X&gt; createX(); <pre>shared_ptr&lt;X&gt; createX();
</pre> </pre>
<p>in certain situations may need to return a pointer to a statically allocated <code>X</code> <p>in certain situations may need to return a pointer to a statically allocated <code>X</code>
instance.</p> instance.</p>
<P>The solution is to use a custom deleter that does nothing:</P> <P>The solution is to use a custom deleter that does nothing:</P>
<pre>struct null_deleter <pre>struct null_deleter
{ {
void operator()(void const *) const void operator()(void const *) const
{ {
@ -254,33 +254,33 @@ shared_ptr&lt;X&gt; createX()
return px; return px;
} }
</pre> </pre>
<p>The same technique works for any object known to outlive the pointer.</p> <p>The same technique works for any object known to outlive the pointer.</p>
<h2><A name="com">Using a <code>shared_ptr</code> to hold a pointer to a COM Object</A></h2> <h2><A name="com">Using a <code>shared_ptr</code> to hold a pointer to a COM Object</A></h2>
<p>Background: COM objects have an embedded reference count and two member <p>Background: COM objects have an embedded reference count and two member
functions that manipulate it. <code>AddRef()</code> increments the count. <code>Release()</code> functions that manipulate it. <code>AddRef()</code> increments the count. <code>Release()</code>
decrements the count and destroys itself when the count drops to zero.</p> decrements the count and destroys itself when the count drops to zero.</p>
<P>It is possible to hold a pointer to a COM object in a <code>shared_ptr</code>:</P> <P>It is possible to hold a pointer to a COM object in a <code>shared_ptr</code>:</P>
<pre>shared_ptr&lt;IWhatever&gt; make_shared_from_COM(IWhatever * p) <pre>shared_ptr&lt;IWhatever&gt; make_shared_from_COM(IWhatever * p)
{ {
p-&gt;AddRef(); p-&gt;AddRef();
shared_ptr&lt;IWhatever&gt; pw(p, <A href="../bind/mem_fn.html" >mem_fn</A>(&amp;IWhatever::Release)); shared_ptr&lt;IWhatever&gt; pw(p, <A href="../bind/mem_fn.html" >mem_fn</A>(&amp;IWhatever::Release));
return pw; return pw;
} }
</pre> </pre>
<p>Note, however, that <code>shared_ptr</code> copies created from <code>pw</code> will <p>Note, however, that <code>shared_ptr</code> copies created from <code>pw</code> will
not "register" in the embedded count of the COM object; they will share the not "register" in the embedded count of the COM object; they will share the
single reference created in <code>make_shared_from_COM</code>. Weak pointers single reference created in <code>make_shared_from_COM</code>. Weak pointers
created from <code>pw</code> will be invalidated when the last <code>shared_ptr</code> created from <code>pw</code> will be invalidated when the last <code>shared_ptr</code>
is destroyed, regardless of whether the COM object itself is still alive.</p> is destroyed, regardless of whether the COM object itself is still alive.</p>
<P>As <A href="../bind/mem_fn.html#Q3">explained</A> in the <code>mem_fn</code> documentation, <P>As <A href="../bind/mem_fn.html#Q3">explained</A> in the <code>mem_fn</code> documentation,
you need to <A href="../bind/mem_fn.html#stdcall">#define you need to <A href="../bind/mem_fn.html#stdcall">#define
BOOST_MEM_FN_ENABLE_STDCALL</A> first.</P> BOOST_MEM_FN_ENABLE_STDCALL</A> first.</P>
<h2><A name="intrusive">Using a <code>shared_ptr</code> to hold a pointer to an object <h2><A name="intrusive">Using a <code>shared_ptr</code> to hold a pointer to an object
with an embedded reference count</A></h2> with an embedded reference count</A></h2>
<p>This is a generalization of the above technique. The example assumes that the <p>This is a generalization of the above technique. The example assumes that the
object implements the two functions required by <code><A href="intrusive_ptr.html">intrusive_ptr</A></code>, object implements the two functions required by <code><A href="intrusive_ptr.html">intrusive_ptr</A></code>,
<code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code>:</p> <code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code>:</p>
<pre>template&lt;class T&gt; struct intrusive_deleter <pre>template&lt;class T&gt; struct intrusive_deleter
{ {
void operator()(T * p) void operator()(T * p)
{ {
@ -295,15 +295,15 @@ shared_ptr&lt;X&gt; make_shared_from_intrusive(X * p)
return px; return px;
} }
</pre> </pre>
<h2><A name="another_sp">Using a <code>shared_ptr</code> to hold another shared <h2><A name="another_sp">Using a <code>shared_ptr</code> to hold another shared
ownership smart pointer</A></h2> ownership smart pointer</A></h2>
<p>One of the design goals of <code>shared_ptr</code> is to be used in library <p>One of the design goals of <code>shared_ptr</code> is to be used in library
interfaces. It is possible to encounter a situation where a library takes a <code>shared_ptr</code> interfaces. It is possible to encounter a situation where a library takes a <code>shared_ptr</code>
argument, but the object at hand is being managed by a different reference argument, but the object at hand is being managed by a different reference
counted or linked smart pointer.</p> counted or linked smart pointer.</p>
<P>It is possible to exploit <code>shared_ptr</code>'s custom deleter feature to <P>It is possible to exploit <code>shared_ptr</code>'s custom deleter feature to
wrap this existing smart pointer behind a <code>shared_ptr</code> facade:</P> wrap this existing smart pointer behind a <code>shared_ptr</code> facade:</P>
<pre>template&lt;class P&gt; struct smart_pointer_deleter <pre>template&lt;class P&gt; struct smart_pointer_deleter
{ {
private: private:
@ -332,17 +332,17 @@ shared_ptr&lt;X&gt; make_shared_from_another(another_ptr&lt;X&gt; qx)
return px; return px;
} }
</pre> </pre>
<p>One subtle point is that deleters are not allowed to throw exceptions, and the <p>One subtle point is that deleters are not allowed to throw exceptions, and the
above example as written assumes that <code>p_.reset()</code> doesn't throw. If above example as written assumes that <code>p_.reset()</code> doesn't throw. If
this is not the case, <code>p_.reset()</code> should be wrapped in a <code>try {} this is not the case, <code>p_.reset()</code> should be wrapped in a <code>try {}
catch(...) {}</code> block that ignores exceptions. In the (usually catch(...) {}</code> block that ignores exceptions. In the (usually
unlikely) event when an exception is thrown and ignored, <code>p_</code> will unlikely) event when an exception is thrown and ignored, <code>p_</code> will
be released when the lifetime of the deleter ends. This happens when all be released when the lifetime of the deleter ends. This happens when all
references, including weak pointers, are destroyed or reset.</p> references, including weak pointers, are destroyed or reset.</p>
<P>Another twist is that it is possible, given the above <code>shared_ptr</code> instance, <P>Another twist is that it is possible, given the above <code>shared_ptr</code> instance,
to recover the original smart pointer, using <code><A href="shared_ptr.htm#get_deleter"> to recover the original smart pointer, using <code><A href="shared_ptr.htm#get_deleter">
get_deleter</A></code>:</P> get_deleter</A></code>:</P>
<pre>void extract_another_from_shared(shared_ptr&lt;X&gt; px) <pre>void extract_another_from_shared(shared_ptr&lt;X&gt; px)
{ {
typedef smart_pointer_deleter&lt; another_ptr&lt;X&gt; &gt; deleter; typedef smart_pointer_deleter&lt; another_ptr&lt;X&gt; &gt; deleter;
@ -356,37 +356,37 @@ shared_ptr&lt;X&gt; make_shared_from_another(another_ptr&lt;X&gt; qx)
} }
} }
</pre> </pre>
<h2><A name="from_raw">Obtaining a <code>shared_ptr</code> from a raw pointer</A></h2> <h2><A name="from_raw">Obtaining a <code>shared_ptr</code> from a raw pointer</A></h2>
<p>Sometimes it is necessary to obtain a <code>shared_ptr</code> given a raw <p>Sometimes it is necessary to obtain a <code>shared_ptr</code> given a raw
pointer to an object that is already managed by another <code>shared_ptr</code> pointer to an object that is already managed by another <code>shared_ptr</code>
instance. Example:</p> instance. Example:</p>
<pre>void f(X * p) <pre>void f(X * p)
{ {
shared_ptr&lt;X&gt; px(<i>???</i>); shared_ptr&lt;X&gt; px(<i>???</i>);
} }
</pre> </pre>
<p>Inside <code>f</code>, we'd like to create a <code>shared_ptr</code> to <code>*p</code>.</p> <p>Inside <code>f</code>, we'd like to create a <code>shared_ptr</code> to <code>*p</code>.</p>
<P>In the general case, this problem has no solution. One approach is to modify <code>f</code> <P>In the general case, this problem has no solution. One approach is to modify <code>f</code>
to take a <code>shared_ptr</code>, if possible:</P> to take a <code>shared_ptr</code>, if possible:</P>
<pre>void f(shared_ptr&lt;X&gt; px); <pre>void f(shared_ptr&lt;X&gt; px);
</pre> </pre>
<p>The same transformation can be used for nonvirtual member functions, to convert <p>The same transformation can be used for nonvirtual member functions, to convert
the implicit <code>this</code>:</p> the implicit <code>this</code>:</p>
<pre>void X::f(int m); <pre>void X::f(int m);
</pre> </pre>
<p>would become a free function with a <code>shared_ptr</code> first argument:</p> <p>would become a free function with a <code>shared_ptr</code> first argument:</p>
<pre>void f(shared_ptr&lt;X&gt; this_, int m); <pre>void f(shared_ptr&lt;X&gt; this_, int m);
</pre> </pre>
<p>If <code>f</code> cannot be changed, but <code>X</code> uses intrusive counting, <p>If <code>f</code> cannot be changed, but <code>X</code> uses intrusive counting,
use <code><A href="#intrusive">make_shared_from_intrusive</A></code> described use <code><A href="#intrusive">make_shared_from_intrusive</A></code> described
above. Or, if it's known that the <code>shared_ptr</code> created in <code>f</code> above. Or, if it's known that the <code>shared_ptr</code> created in <code>f</code>
will never outlive the object, use <A href="#static">a null deleter</A>.</p> will never outlive the object, use <A href="#static">a null deleter</A>.</p>
<h2><A name="in_constructor">Obtaining a <code>shared_ptr</code> (<code>weak_ptr</code>) <h2><A name="in_constructor">Obtaining a <code>shared_ptr</code> (<code>weak_ptr</code>)
to <code>this</code> in a constructor</A></h2> to <code>this</code> in a constructor</A></h2>
<p>Some designs require objects to register themselves on construction with a <p>Some designs require objects to register themselves on construction with a
central authority. When the registration routines take a shared_ptr, this leads central authority. When the registration routines take a shared_ptr, this leads
to the question how could a constructor obtain a shared_ptr to this:</p> to the question how could a constructor obtain a shared_ptr to this:</p>
<pre>class X <pre>class X
{ {
public: public:
@ -396,19 +396,19 @@ public:
} }
}; };
</pre> </pre>
<p>In the general case, the problem cannot be solved. The <code>X</code> instance <p>In the general case, the problem cannot be solved. The <code>X</code> instance
being constructed can be an automatic variable or a static variable; it can be being constructed can be an automatic variable or a static variable; it can be
created on the heap:</p> created on the heap:</p>
<pre>shared_ptr&lt;X&gt; px(new X);</pre> <pre>shared_ptr&lt;X&gt; px(new X);</pre>
<P>but at construction time, <code>px</code> does not exist yet, and it is <P>but at construction time, <code>px</code> does not exist yet, and it is
impossible to create another <code>shared_ptr</code> instance that shares impossible to create another <code>shared_ptr</code> instance that shares
ownership with it.</P> ownership with it.</P>
<P>Depending on context, if the inner <code>shared_ptr</code> <code>this_</code> doesn't <P>Depending on context, if the inner <code>shared_ptr</code> <code>this_</code> doesn't
need to keep the object alive, use a <code>null_deleter</code> as explained <A href="#static"> need to keep the object alive, use a <code>null_deleter</code> as explained <A href="#static">
here</A> and <A href="#weak_without_shared">here</A>. If <code>X</code> is here</A> and <A href="#weak_without_shared">here</A>. If <code>X</code> is
supposed to always live on the heap, and be managed by a <code>shared_ptr</code>, supposed to always live on the heap, and be managed by a <code>shared_ptr</code>,
use a static factory function:</P> use a static factory function:</P>
<pre>class X <pre>class X
{ {
private: private:
@ -424,13 +424,13 @@ public:
} }
}; };
</pre> </pre>
<h2><A name="from_this">Obtaining a <code>shared_ptr</code> to <code>this</code></A></h2> <h2><A name="from_this">Obtaining a <code>shared_ptr</code> to <code>this</code></A></h2>
<p>Sometimes it is needed to obtain a <code>shared_ptr</code> from <code>this</code> <p>Sometimes it is needed to obtain a <code>shared_ptr</code> from <code>this</code>
in a virtual member function under the assumption that <code>this</code> is in a virtual member function under the assumption that <code>this</code> is
already managed by a <code>shared_ptr</code>. The transformations <A href="#from_raw"> already managed by a <code>shared_ptr</code>. The transformations <A href="#from_raw">
described in the previous technique</A> cannot be applied.</p> described in the previous technique</A> cannot be applied.</p>
<P>A typical example:</P> <P>A typical example:</P>
<pre>class X <pre>class X
{ {
public: public:
@ -469,8 +469,8 @@ public:
} }
}; };
</pre> </pre>
<p>The solution is to keep a weak pointer to <code>this</code> as a member in <code>impl</code>:</p> <p>The solution is to keep a weak pointer to <code>this</code> as a member in <code>impl</code>:</p>
<pre>class impl: public X, public Y <pre>class impl: public X, public Y
{ {
private: private:
@ -499,10 +499,10 @@ public:
} }
}; };
</pre> </pre>
<p>The library now includes a helper class template <code><A href="enable_shared_from_this.html"> <p>The library now includes a helper class template <code><A href="enable_shared_from_this.html">
enable_shared_from_this</A></code> that can be used to encapsulate the enable_shared_from_this</A></code> that can be used to encapsulate the
solution:</p> solution:</p>
<pre>class impl: public X, public Y, public enable_shared_from_this&lt;impl&gt; <pre>class impl: public X, public Y, public enable_shared_from_this&lt;impl&gt;
{ {
public: public:
@ -519,19 +519,19 @@ public:
} }
} }
</pre> </pre>
<p>Note that you no longer need to manually initialize the <code>weak_ptr</code> member <p>Note that you no longer need to manually initialize the <code>weak_ptr</code> member
in <code><A href="enable_shared_from_this.html">enable_shared_from_this</A></code>. in <code><A href="enable_shared_from_this.html">enable_shared_from_this</A></code>.
Constructing a <code>shared_ptr</code> to <code>impl</code> takes care of that.</p> Constructing a <code>shared_ptr</code> to <code>impl</code> takes care of that.</p>
<h2><A name="handle">Using <code>shared_ptr</code> as a smart counted handle</A></h2> <h2><A name="handle">Using <code>shared_ptr</code> as a smart counted handle</A></h2>
<p>Some library interfaces use opaque handles, a variation of the <A href="#incomplete"> <p>Some library interfaces use opaque handles, a variation of the <A href="#incomplete">
incomplete class technique</A> described above. An example:</p> incomplete class technique</A> described above. An example:</p>
<pre>typedef void * HANDLE; <pre>typedef void * HANDLE;
HANDLE CreateProcess(); HANDLE CreateProcess();
void CloseHandle(HANDLE); void CloseHandle(HANDLE);
</pre> </pre>
<p>Instead of a raw pointer, it is possible to use <code>shared_ptr</code> as the <p>Instead of a raw pointer, it is possible to use <code>shared_ptr</code> as the
handle and get reference counting and automatic resource management for free:</p> handle and get reference counting and automatic resource management for free:</p>
<pre>typedef shared_ptr&lt;void&gt; handle; <pre>typedef shared_ptr&lt;void&gt; handle;
handle createProcess() handle createProcess()
{ {
@ -539,42 +539,42 @@ handle createProcess()
return pv; return pv;
} }
</pre> </pre>
<h2><A name="on_block_exit">Using <code>shared_ptr</code> to execute code on block exit</A></h2> <h2><A name="on_block_exit">Using <code>shared_ptr</code> to execute code on block exit</A></h2>
<p><code>shared_ptr&lt;void&gt;</code> can automatically execute cleanup code when <p><code>shared_ptr&lt;void&gt;</code> can automatically execute cleanup code when
control leaves a scope.</p> control leaves a scope.</p>
<UL> <UL>
<LI> <LI>
Executing <code>f(p)</code>, where <code>p</code> is a pointer:</LI></UL> Executing <code>f(p)</code>, where <code>p</code> is a pointer:</LI></UL>
<pre> shared_ptr&lt;void&gt; guard(p, f); <pre> shared_ptr&lt;void&gt; guard(p, f);
</pre> </pre>
<UL> <UL>
<LI> <LI>
Executing arbitrary code: <code>f(x, y)</code>:</LI></UL> Executing arbitrary code: <code>f(x, y)</code>:</LI></UL>
<pre> shared_ptr&lt;void&gt; guard(static_cast&lt;void*&gt;(0), <A href="../bind/bind.html" >bind</A>(f, x, y)); <pre> shared_ptr&lt;void&gt; guard(static_cast&lt;void*&gt;(0), <A href="../bind/bind.html" >bind</A>(f, x, y));
</pre> </pre>
<P>For a more thorough treatment, see the article "Simplify Your Exception-Safe <P>For a more thorough treatment, see the article "Simplify Your Exception-Safe
Code" by Andrei Alexandrescu and Petru Marginean, available online at <A href="http://www.cuj.com/experts/1812/alexandr.htm?topic=experts"> Code" by Andrei Alexandrescu and Petru Marginean, available online at <A href="http://www.cuj.com/experts/1812/alexandr.htm?topic=experts">
http://www.cuj.com/experts/1812/alexandr.htm?topic=experts</A>.</P> http://www.cuj.com/experts/1812/alexandr.htm?topic=experts</A>.</P>
<h2><A name="pvoid">Using <code>shared_ptr&lt;void&gt;</code> to hold an arbitrary <h2><A name="pvoid">Using <code>shared_ptr&lt;void&gt;</code> to hold an arbitrary
object</A></h2> object</A></h2>
<p><code>shared_ptr&lt;void&gt;</code> can act as a generic object pointer similar <p><code>shared_ptr&lt;void&gt;</code> can act as a generic object pointer similar
to <code>void*</code>. When a <code>shared_ptr&lt;void&gt;</code> instance to <code>void*</code>. When a <code>shared_ptr&lt;void&gt;</code> instance
constructed as:</p> constructed as:</p>
<pre> shared_ptr&lt;void&gt; pv(new X); <pre> shared_ptr&lt;void&gt; pv(new X);
</pre> </pre>
<p>is destroyed, it will correctly dispose of the <code>X</code> object by <p>is destroyed, it will correctly dispose of the <code>X</code> object by
executing <code>~X</code>.</p> executing <code>~X</code>.</p>
<p>This propery can be used in much the same manner as a raw <code>void*</code> is <p>This propery can be used in much the same manner as a raw <code>void*</code> is
used to temporarily strip type information from an object pointer. A <code>shared_ptr&lt;void&gt;</code> used to temporarily strip type information from an object pointer. A <code>shared_ptr&lt;void&gt;</code>
can later be cast back to the correct type by using <code><A href="shared_ptr.htm#static_pointer_cast"> can later be cast back to the correct type by using <code><A href="shared_ptr.htm#static_pointer_cast">
static_pointer_cast</A></code>.</p> static_pointer_cast</A></code>.</p>
<h2><A name="extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code> <h2><A name="extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code>
instances</A></h2> instances</A></h2>
<p><code>shared_ptr</code> and <code>weak_ptr</code> support <code>operator&lt;</code> <p><code>shared_ptr</code> and <code>weak_ptr</code> support <code>operator&lt;</code>
comparisons required by standard associative containers such as <code>std::map</code>. comparisons required by standard associative containers such as <code>std::map</code>.
This can be used to non-intrusively associate arbitrary data with objects This can be used to non-intrusively associate arbitrary data with objects
managed by <code>shared_ptr</code>:</p> managed by <code>shared_ptr</code>:</p>
<pre>typedef int Data; <pre>typedef int Data;
std::map&lt; shared_ptr&lt;void&gt;, Data &gt; userData; std::map&lt; shared_ptr&lt;void&gt;, Data &gt; userData;
// or std::map&lt; weak_ptr&lt;void&gt;, Data &gt; userData; to not affect the lifetime // or std::map&lt; weak_ptr&lt;void&gt;, Data &gt; userData; to not affect the lifetime
@ -585,11 +585,11 @@ shared_ptr&lt;int&gt; pi(new int(3));
userData[px] = 42; userData[px] = 42;
userData[pi] = 91; userData[pi] = 91;
</pre> </pre>
<h2><A name="as_lock">Using <code>shared_ptr</code> as a CopyConstructible mutex lock</A></h2> <h2><A name="as_lock">Using <code>shared_ptr</code> as a CopyConstructible mutex lock</A></h2>
<p>Sometimes it's necessary to return a mutex lock from a function, and a <p>Sometimes it's necessary to return a mutex lock from a function, and a
noncopyable lock cannot be returned by value. It is possible to use <code>shared_ptr</code> noncopyable lock cannot be returned by value. It is possible to use <code>shared_ptr</code>
as a mutex lock:</p> as a mutex lock:</p>
<pre>class mutex <pre>class mutex
{ {
public: public:
@ -603,9 +603,9 @@ shared_ptr&lt;mutex&gt; lock(mutex &amp; m)
return shared_ptr&lt;mutex&gt;(&amp;m, mem_fn(&amp;mutex::unlock)); return shared_ptr&lt;mutex&gt;(&amp;m, mem_fn(&amp;mutex::unlock));
} }
</pre> </pre>
<p>Better yet, the <code>shared_ptr</code> instance acting as a lock can be <p>Better yet, the <code>shared_ptr</code> instance acting as a lock can be
encapsulated in a dedicated <code>shared_lock</code> class:</p> encapsulated in a dedicated <code>shared_lock</code> class:</p>
<pre>class shared_lock <pre>class shared_lock
{ {
private: private:
@ -616,17 +616,17 @@ public:
template&lt;class Mutex&gt; explicit shared_lock(Mutex &amp; m): pv((m.lock(), &amp;m), mem_fn(&amp;Mutex::unlock)) {} template&lt;class Mutex&gt; explicit shared_lock(Mutex &amp; m): pv((m.lock(), &amp;m), mem_fn(&amp;Mutex::unlock)) {}
}; };
</pre> </pre>
<p><code>shared_lock</code> can now be used as:</p> <p><code>shared_lock</code> can now be used as:</p>
<pre> shared_lock lock(m); <pre> shared_lock lock(m);
</pre> </pre>
<p>Note that <code>shared_lock</code> is not templated on the mutex type, thanks to <code> <p>Note that <code>shared_lock</code> is not templated on the mutex type, thanks to <code>
shared_ptr&lt;void&gt;</code>'s ability to hide type information.</p> shared_ptr&lt;void&gt;</code>'s ability to hide type information.</p>
<h2><A name="wrapper">Using <code>shared_ptr</code> to wrap member function calls</A></h2> <h2><A name="wrapper">Using <code>shared_ptr</code> to wrap member function calls</A></h2>
<p><code>shared_ptr</code> implements the ownership semantics required from the <code>Wrap</code>/<code>CallProxy</code> <p><code>shared_ptr</code> implements the ownership semantics required from the <code>Wrap</code>/<code>CallProxy</code>
scheme described in Bjarne Stroustrup's article "Wrapping C++ Member Function scheme described in Bjarne Stroustrup's article "Wrapping C++ Member Function
Calls" (available online at <A href="http://www.stroustrup.com/wrapper.pdf">http://www.stroustrup.com/wrapper.pdf</A>). Calls" (available online at <A href="http://www.stroustrup.com/wrapper.pdf">http://www.stroustrup.com/wrapper.pdf</A>).
An implementation is given below:</p> An implementation is given below:</p>
<pre>template&lt;class T&gt; class pointer <pre>template&lt;class T&gt; class pointer
{ {
private: private:
@ -669,10 +669,10 @@ int main()
px-&gt;g(); px-&gt;g();
} }
</pre> </pre>
<h2><A name="delayed">Delayed deallocation</A></h2> <h2><A name="delayed">Delayed deallocation</A></h2>
<p>In some situations, a single <code>px.reset()</code> can trigger an expensive <p>In some situations, a single <code>px.reset()</code> can trigger an expensive
deallocation in a performance-critical region:</p> deallocation in a performance-critical region:</p>
<pre>class X; // ~X is expensive <pre>class X; // ~X is expensive
class Y class Y
{ {
@ -686,10 +686,10 @@ public:
} }
}; };
</pre> </pre>
<p>The solution is to postpone the potential deallocation by moving <code>px</code> <p>The solution is to postpone the potential deallocation by moving <code>px</code>
to a dedicated free list that can be periodically emptied when performance and to a dedicated free list that can be periodically emptied when performance and
response times are not an issue:</p> response times are not an issue:</p>
<pre>vector&lt; shared_ptr&lt;void&gt; &gt; free_list; <pre>vector&lt; shared_ptr&lt;void&gt; &gt; free_list;
class Y class Y
{ {
@ -706,9 +706,9 @@ public:
// periodically invoke free_list.clear() when convenient // periodically invoke free_list.clear() when convenient
</pre> </pre>
<p>Another variation is to move the free list logic to the construction point by <p>Another variation is to move the free list logic to the construction point by
using a delayed deleter:</p> using a delayed deleter:</p>
<pre>struct delayed_deleter <pre>struct delayed_deleter
{ {
template&lt;class T&gt; void operator()(T * p) template&lt;class T&gt; void operator()(T * p)
{ {
@ -723,9 +723,9 @@ public:
} }
}; };
</pre> </pre>
<h2><A name="weak_without_shared">Weak pointers to objects not managed by a <code>shared_ptr</code></A></h2> <h2><A name="weak_without_shared">Weak pointers to objects not managed by a <code>shared_ptr</code></A></h2>
<p>Make the object hold a <code>shared_ptr</code> to itself, using a <code>null_deleter</code>:</p> <p>Make the object hold a <code>shared_ptr</code> to itself, using a <code>null_deleter</code>:</p>
<pre>class X <pre>class X
{ {
private: private:
@ -748,18 +748,18 @@ public:
X &amp; operator=(X const &amp; rhs) X &amp; operator=(X const &amp; rhs)
{ {
i_ = rhs.i_; i_ = rhs.i_;
} }
weak_ptr&lt;X&gt; get_weak_ptr() const { return this_; } weak_ptr&lt;X&gt; get_weak_ptr() const { return this_; }
}; };
</pre> </pre>
<p>When the object's lifetime ends, <code>X::this_</code> will be destroyed, and <p>When the object's lifetime ends, <code>X::this_</code> will be destroyed, and
all weak pointers will automatically expire.</p> all weak pointers will automatically expire.</p>
<hr> <hr>
<p>$Date$</p> <p>$Date$</p>
<p><small>Copyright <EFBFBD> 2003 Peter Dimov. Distributed under the Boost Software License, Version <p><small>Copyright &copy; 2003 Peter Dimov. Distributed under the Boost Software License, Version
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body> </body>
</html> </html>

332
weak_ptr.htm
View File

@ -1,42 +1,42 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>weak_ptr</title> <title>weak_ptr</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head> </head>
<body text="#000000" bgColor="#ffffff"> <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
border="0"></A>weak_ptr class template</h1> width="277" align="middle" border="0">weak_ptr class template</h1>
<p><A href="#Introduction">Introduction</A><br> <p><A href="#Introduction">Introduction</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>
<A href="#FAQ">Frequently Asked Questions</A> <A href="#FAQ">Frequently Asked Questions</A>
</p> </p>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<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 member function <STRONG><A href="#lock"> 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 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> 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>weak_ptr::lock</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 <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
standard library's associative containers.</p> standard library's associative containers.</p>
<P><STRONG>weak_ptr</STRONG> operations never throw&nbsp;exceptions.</P> <P><STRONG>weak_ptr</STRONG> operations never throw&nbsp;exceptions.</P>
<p>The class template is parameterized on <b>T</b>, the type of the object pointed <p>The class template is parameterized on <b>T</b>, the type of the object pointed
to.</p> to.</p>
<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a <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 very limited subset of operations since accessing its stored pointer is often
dangerous in multithreaded programs, and sometimes unsafe even within a single dangerous in multithreaded programs, and sometimes unsafe even within a single
thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b> 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 has a <b>get</b> member function that returns a raw pointer, and consider this
innocent piece of code:</P> innocent piece of code:</P>
<pre>shared_ptr&lt;int&gt; p(new int(5)); <pre>shared_ptr&lt;int&gt; p(new int(5));
weak_ptr&lt;int&gt; q(p); weak_ptr&lt;int&gt; q(p);
// some time later // some time later
@ -46,12 +46,12 @@ if(int * r = q.get())
// use *r // use *r
} }
</pre> </pre>
<P>Imagine that after the <STRONG>if</STRONG>, but immediately before <STRONG>r</STRONG> <P>Imagine that after the <STRONG>if</STRONG>, but immediately before <STRONG>r</STRONG>
is used, another thread executes the statement <code>p.reset()</code>. Now <STRONG>r</STRONG> is used, another thread executes the statement <code>p.reset()</code>. Now <STRONG>r</STRONG>
is a dangling pointer.</P> is a dangling pointer.</P>
<P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG> <P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
from <STRONG>q</STRONG>:</P> from <STRONG>q</STRONG>:</P>
<pre>shared_ptr&lt;int&gt; p(new int(5)); <pre>shared_ptr&lt;int&gt; p(new int(5));
weak_ptr&lt;int&gt; q(p); weak_ptr&lt;int&gt; q(p);
// some time later // some time later
@ -61,13 +61,13 @@ if(shared_ptr&lt;int&gt; r = q.<A href="#lock" >lock</A>())
// use *r // use *r
} }
</pre> </pre>
<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. By obtaining 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 a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it
against destruction.</p> against destruction.</p>
<h2><a name="Synopsis">Synopsis</a></h2> <h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost { <pre>namespace boost {
template&lt;class T&gt; class weak_ptr { template&lt;class T&gt; class weak_ptr {
@ -101,119 +101,119 @@ if(shared_ptr&lt;int&gt; r = q.<A href="#lock" >lock</A>())
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);
} }
</pre> </pre>
<h2><a name="Members">Members</a></h2> <h2><a name="Members">Members</a></h2>
<h3><a name="element_type">element_type</a></h3> <h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<blockquote> <blockquote>
<p>Provides the type of the template parameter T.</p> <p>Provides the type of the template parameter T.</p>
</blockquote> </blockquote>
<h3><a name="default-constructor">constructors</a></h3> <h3><a name="constructors">constructors</a></h3>
<pre>weak_ptr();</pre> <pre><a name="default-constructor">weak_ptr();</a></pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Constructs an <EM>empty</EM> <b>weak_ptr</b>.</p> <p><b>Effects:</b> Constructs an <EM>empty</EM> <b>weak_ptr</b>.</p>
<p><b>Postconditions:</b> <code>use_count() == 0</code>.</p> <p><b>Postconditions:</b> <code>use_count() == 0</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote><a name="constructors"></a> </blockquote>
<pre>template&lt;class Y&gt; weak_ptr</A>(shared_ptr&lt;Y&gt; const &amp; r); <pre>template&lt;class Y&gt; weak_ptr(shared_ptr&lt;Y&gt; const &amp; r);
weak_ptr(weak_ptr const &amp; r); weak_ptr(weak_ptr const &amp; r);
template&lt;class Y&gt; weak_ptr(weak_ptr&lt;Y&gt; const &amp; r);</pre> template&lt;class Y&gt; weak_ptr(weak_ptr&lt;Y&gt; const &amp; r);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> If <STRONG>r</STRONG> is <EM>empty</EM>, constructs an <EM>empty</EM> <p><b>Effects:</b> If <STRONG>r</STRONG> is <EM>empty</EM>, constructs an <EM>empty</EM>
<STRONG>weak_ptr</STRONG>; otherwise, constructs a <b>weak_ptr</b> that <EM>shares <STRONG>weak_ptr</STRONG>; otherwise, constructs a <b>weak_ptr</b> that <EM>shares
ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the
pointer stored in <b>r</b>.</p> pointer stored in <b>r</b>.</p>
<p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p> <p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h3><a name="destructor">destructor</a></h3> <h3><a name="destructor">destructor</a></h3>
<pre>~weak_ptr();</pre> <pre>~weak_ptr();</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object <P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object
its stored pointer points to.</P> its stored pointer points to.</P>
<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>
<pre>weak_ptr &amp; operator=(weak_ptr const &amp; r); <pre>weak_ptr &amp; operator=(weak_ptr const &amp; r);
template&lt;class Y&gt; weak_ptr &amp; operator=(weak_ptr&lt;Y&gt; const &amp; r); template&lt;class Y&gt; weak_ptr &amp; operator=(weak_ptr&lt;Y&gt; const &amp; r);
template&lt;class Y&gt; weak_ptr &amp; operator=(shared_ptr&lt;Y&gt; const &amp; r);</pre> template&lt;class Y&gt; weak_ptr &amp; operator=(shared_ptr&lt;Y&gt; const &amp; r);</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P> <P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
<P><B>Throws:</B> nothing.</P> <P><B>Throws:</B> nothing.</P>
<P><B>Notes:</B> The implementation is free to meet the effects (and the implied <P><B>Notes:</B> The implementation is free to meet the effects (and the implied
guarantees) via different means, without creating a temporary.</P> guarantees) via different means, without creating a temporary.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<h3><a name="use_count">use_count</a></h3> <h3><a name="use_count">use_count</a></h3>
<pre>long use_count() const;</pre> <pre>long use_count() const;</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> 0 if <STRONG>*this</STRONG> is <EM>empty</EM>; otherwise, the <p><b>Returns:</b> 0 if <STRONG>*this</STRONG> is <EM>empty</EM>; otherwise, the
number of <b>shared_ptr</b> objects that <EM>share ownership</EM> with <STRONG>*this</STRONG>.</p> number of <b>shared_ptr</b> objects that <EM>share ownership</EM> with <STRONG>*this</STRONG>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only <P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only
for debugging and testing purposes, not for production code.</P> for debugging and testing purposes, not for production code.</P>
</blockquote> </blockquote>
<h3><a name="expired">expired</a></h3> <h3><a name="expired">expired</a></h3>
<pre>bool expired() const;</pre> <pre>bool expired() const;</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> <code>use_count() == 0</code>.</p> <p><b>Returns:</b> <code>use_count() == 0</code>.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P> <P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
</blockquote> </blockquote>
<h3><a name="lock">lock</a></h3> <h3><a name="lock">lock</a></h3>
<pre>shared_ptr&lt;T&gt; lock() const;</pre> <pre>shared_ptr&lt;T&gt; lock() const;</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<P><B>Returns:</B> <code>expired()? shared_ptr&lt;T&gt;(): shared_ptr&lt;T&gt;(*this)</code>.</P> <P><B>Returns:</B> <code>expired()? shared_ptr&lt;T&gt;(): shared_ptr&lt;T&gt;(*this)</code>.</P>
<P><B>Throws:</B> nothing.</P> <P><B>Throws:</B> nothing.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<h3><a name="reset">reset</a></h3> <h3><a name="reset">reset</a></h3>
<pre>void reset();</pre> <pre>void reset();</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P> <P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
</BLOCKQUOTE> </BLOCKQUOTE>
<h3><a name="swap">swap</a></h3> <h3><a name="swap">swap</a></h3>
<pre>void swap(weak_ptr &amp; b);</pre> <pre>void swap(weak_ptr &amp; b);</pre>
<blockquote> <blockquote>
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p> <p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
</blockquote> </blockquote>
<h2><a name="functions">Free Functions</a></h2> <h2><a name="functions">Free Functions</a></h2>
<h3><a name="comparison">comparison</a></h3> <h3><a name="comparison">comparison</a></h3>
<pre>template&lt;class T, class U&gt; <pre>template&lt;class T, class U&gt;
bool operator&lt;(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b);</pre> bool operator&lt;(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b);</pre>
<blockquote> <blockquote>
<p><b>Returns:</b> an unspecified value such that</p> <p><b>Returns:</b> an unspecified value such that</p>
<UL> <UL>
<LI> <LI>
<b>operator&lt;</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code> <b>operator&lt;</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
of the C++ standard; of the C++ standard;
<LI> <LI>
under the equivalence relation defined by <STRONG>operator&lt;</STRONG>, <code>!(a under the equivalence relation defined by <STRONG>operator&lt;</STRONG>, <code>!(a
&lt; b) &amp;&amp; !(b &lt; a)</code>, two <STRONG>weak_ptr</STRONG> instances &lt; b) &amp;&amp; !(b &lt; a)</code>, two <STRONG>weak_ptr</STRONG> instances
are equivalent if and only if they <EM>share ownership</EM> or are both <EM>empty</EM>.</LI></UL> are equivalent if and only if they <EM>share ownership</EM> or are both <EM>empty</EM>.</LI></UL>
<p><b>Throws:</b> nothing.</p> <p><b>Throws:</b> nothing.</p>
<P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in <P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in
associative containers.</P> associative containers.</P>
</blockquote> </blockquote>
<h3><a name="free-swap">swap</a></h3> <h3><a name="free-swap">swap</a></h3>
<pre>template&lt;class T&gt; <pre>template&lt;class T&gt;
void swap(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b)</pre> void swap(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b)</pre>
<BLOCKQUOTE> <BLOCKQUOTE>
<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P> <P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
<P><B>Throws:</B> nothing.</P> <P><B>Throws:</B> nothing.</P>
<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>
<h2><a name="FAQ">Frequently Asked Questions</a></h2> <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 <P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its
constructor?</P> constructor?</P>
<P><b>A.</b> No. A <STRONG>weak_ptr</STRONG> can only be created from a <STRONG>shared_ptr</STRONG>, <P><b>A.</b> No. A <STRONG>weak_ptr</STRONG> can only be created from a <STRONG>shared_ptr</STRONG>,
and at object construction time no <STRONG>shared_ptr</STRONG> to the object and at object construction time no <STRONG>shared_ptr</STRONG> to the object
exists yet. Even if you could create a temporary <STRONG>shared_ptr</STRONG> to <STRONG> exists yet. Even if you could create a temporary <STRONG>shared_ptr</STRONG> to <STRONG>
this</STRONG>, it would go out of scope at the end of the constructor, and this</STRONG>, it would go out of scope at the end of the constructor, and
all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P> all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P>
<P>The solution is to make the constructor private, and supply a factory function <P>The solution is to make the constructor private, and supply a factory function
that returns a <STRONG>shared_ptr</STRONG>:<BR> that returns a <STRONG>shared_ptr</STRONG>:<BR>
</P> </P>
<pre> <pre>
class X class X
{ {
private: private:
@ -230,13 +230,11 @@ public:
} }
}; };
</pre> </pre>
<p><br> <hr>
</p> <p>$Date$</p>
<hr> <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
<p>$Date$</p> Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version
<p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or </body>
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body>
</html> </html>