forked from boostorg/smart_ptr
Tidy documentation in smart_ptr
This commit is contained in:
Glen Fernandes
@ -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>
|
||||
<head>
|
||||
<title>Smart Pointer Changes</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86"
|
||||
border="0"></A>Smart Pointer Changes</h1>
|
||||
<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
|
||||
time, it's useful to have a detailed list of what changed from a library user's
|
||||
point of view.</p>
|
||||
<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
|
||||
like the old version.</p>
|
||||
<h2>Features Requiring Code Changes to Take Advantage</h2>
|
||||
<ul>
|
||||
<li>
|
||||
The smart pointer class templates now each have their own header file. For
|
||||
compatibility, the <a href="../../boost/smart_ptr.hpp"><boost/smart_ptr.hpp></a>
|
||||
header now includes the headers for the four classic smart pointer class
|
||||
templates.
|
||||
<li>
|
||||
The <b>weak_ptr</b>
|
||||
template was added.
|
||||
<li>
|
||||
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>
|
||||
destructor. This makes it easier to have shared_ptr members in classes without
|
||||
explicit destructors.
|
||||
<li>
|
||||
A custom deallocator can be passed in when creating a <b>shared_ptr</b> or <b>shared_array</b>.
|
||||
<li>
|
||||
<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>
|
||||
and <b>dynamic_cast</b>
|
||||
do for pointers.
|
||||
<li>
|
||||
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>.
|
||||
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
|
||||
assertions are off).
|
||||
<li>
|
||||
The <b>BOOST_SMART_PTR_CONVERSION</b>
|
||||
feature has been removed.
|
||||
<li>
|
||||
<b>shared_ptr<void></b> is now allowed.</li>
|
||||
</ul>
|
||||
<h2>Features That Improve Robustness</h2>
|
||||
<ul>
|
||||
<li>
|
||||
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">
|
||||
<boost/detail/atomic_count.hpp></a>
|
||||
file for details
|
||||
<li>
|
||||
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
|
||||
the last <b>shared_ptr</b> was a pointer to a sub-object of a class that did
|
||||
not have a virtual destructor.</li>
|
||||
</ul>
|
||||
<h2>Implementation Details</h2>
|
||||
<ul>
|
||||
<li>
|
||||
Some bugs in the assignment operator implementations and in <b>reset</b>
|
||||
have been fixed by using the "copy and swap" idiom.
|
||||
<li>
|
||||
Assertions have been added to check preconditions of various functions;
|
||||
however, since these use the new <a href="../../boost/assert.hpp"><boost/assert.hpp></a>
|
||||
header, the assertions are disabled by default.
|
||||
<li>
|
||||
The partial specialization of <b>std::less</b> has been replaced by <b>operator<</b>
|
||||
overloads which accomplish the same thing without relying on undefined
|
||||
behavior.
|
||||
<li>
|
||||
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
|
||||
violate the C++ standard.</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<p>Revised 1 February 2002</p>
|
||||
<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
|
||||
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
|
||||
</body>
|
||||
<head>
|
||||
<title>Smart Pointer Changes</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">Smart Pointer Changes</h1>
|
||||
<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
|
||||
time, it's useful to have a detailed list of what changed from a library user's
|
||||
point of view.</p>
|
||||
<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
|
||||
like the old version.</p>
|
||||
<h2>Features Requiring Code Changes to Take Advantage</h2>
|
||||
<ul>
|
||||
<li>
|
||||
The smart pointer class templates now each have their own header file. For
|
||||
compatibility, the <a href="../../boost/smart_ptr.hpp"><boost/smart_ptr.hpp></a>
|
||||
header now includes the headers for the four classic smart pointer class
|
||||
templates.
|
||||
<li>
|
||||
The <b>weak_ptr</b>
|
||||
template was added.
|
||||
<li>
|
||||
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>
|
||||
destructor. This makes it easier to have shared_ptr members in classes without
|
||||
explicit destructors.
|
||||
<li>
|
||||
A custom deallocator can be passed in when creating a <b>shared_ptr</b> or <b>shared_array</b>.
|
||||
<li>
|
||||
<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>
|
||||
and <b>dynamic_cast</b>
|
||||
do for pointers.
|
||||
<li>
|
||||
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>.
|
||||
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
|
||||
assertions are off).
|
||||
<li>
|
||||
The <b>BOOST_SMART_PTR_CONVERSION</b>
|
||||
feature has been removed.
|
||||
<li>
|
||||
<b>shared_ptr<void></b> is now allowed.</li>
|
||||
</ul>
|
||||
<h2>Features That Improve Robustness</h2>
|
||||
<ul>
|
||||
<li>
|
||||
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">
|
||||
<boost/detail/atomic_count.hpp></a>
|
||||
file for details
|
||||
<li>
|
||||
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
|
||||
the last <b>shared_ptr</b> was a pointer to a sub-object of a class that did
|
||||
not have a virtual destructor.</li>
|
||||
</ul>
|
||||
<h2>Implementation Details</h2>
|
||||
<ul>
|
||||
<li>
|
||||
Some bugs in the assignment operator implementations and in <b>reset</b>
|
||||
have been fixed by using the "copy and swap" idiom.
|
||||
<li>
|
||||
Assertions have been added to check preconditions of various functions;
|
||||
however, since these use the new <a href="../../boost/assert.hpp"><boost/assert.hpp></a>
|
||||
header, the assertions are disabled by default.
|
||||
<li>
|
||||
The partial specialization of <b>std::less</b> has been replaced by <b>operator<</b>
|
||||
overloads which accomplish the same thing without relying on undefined
|
||||
behavior.
|
||||
<li>
|
||||
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
|
||||
violate the C++ standard.</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<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
|
||||
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>
|
||||
|
||||
@ -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>
|
||||
<head>
|
||||
<title>Boost: enable_shared_from_this.hpp documentation</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="white" style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%">
|
||||
<table border="0" width="100%">
|
||||
<tr>
|
||||
<td width="277"><A href="../../index.htm"> <img src="../../boost.png" alt="boost.png (6897 bytes)" width="277" height="86" border="0"></A>
|
||||
</td>
|
||||
<td align="center">
|
||||
<h1>enable_shared_from_this.hpp</h1>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2" height="64"> </td>
|
||||
</tr>
|
||||
</table>
|
||||
<h3><a name="Purpose">Purpose</a></h3>
|
||||
<p>
|
||||
The header <STRONG><boost/enable_shared_from_this.hpp></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<T></STRONG> defines two member functions
|
||||
called <STRONG>shared_from_this</STRONG> that return a <STRONG>shared_ptr<T></STRONG>
|
||||
and <STRONG>shared_ptr<T const></STRONG>, depending on constness, to <STRONG>this</STRONG>.</P>
|
||||
<h3><a name="Example">Example</a></h3>
|
||||
<pre>
|
||||
<head>
|
||||
<title>enable_shared_from_this</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">enable_shared_from_this</h1>
|
||||
<h2><a name="Purpose">Purpose</a></h2>
|
||||
<p>
|
||||
The header <STRONG><boost/enable_shared_from_this.hpp></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<T></STRONG> defines two member functions
|
||||
called <STRONG>shared_from_this</STRONG> that return a <STRONG>shared_ptr<T></STRONG>
|
||||
and <STRONG>shared_ptr<T const></STRONG>, depending on constness, to <STRONG>this</STRONG>.</P>
|
||||
<h2><a name="Example">Example</a></h2>
|
||||
<pre>
|
||||
#include <boost/enable_shared_from_this.hpp>
|
||||
#include <boost/shared_ptr.hpp>
|
||||
#include <cassert>
|
||||
@ -51,8 +41,8 @@ int main()
|
||||
assert(!(p < q || q < p)); // p and q must share ownership
|
||||
}
|
||||
</pre>
|
||||
<h3><a name="Synopsis">Synopsis</a></h3>
|
||||
<pre>
|
||||
<h3><a name="Synopsis">Synopsis</a></h3>
|
||||
<pre>
|
||||
namespace boost
|
||||
{
|
||||
|
||||
@ -66,30 +56,30 @@ public:
|
||||
|
||||
}
|
||||
</pre>
|
||||
<h4>template<class T> shared_ptr<T>
|
||||
enable_shared_from_this<T>::shared_from_this();</h4>
|
||||
<h4>template<class T> shared_ptr<T const>
|
||||
enable_shared_from_this<T>::shared_from_this() const;</h4>
|
||||
<blockquote>
|
||||
<p>
|
||||
<b>Requires:</b> <STRONG>enable_shared_from_this<T></STRONG> must be an
|
||||
accessible base class of <b>T</b>. <STRONG>*this</STRONG> must be a subobject
|
||||
of an instance <STRONG>t</STRONG> of type <STRONG>T</STRONG> . There must exist
|
||||
at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> that <EM>owns</EM>
|
||||
<STRONG>t</STRONG>.
|
||||
</p>
|
||||
<p>
|
||||
<b>Returns:</b> A <b>shared_ptr<T></b> instance <b>r</b> that shares
|
||||
ownership with <b>p</b>.
|
||||
</p>
|
||||
<p>
|
||||
<b>Postconditions:</b> <tt>r.get() == this</tt>.
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>
|
||||
<br>
|
||||
<small>Copyright <EFBFBD> 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
|
||||
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
|
||||
</body>
|
||||
<h4>template<class T> shared_ptr<T>
|
||||
enable_shared_from_this<T>::shared_from_this();</h4>
|
||||
<h4>template<class T> shared_ptr<T const>
|
||||
enable_shared_from_this<T>::shared_from_this() const;</h4>
|
||||
<blockquote>
|
||||
<p>
|
||||
<b>Requires:</b> <STRONG>enable_shared_from_this<T></STRONG> must be an
|
||||
accessible base class of <b>T</b>. <STRONG>*this</STRONG> must be a subobject
|
||||
of an instance <STRONG>t</STRONG> of type <STRONG>T</STRONG> . There must exist
|
||||
at least one <STRONG>shared_ptr</STRONG> instance <STRONG>p</STRONG> that <EM>owns</EM>
|
||||
<STRONG>t</STRONG>.
|
||||
</p>
|
||||
<p>
|
||||
<b>Returns:</b> A <b>shared_ptr<T></b> instance <b>r</b> that shares
|
||||
ownership with <b>p</b>.
|
||||
</p>
|
||||
<p>
|
||||
<b>Postconditions:</b> <tt>r.get() == this</tt>.
|
||||
</p>
|
||||
</blockquote>
|
||||
<p>$Date$</p>
|
||||
<p>
|
||||
<small>Copyright © 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
|
||||
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>
|
||||
|
||||
13
index.html
13
index.html
@ -1,15 +1,18 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<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">
|
||||
</head>
|
||||
<body>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
Automatic redirection failed, please go to
|
||||
<a href="smart_ptr.htm">smart_ptr.htm</a>.
|
||||
</body>
|
||||
</html>
|
||||
<!--
|
||||
<09> Copyright Beman Dawes, 2001
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt
|
||||
(C) Copyright Beman Dawes, 2001
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt
|
||||
-->
|
||||
|
||||
@ -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>
|
||||
<head>
|
||||
<title>intrusive_ptr</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff">
|
||||
<h1><a href="../../index.htm"><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
|
||||
border="0" /></a>intrusive_ptr class template</h1>
|
||||
<p>
|
||||
<a href="#Introduction">Introduction</a><br />
|
||||
<a href="#Synopsis">Synopsis</a><br />
|
||||
<a href="#Members">Members</a><br />
|
||||
<a href="#functions">Free Functions</a><br />
|
||||
</p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<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
|
||||
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>
|
||||
is destroyed, it calls <code>intrusive_ptr_release</code>; this function is
|
||||
responsible for destroying the object when its reference count drops to zero.
|
||||
The user is expected to provide suitable definitions of these two functions. On
|
||||
compilers that support argument-dependent lookup, <code>intrusive_ptr_add_ref</code>
|
||||
and <code>intrusive_ptr_release</code> should be defined in the namespace
|
||||
that corresponds to their parameter; otherwise, the definitions need to go in
|
||||
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
|
||||
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
|
||||
to. <code>intrusive_ptr<T></code> can be implicitly converted to <code>intrusive_ptr<U></code>
|
||||
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>
|
||||
<ul>
|
||||
<li>
|
||||
Some existing frameworks or OSes provide objects with embedded reference
|
||||
counts;</li>
|
||||
<li>
|
||||
The memory footprint of <code>intrusive_ptr</code>
|
||||
is the same as the corresponding raw pointer;</li>
|
||||
<li>
|
||||
<code>intrusive_ptr<T></code> can be constructed from an arbitrary
|
||||
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
|
||||
fits your needs than <code>shared_ptr</code>, try a <code>shared_ptr</code>-based
|
||||
design first.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
<head>
|
||||
<title>intrusive_ptr</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">intrusive_ptr class template</h1>
|
||||
<p>
|
||||
<a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Members">Members</a><br>
|
||||
<a href="#functions">Free Functions</a><br>
|
||||
</p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<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
|
||||
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>
|
||||
is destroyed, it calls <code>intrusive_ptr_release</code>; this function is
|
||||
responsible for destroying the object when its reference count drops to zero.
|
||||
The user is expected to provide suitable definitions of these two functions. On
|
||||
compilers that support argument-dependent lookup, <code>intrusive_ptr_add_ref</code>
|
||||
and <code>intrusive_ptr_release</code> should be defined in the namespace
|
||||
that corresponds to their parameter; otherwise, the definitions need to go in
|
||||
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
|
||||
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
|
||||
to. <code>intrusive_ptr<T></code> can be implicitly converted to <code>intrusive_ptr<U></code>
|
||||
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>
|
||||
<ul>
|
||||
<li>
|
||||
Some existing frameworks or OSes provide objects with embedded reference
|
||||
counts;</li>
|
||||
<li>
|
||||
The memory footprint of <code>intrusive_ptr</code>
|
||||
is the same as the corresponding raw pointer;</li>
|
||||
<li>
|
||||
<code>intrusive_ptr<T></code> can be constructed from an arbitrary
|
||||
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
|
||||
fits your needs than <code>shared_ptr</code>, try a <code>shared_ptr</code>-based
|
||||
design first.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<class T> class intrusive_ptr {
|
||||
|
||||
@ -117,203 +117,204 @@
|
||||
std::basic_ostream<E, T> & <a href="#insertion-operator" >operator<<</a> (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);
|
||||
|
||||
}</pre>
|
||||
<h2><a name="Members">Members</a></h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<blockquote>
|
||||
<p>Provides the type of the template parameter <code>T</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<pre>intrusive_ptr(); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Postconditions:</b> <code>get() == 0</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>intrusive_ptr(T * p, bool add_ref = true);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> <code>if(p != 0 && add_ref) intrusive_ptr_add_ref(p);</code>.</p>
|
||||
<p><b>Postconditions:</b> <code>get() == p</code>.</p>
|
||||
</blockquote>
|
||||
<pre>intrusive_ptr(intrusive_ptr const & r);
|
||||
<h2><a name="Members">Members</a></h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<blockquote>
|
||||
<p>Provides the type of the template parameter <code>T</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<pre>intrusive_ptr(); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Postconditions:</b> <code>get() == 0</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>intrusive_ptr(T * p, bool add_ref = true);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> <code>if(p != 0 && add_ref) intrusive_ptr_add_ref(p);</code>.</p>
|
||||
<p><b>Postconditions:</b> <code>get() == p</code>.</p>
|
||||
</blockquote>
|
||||
<pre>intrusive_ptr(intrusive_ptr const & r);
|
||||
template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r);</pre>
|
||||
<blockquote>
|
||||
<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>
|
||||
</blockquote>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~intrusive_ptr();</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="assignment">assignment</a></h3>
|
||||
<pre>intrusive_ptr & operator=(intrusive_ptr const & r);
|
||||
<blockquote>
|
||||
<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>
|
||||
</blockquote>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~intrusive_ptr();</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="assignment">assignment</a></h3>
|
||||
<pre>intrusive_ptr & operator=(intrusive_ptr const & r);
|
||||
template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r);
|
||||
intrusive_ptr & operator=(T * r);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
|
||||
<p><b>Returns:</b> <code>*this</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset();</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr().swap(*this)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>void reset(T * r);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>void reset(T * r, bool add_ref);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r, add_ref).swap(*this)</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="indirection">indirection</a></h3>
|
||||
<pre>T & operator*() const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requirements:</b> <code>get() != 0</code>.</p>
|
||||
<p><b>Returns:</b> <code>*get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>T * operator->() const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requirements:</b> <code>get() != 0</code>.</p>
|
||||
<p><b>Returns:</b> <code>get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> the stored pointer.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="detach">detach</a></h3>
|
||||
<pre>T * detach(); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> the stored pointer.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Postconditions:</b> <code>get() == 0</code>.</p>
|
||||
<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,
|
||||
without the performance overhead of acquiring and dropping an extra
|
||||
reference. It can be viewed as the complement of the
|
||||
non-reference-incrementing constructor.</p>
|
||||
<p><b>Caution:</b> Using <code>detach</code> escapes the safety of automatic
|
||||
reference counting provided by <code>intrusive_ptr</code>. It should
|
||||
by used only where strictly necessary (such as when interfacing to an
|
||||
existing API), and when the implications are thoroughly understood.</p>
|
||||
</blockquote>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is
|
||||
equivalent to <code>get() != 0</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> This conversion operator allows <code>intrusive_ptr</code> objects to be
|
||||
used in boolean contexts, like <code>if (p && p->valid()) {}</code>.
|
||||
The actual target type is typically a pointer to a member function, avoiding
|
||||
many of the implicit conversion pitfalls.</p>
|
||||
</blockquote>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(intrusive_ptr & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="comparison">comparison</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
|
||||
<p><b>Returns:</b> <code>*this</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset();</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr().swap(*this)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>void reset(T * r);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>void reset(T * r, bool add_ref);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r, add_ref).swap(*this)</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="indirection">indirection</a></h3>
|
||||
<pre>T & operator*() const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requirements:</b> <code>get() != 0</code>.</p>
|
||||
<p><b>Returns:</b> <code>*get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>T * operator->() const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requirements:</b> <code>get() != 0</code>.</p>
|
||||
<p><b>Returns:</b> <code>get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> the stored pointer.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="detach">detach</a></h3>
|
||||
<pre>T * detach(); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> the stored pointer.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Postconditions:</b> <code>get() == 0</code>.</p>
|
||||
<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,
|
||||
without the performance overhead of acquiring and dropping an extra
|
||||
reference. It can be viewed as the complement of the
|
||||
non-reference-incrementing constructor.</p>
|
||||
<p><b>Caution:</b> Using <code>detach</code> escapes the safety of automatic
|
||||
reference counting provided by <code>intrusive_ptr</code>. It should
|
||||
by used only where strictly necessary (such as when interfacing to an
|
||||
existing API), and when the implications are thoroughly understood.</p>
|
||||
</blockquote>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is
|
||||
equivalent to <code>get() != 0</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> This conversion operator allows <code>intrusive_ptr</code> objects to be
|
||||
used in boolean contexts, like <code>if (p && p->valid()) {}</code>.
|
||||
The actual target type is typically a pointer to a member function, avoiding
|
||||
many of the implicit conversion pitfalls.</p>
|
||||
</blockquote>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(intrusive_ptr & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="comparison">comparison</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() == b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() == b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() != b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() != b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
bool operator==(intrusive_ptr<T> const & a, U * b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() == b</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() == b</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
bool operator!=(intrusive_ptr<T> const & a, U * b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() != b</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a.get() != b</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
bool operator==(T * a, intrusive_ptr<U> const & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a == b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a == b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
bool operator!=(T * a, intrusive_ptr<U> const & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a != b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>a != b.get()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class T, class U>
|
||||
bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>std::less<T *>()(a.get(), b.get())</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> Allows <code>intrusive_ptr</code> objects to be used as keys
|
||||
in associative containers.</p>
|
||||
</blockquote>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>std::less<T *>()(a.get(), b.get())</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> Allows <code>intrusive_ptr</code> objects to be used as keys
|
||||
in associative containers.</p>
|
||||
</blockquote>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T>
|
||||
void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>a.swap(b)</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> Matches the interface of <code>std::swap</code>. Provided as an aid to
|
||||
generic programming.</p>
|
||||
</blockquote>
|
||||
<h3><a name="get_pointer">get_pointer</a></h3>
|
||||
<pre>template<class T>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Equivalent to <code>a.swap(b)</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> Matches the interface of <code>std::swap</code>. Provided as an aid to
|
||||
generic programming.</p>
|
||||
</blockquote>
|
||||
<h3><a name="get_pointer">get_pointer</a></h3>
|
||||
<pre>template<class T>
|
||||
T * get_pointer(intrusive_ptr<T> const & p); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>p.get()</code>.</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">
|
||||
mem_fn</a>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="static_pointer_cast">static_pointer_cast</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>p.get()</code>.</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">
|
||||
mem_fn</a>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="static_pointer_cast">static_pointer_cast</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>intrusive_ptr<T>(static_cast<T*>(r.get()))</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="const_pointer_cast">const_pointer_cast</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>intrusive_ptr<T>(static_cast<T*>(r.get()))</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="const_pointer_cast">const_pointer_cast</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>intrusive_ptr<T>(const_cast<T*>(r.get()))</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>intrusive_ptr<T>(const_cast<T*>(r.get()))</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r);</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>intrusive_ptr<T>(dynamic_cast<T*>(r.get()))</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="insertion-operator">operator<<</a></h3>
|
||||
<pre>template<class E, class T, class Y>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>intrusive_ptr<T>(dynamic_cast<T*>(r.get()))</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="insertion-operator">operator<<</a></h3>
|
||||
<pre>template<class E, class T, class Y>
|
||||
std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> <code>os << p.get();</code>.</p>
|
||||
<p><b>Returns:</b> <code>os</code>.</p>
|
||||
</blockquote>
|
||||
<hr />
|
||||
<p>
|
||||
<small>Copyright <20> 2003-2005, 2013 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
|
||||
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>.</small></p>
|
||||
</body>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> <code>os << p.get();</code>.</p>
|
||||
<p><b>Returns:</b> <code>os</code>.</p>
|
||||
</blockquote>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<p>
|
||||
<small>Copyright © 2003-2005, 2013 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
|
||||
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>
|
||||
|
||||
@ -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>
|
||||
<head>
|
||||
<title>intrusive_ref_counter</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgColor="#ffffff">
|
||||
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
|
||||
border="0"></A>basic_intrusive_ref_counter class template</h1>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">basic_intrusive_ref_counter class template</h1>
|
||||
<p>
|
||||
<A href="#Introduction">Introduction</A><br>
|
||||
<A href="#Synopsis">Synopsis</A><br>
|
||||
@ -14,11 +14,11 @@
|
||||
</p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>The <STRONG>intrusive_ref_counter</STRONG> class template implements a reference counter for a derived
|
||||
user'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
|
||||
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.
|
||||
The first parameter is the user'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>
|
||||
<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
|
||||
@ -85,11 +85,10 @@
|
||||
<P><B>Notes:</B> The returned value may not be actual in multi-threaded applications.</P>
|
||||
</BLOCKQUOTE>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<p>
|
||||
$Date$</p>
|
||||
<p>
|
||||
<small>Copyright <20> 2013 Andrey Semashev. 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>
|
||||
<small>Copyright © 2013 Andrey Semashev. 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>
|
||||
|
||||
154
make_shared.html
154
make_shared.html
@ -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>
|
||||
<head>
|
||||
<title>make_shared and allocate_shared</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgColor="#ffffff">
|
||||
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
|
||||
border="0"></A>make_shared and allocate_shared function templates</h1>
|
||||
<p><A href="#Introduction">Introduction</A><br>
|
||||
<A href="#Synopsis">Synopsis</A><br>
|
||||
<A href="#functions">Free Functions</A><br>
|
||||
<A href="#example">Example</A><br>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Consistent use of <a href="shared_ptr.htm"><code>shared_ptr</code></a>
|
||||
can eliminate the need to use an explicit <code>delete</code>,
|
||||
but alone it provides no support in avoiding explicit <code>new</code>.
|
||||
There have been repeated requests from users for a factory function that creates
|
||||
an object of a given type and returns a <code>shared_ptr</code> to it.
|
||||
Besides convenience and style, such a function is also exception safe and
|
||||
considerably faster because it can use a single allocation for both the object
|
||||
and its corresponding control block, eliminating a significant portion of
|
||||
<code>shared_ptr</code>'s construction overhead.
|
||||
This eliminates one of the major efficiency complaints about <code>shared_ptr</code>.
|
||||
</p>
|
||||
<p>The header file <boost/make_shared.hpp> provides a family of overloaded function templates,
|
||||
<code>make_shared</code> and <code>allocate_shared</code>, to address this need.
|
||||
<code>make_shared</code> uses the global operator <code>new</code> to allocate memory,
|
||||
whereas <code>allocate_shared</code> uses an user-supplied allocator, allowing finer control.</p>
|
||||
<p>
|
||||
The rationale for choosing the name <code>make_shared</code> is that the expression
|
||||
<code>make_shared<Widget>()</code> can be read aloud and conveys the intended meaning.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
<head>
|
||||
<title>make_shared and allocate_shared</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">make_shared and allocate_shared
|
||||
function templates</h1>
|
||||
<p><A href="#Introduction">Introduction</A><br>
|
||||
<A href="#Synopsis">Synopsis</A><br>
|
||||
<A href="#functions">Free Functions</A><br>
|
||||
<A href="#example">Example</A><br>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Consistent use of <a href="shared_ptr.htm"><code>shared_ptr</code></a>
|
||||
can eliminate the need to use an explicit <code>delete</code>,
|
||||
but alone it provides no support in avoiding explicit <code>new</code>.
|
||||
There have been repeated requests from users for a factory function that creates
|
||||
an object of a given type and returns a <code>shared_ptr</code> to it.
|
||||
Besides convenience and style, such a function is also exception safe and
|
||||
considerably faster because it can use a single allocation for both the object
|
||||
and its corresponding control block, eliminating a significant portion of
|
||||
<code>shared_ptr</code>'s construction overhead.
|
||||
This eliminates one of the major efficiency complaints about <code>shared_ptr</code>.
|
||||
</p>
|
||||
<p>The header file <boost/make_shared.hpp> provides a family of overloaded function templates,
|
||||
<code>make_shared</code> and <code>allocate_shared</code>, to address this need.
|
||||
<code>make_shared</code> uses the global operator <code>new</code> to allocate memory,
|
||||
whereas <code>allocate_shared</code> uses an user-supplied allocator, allowing finer control.</p>
|
||||
<p>
|
||||
The rationale for choosing the name <code>make_shared</code> is that the expression
|
||||
<code>make_shared<Widget>()</code> can be read aloud and conveys the intended meaning.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<typename T> class shared_ptr;
|
||||
|
||||
@ -41,7 +42,7 @@
|
||||
template<typename T, typename A>
|
||||
shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & );
|
||||
|
||||
#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<typename T, typename... Args>
|
||||
shared_ptr<T> <a href="#functions">make_shared</a>( Args && ... args );
|
||||
@ -69,51 +70,50 @@
|
||||
|
||||
#endif
|
||||
}</pre>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<pre>template<class T, class... Args>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<pre>template<class T, class... Args>
|
||||
shared_ptr<T> make_shared( Args && ... args );
|
||||
template<class T, class A, class... Args>
|
||||
shared_ptr<T> allocate_shared( A const & a, Args && ... args );</pre>
|
||||
<blockquote>
|
||||
<p><b>Requires:</b> The expression <code>new( pv ) T( std::forward<Args>(args)... )</code>,
|
||||
where <code>pv</code> is a <code>void*</code> pointing to storage suitable
|
||||
to hold an object of type <code>T</code>,
|
||||
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.
|
||||
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>
|
||||
and constructs an object in it via the placement new expression <code>new( pv ) T()</code>
|
||||
or <code>new( pv ) T( std::forward<Args>(args)... )</code>.
|
||||
<code>allocate_shared</code> uses a copy of <code>a</code> to allocate memory.
|
||||
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
|
||||
of the newly constructed object of type <code>T</code>.</p>
|
||||
<p><b>Postconditions:</b> <code>get() != 0 && use_count() == 1</code>.</p>
|
||||
<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>
|
||||
<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
|
||||
allocation. This provides efficiency equivalent to an intrusive smart pointer.</p>
|
||||
<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
|
||||
the constructors of <code>T</code>.</p>
|
||||
<p>Otherwise, the implementation will fall back on
|
||||
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>,
|
||||
you may do so by wrapping the parameter in a call to <code>boost::ref</code>.
|
||||
In addition, you will be
|
||||
limited to a maximum of 9 arguments (not counting the allocator argument of
|
||||
allocate_shared).</p>
|
||||
</blockquote>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<pre>boost::shared_ptr<std::string> x = boost::make_shared<std::string>("hello, world!");
|
||||
<blockquote>
|
||||
<p><b>Requires:</b> The expression <code>new( pv ) T( std::forward<Args>(args)... )</code>,
|
||||
where <code>pv</code> is a <code>void*</code> pointing to storage suitable
|
||||
to hold an object of type <code>T</code>,
|
||||
shall be well-formed. <code>A</code> shall be an <em>Allocator</em>,
|
||||
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>
|
||||
<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>
|
||||
or <code>new( pv ) T( std::forward<Args>(args)... )</code>.
|
||||
<code>allocate_shared</code> uses a copy of <code>a</code> to allocate memory.
|
||||
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
|
||||
of the newly constructed object of type <code>T</code>.</p>
|
||||
<p><b>Postconditions:</b> <code>get() != 0 && use_count() == 1</code>.</p>
|
||||
<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>
|
||||
<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
|
||||
allocation. This provides efficiency equivalent to an intrusive smart pointer.</p>
|
||||
<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
|
||||
the constructors of <code>T</code>.</p>
|
||||
<p>Otherwise, the implementation will fall back on
|
||||
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>,
|
||||
you may do so by wrapping the parameter in a call to <code>boost::ref</code>.
|
||||
In addition, you will be
|
||||
limited to a maximum of 9 arguments (not counting the allocator argument of
|
||||
allocate_shared).</p>
|
||||
</blockquote>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<pre>boost::shared_ptr<std::string> x = boost::make_shared<std::string>("hello, world!");
|
||||
std::cout << *x;</pre>
|
||||
<hr>
|
||||
<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.
|
||||
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>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<p><small>Copyright 2008 Peter Dimov. Copyright 2008 Frank Mori Hess.
|
||||
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>
|
||||
|
||||
@ -250,8 +250,10 @@ boost::shared_ptr<int[4][2]> a2 = boost::make_shared_noinit<int[4][2]&g
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<h2><a name="history">History</a></h2>
|
||||
<p>January 2014. Glen Fernandes reduced the overloads of make_shared and
|
||||
allocate_shared according to <a href="#N3870">N3870</a>.</p>
|
||||
<p>February 2014. Glen Fernandes updated overloads of make_shared and
|
||||
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
|
||||
make_shared and allocate_shared for arrays.</p>
|
||||
<h2><a name="references">References</a></h2>
|
||||
@ -260,7 +262,7 @@ boost::shared_ptr<int[4][2]> a2 = boost::make_shared_noinit<int[4][2]&g
|
||||
Extending make_shared to Support Arrays, Revision 1</a>, Peter Dimov
|
||||
& Glen Fernandes, January, 2014.</p>
|
||||
<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
|
||||
Boost Software License, Version 1.0. See accompanying file
|
||||
<a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
|
||||
|
||||
@ -142,7 +142,7 @@ unique_ptr<int[][2]> p2 = boost::make_unique_noinit<int[][2]>(2);</p
|
||||
<p>January 2014. Glen Fernandes contributed implementations of
|
||||
make_unique for objects and arrays.</p>
|
||||
<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
|
||||
Boost Software License, Version 1.0. See accompanying file
|
||||
<a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
|
||||
|
||||
@ -1,33 +1,34 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>pointer_cast.hpp</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1><IMG height="86" alt="C++ Boost" src="../../boost.png" width="277" align="middle" border="0">Pointer
|
||||
cast functions</h1>
|
||||
<p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code>
|
||||
<code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>)
|
||||
provide a way to write generic pointer castings for raw pointers. The functions
|
||||
are defined in <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A>.</CITE></p>
|
||||
<P>There is test/example code in <CITE><A href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</A></CITE>.</p>
|
||||
<h2><a name="rationale">Rationale</a></h2>
|
||||
<P>Boost smart pointers usually overload those functions to provide a mechanism to
|
||||
emulate pointers casts. For example, <code>boost::shared_ptr<...></code> implements
|
||||
a static pointer cast this way:</P>
|
||||
<pre>
|
||||
<head>
|
||||
<title>pointer_cast</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">pointer_cast</h1>
|
||||
<p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code>
|
||||
<code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>)
|
||||
provide a way to write generic pointer castings for raw pointers. The functions
|
||||
are defined in <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A>.</CITE></p>
|
||||
<P>There is test/example code in <CITE><A href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</A></CITE>.</p>
|
||||
<h2><a name="rationale">Rationale</a></h2>
|
||||
<P>Boost smart pointers usually overload those functions to provide a mechanism to
|
||||
emulate pointers casts. For example, <code>boost::shared_ptr<...></code> implements
|
||||
a static pointer cast this way:</P>
|
||||
<pre>
|
||||
template<class T, class U>
|
||||
shared_ptr<T> static_pointer_cast(shared_ptr<U> const &r);
|
||||
</pre>
|
||||
<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>,
|
||||
<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 example, memory managers or shared memory compatible classes, the same code
|
||||
can be used for raw and smart pointers.</p>
|
||||
<H2><A name="synopsis">Synopsis</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<PRE>
|
||||
<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>,
|
||||
<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 example, memory managers or shared memory compatible classes, the same code
|
||||
can be used for raw and smart pointers.</p>
|
||||
<H2><A name="synopsis">Synopsis</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<PRE>
|
||||
namespace boost {
|
||||
|
||||
template<class T, class U>
|
||||
@ -48,12 +49,12 @@ inline T* reinterpret_pointer_cast(U *ptr)
|
||||
|
||||
} // namespace boost
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
<P>As you can see from the above synopsis, the pointer cast functions are just
|
||||
wrappers around standard C++ cast operators.</P>
|
||||
<H2><A name="example">Example</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<PRE>
|
||||
</BLOCKQUOTE>
|
||||
<P>As you can see from the above synopsis, the pointer cast functions are just
|
||||
wrappers around standard C++ cast operators.</P>
|
||||
<H2><A name="example">Example</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<PRE>
|
||||
#include <boost/pointer_cast.hpp>
|
||||
#include <boost/shared_ptr.hpp>
|
||||
|
||||
@ -93,13 +94,13 @@ int main()
|
||||
delete ptr;
|
||||
return 0;
|
||||
}</PRE>
|
||||
</BLOCKQUOTE>
|
||||
<P>The example demonstrates how the generic pointer casts help us create pointer
|
||||
independent code.</P>
|
||||
<hr>
|
||||
<p>Revised: $Date$</p>
|
||||
<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">
|
||||
LICENSE_1_0.txt</A> or a copy at <<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>>.)</p>
|
||||
</body>
|
||||
</BLOCKQUOTE>
|
||||
<P>The example demonstrates how the generic pointer casts help us create pointer
|
||||
independent code.</P>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<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">
|
||||
LICENSE_1_0.txt</A> or a copy at <<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>>.)</p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>pointer_to_other.hpp</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" WIDTH="277" HEIGHT="86">Header
|
||||
<a href="../../boost/pointer_to_other.hpp">boost/pointer_to_other.hpp</a></h1>
|
||||
<p>
|
||||
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
|
||||
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>
|
||||
<h2><a name="contents">Contents</a></h2>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="#rationale">Rationale</a>
|
||||
<li>
|
||||
<a href="#synopsis">Synopsis</a>
|
||||
<li>
|
||||
<a href="#example">Example</a></li>
|
||||
</ul>
|
||||
<h2><a name="rationale">Rationale</a></h2>
|
||||
<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
|
||||
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
|
||||
raw or smart pointer to a float.)</p>
|
||||
<pre>template <class IntPtr>
|
||||
<head>
|
||||
<title>pointer_to_other</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">pointer_to_other</h1>
|
||||
<p>
|
||||
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
|
||||
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>
|
||||
<h2><a name="contents">Contents</a></h2>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="#rationale">Rationale</a>
|
||||
<li>
|
||||
<a href="#synopsis">Synopsis</a>
|
||||
<li>
|
||||
<a href="#example">Example</a></li>
|
||||
</ul>
|
||||
<h2><a name="rationale">Rationale</a></h2>
|
||||
<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
|
||||
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
|
||||
raw or smart pointer to a float.)</p>
|
||||
<pre>template <class IntPtr>
|
||||
class FloatPointerHolder
|
||||
{
|
||||
<em>// Let's define a pointer to a float</em>
|
||||
@ -35,8 +35,8 @@ class FloatPointerHolder
|
||||
<IntPtr, float>::type float_ptr_t;
|
||||
float_ptr_t float_ptr;
|
||||
};</pre>
|
||||
<h2><a name="synopsis">Synopsis</a></h2>
|
||||
<pre>
|
||||
<h2><a name="synopsis">Synopsis</a></h2>
|
||||
<pre>
|
||||
namespace boost {
|
||||
|
||||
template<class T, class U>
|
||||
@ -69,10 +69,10 @@ struct pointer_to_other< T*, U >
|
||||
};
|
||||
|
||||
} <em>// namespace boost</em></pre>
|
||||
<p>If these definitions are not correct for a specific smart pointer, we can define
|
||||
a specialization of pointer_to_other.</p>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<pre><em>// Let's define a memory allocator that can
|
||||
<p>If these definitions are not correct for a specific smart pointer, we can define
|
||||
a specialization of pointer_to_other.</p>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<pre><em>// Let's define a memory allocator that can
|
||||
// work with raw and smart pointers</em>
|
||||
|
||||
#include <boost/pointer_to_other.hpp>
|
||||
@ -97,12 +97,12 @@ class memory_allocator
|
||||
|
||||
block_ptr_t free_blocks;
|
||||
};</pre>
|
||||
<p>As we can see, using pointer_to_other we can create pointer independent code.</p>
|
||||
<hr>
|
||||
<p>Last revised: $Date$</p>
|
||||
<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>
|
||||
(See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or a
|
||||
copy at < <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>>.)</small></p>
|
||||
</body>
|
||||
<p>As we can see, using pointer_to_other we can create pointer independent code.</p>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<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>
|
||||
(See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or a
|
||||
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>
|
||||
|
||||
183
scoped_array.htm
183
scoped_array.htm
@ -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>
|
||||
<head>
|
||||
<title>scoped_array</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86"
|
||||
border="0"></A>scoped_array class template</h1>
|
||||
<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>
|
||||
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>
|
||||
<p>The <b>scoped_array</b> template is a simple solution for simple needs. It
|
||||
supplies a basic "resource acquisition is initialization" facility, without
|
||||
shared-ownership or transfer-of-ownership semantics. Both its name and
|
||||
enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
|
||||
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>,
|
||||
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
|
||||
operation is as fast as a built-in array pointer and it has no more space
|
||||
overhead that a built-in array pointer.</p>
|
||||
<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>
|
||||
<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>
|
||||
<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
|
||||
that does not use dynamic allocation.</p>
|
||||
<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">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
<head>
|
||||
<title>scoped_array</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
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
|
||||
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
|
||||
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
|
||||
supplies a basic "resource acquisition is initialization" facility, without
|
||||
shared-ownership or transfer-of-ownership semantics. Both its name and
|
||||
enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
|
||||
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>,
|
||||
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
|
||||
operation is as fast as a built-in array pointer and it has no more space
|
||||
overhead that a built-in array pointer.</p>
|
||||
<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>
|
||||
<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>
|
||||
<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
|
||||
that does not use dynamic allocation.</p>
|
||||
<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">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<class T> class scoped_array : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
|
||||
|
||||
@ -55,62 +55,61 @@
|
||||
template<class T> void <a href="#free-swap">swap</a>(scoped_array<T> & a, scoped_array<T> & b); // never throws
|
||||
|
||||
}</pre>
|
||||
<h2>Members</h2>
|
||||
<h3>
|
||||
<a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="ctor">constructors</a></h3>
|
||||
<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
|
||||
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">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~scoped_array(); // never throws</pre>
|
||||
<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
|
||||
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">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0); // never throws</pre>
|
||||
<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
|
||||
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
|
||||
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
|
||||
<h3><a name="operator[]">subscripting</a></h3>
|
||||
<pre>T & 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
|
||||
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
|
||||
number of elements in the array.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<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>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent
|
||||
to <code>get() != 0</code>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(scoped_array & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->
|
||||
09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310"--></p>
|
||||
<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
|
||||
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>
|
||||
<h2>Members</h2>
|
||||
<h3>
|
||||
<a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="ctor">constructors</a></h3>
|
||||
<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
|
||||
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">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~scoped_array(); // never throws</pre>
|
||||
<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
|
||||
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">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0); // never throws</pre>
|
||||
<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
|
||||
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
|
||||
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
|
||||
<h3><a name="operator[]">subscripting</a></h3>
|
||||
<pre>T & 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
|
||||
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
|
||||
number of elements in the array.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<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>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent
|
||||
to <code>get() != 0</code>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(scoped_array & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<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
|
||||
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>
|
||||
|
||||
271
scoped_ptr.htm
271
scoped_ptr.htm
@ -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>
|
||||
<head>
|
||||
<title>scoped_ptr</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86"
|
||||
border="0"></A>scoped_ptr class template</h1>
|
||||
<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.)
|
||||
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>
|
||||
<p>The <b>scoped_ptr</b> template is a simple solution for simple needs. It
|
||||
supplies a basic "resource acquisition is initialization" facility, without
|
||||
shared-ownership or transfer-of-ownership semantics. Both its name and
|
||||
enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
|
||||
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>,
|
||||
it is safer than <b>shared_ptr</b> or <b>std::auto_ptr</b> for pointers which
|
||||
should not be copied.</p>
|
||||
<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
|
||||
built-in pointer.</p>
|
||||
<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
|
||||
that can.</p>
|
||||
<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
|
||||
that usage.</p>
|
||||
<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">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
<head>
|
||||
<title>scoped_ptr</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
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
|
||||
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>,
|
||||
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
|
||||
supplies a basic "resource acquisition is initialization" facility, without
|
||||
shared-ownership or transfer-of-ownership semantics. Both its name and
|
||||
enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
|
||||
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>,
|
||||
it is safer than <b>shared_ptr</b> or <b>std::auto_ptr</b> for pointers which
|
||||
should not be copied.</p>
|
||||
<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
|
||||
built-in pointer.</p>
|
||||
<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
|
||||
that can.</p>
|
||||
<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
|
||||
that usage.</p>
|
||||
<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">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<class T> class scoped_ptr : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
|
||||
|
||||
@ -56,60 +56,60 @@
|
||||
template<class T> void <a href="#free-swap">swap</a>(scoped_ptr<T> & a, scoped_ptr<T> & b); // never throws
|
||||
|
||||
}</pre>
|
||||
<h2>Members</h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<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
|
||||
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
|
||||
requirements</a>.</p>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~scoped_ptr(); // never throws</pre>
|
||||
<p>Destroys the object pointed to by the stored pointer, if any, as if by using <tt>delete
|
||||
this->get()</tt>.</p>
|
||||
<P>
|
||||
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
|
||||
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</P>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0); // never throws</pre>
|
||||
<p>
|
||||
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
|
||||
guarantee that this does not throw exceptions depends on the requirement 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>
|
||||
<h3><a name="indirection">indirection</a></h3>
|
||||
<pre>T & operator*() const; // never throws</pre>
|
||||
<p>Returns a reference to the object pointed to by the stored pointer. Behavior is
|
||||
undefined if the stored pointer is 0.</p>
|
||||
<pre>T * operator->() const; // never throws</pre>
|
||||
<p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<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>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent
|
||||
to <code>get() != 0</code>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(scoped_ptr & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b); // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<p>Here's an example that uses <b>scoped_ptr</b>.</p>
|
||||
<blockquote>
|
||||
<pre>#include <boost/scoped_ptr.hpp>
|
||||
<h2>Members</h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<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
|
||||
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
|
||||
requirements</a>.</p>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~scoped_ptr(); // never throws</pre>
|
||||
<p>Destroys the object pointed to by the stored pointer, if any, as if by using <tt>delete
|
||||
this->get()</tt>.</p>
|
||||
<P>
|
||||
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
|
||||
pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</P>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0); // never throws</pre>
|
||||
<p>
|
||||
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
|
||||
guarantee that this does not throw exceptions depends on the requirement 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>
|
||||
<h3><a name="indirection">indirection</a></h3>
|
||||
<pre>T & operator*() const; // never throws</pre>
|
||||
<p>Returns a reference to the object pointed to by the stored pointer. Behavior is
|
||||
undefined if the stored pointer is 0.</p>
|
||||
<pre>T * operator->() const; // never throws</pre>
|
||||
<p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<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>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent
|
||||
to <code>get() != 0</code>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(scoped_ptr & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b); // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<p>Here's an example that uses <b>scoped_ptr</b>.</p>
|
||||
<blockquote>
|
||||
<pre>#include <boost/scoped_ptr.hpp>
|
||||
#include <iostream>
|
||||
|
||||
struct Shoe { ~Shoe() { std::cout << "Buckle my shoe\n"; } };
|
||||
@ -128,54 +128,53 @@ int main()
|
||||
std::cout << my_instance.add_one() << '\n';
|
||||
std::cout << my_instance.add_one() << '\n';
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<p>The example program produces the beginning of a child's nursery rhyme:</p>
|
||||
<blockquote>
|
||||
<pre>1
|
||||
</blockquote>
|
||||
<p>The example program produces the beginning of a child's nursery rhyme:</p>
|
||||
<blockquote>
|
||||
<pre>1
|
||||
2
|
||||
Buckle my shoe</pre>
|
||||
</blockquote>
|
||||
<h2>Rationale</h2>
|
||||
<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
|
||||
initialization" to be applied only for the current scope, and have no intent to
|
||||
transfer ownership.</p>
|
||||
<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>,
|
||||
because the maintenance programmer saw <b>auto_ptr</b>, and assumed ownership
|
||||
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>
|
||||
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>,
|
||||
you tell your readers what your intent is. Same with <b>scoped_ptr</b>; by
|
||||
using it you are signaling intent.</p>
|
||||
<p>It has been suggested that <b>scoped_ptr<T></b> is equivalent to <b>std::auto_ptr<T>
|
||||
const</b>. Ed Brey pointed out, however, that <b>reset</b> will not work on
|
||||
a <b>std::auto_ptr<T> const.</b></p>
|
||||
<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
|
||||
pimpl) idiom which avoids exposing the body (implementation) in the header
|
||||
file.</p>
|
||||
<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>,
|
||||
which uses a <b>scoped_ptr<></b> to an incomplete type to hide the
|
||||
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>
|
||||
implementation file.</p>
|
||||
<h2>Frequently Asked Questions</h2>
|
||||
<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
|
||||
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
|
||||
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
|
||||
is required. (supplied by Dave Abrahams)</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->
|
||||
09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310" --></p>
|
||||
<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
|
||||
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>
|
||||
</blockquote>
|
||||
<h2>Rationale</h2>
|
||||
<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
|
||||
initialization" to be applied only for the current scope, and have no intent to
|
||||
transfer ownership.</p>
|
||||
<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>,
|
||||
because the maintenance programmer saw <b>auto_ptr</b>, and assumed ownership
|
||||
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>
|
||||
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>,
|
||||
you tell your readers what your intent is. Same with <b>scoped_ptr</b>; by
|
||||
using it you are signaling intent.</p>
|
||||
<p>It has been suggested that <b>scoped_ptr<T></b> is equivalent to <b>std::auto_ptr<T>
|
||||
const</b>. Ed Brey pointed out, however, that <b>reset</b> will not work on
|
||||
a <b>std::auto_ptr<T> const.</b></p>
|
||||
<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
|
||||
pimpl) idiom which avoids exposing the body (implementation) in the header
|
||||
file.</p>
|
||||
<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>,
|
||||
which uses a <b>scoped_ptr<></b> to an incomplete type to hide the
|
||||
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>
|
||||
implementation file.</p>
|
||||
<h2>Frequently Asked Questions</h2>
|
||||
<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
|
||||
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
|
||||
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
|
||||
is required. (supplied by Dave Abrahams)</p>
|
||||
<hr>
|
||||
<p>$Date</p>
|
||||
<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
|
||||
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>
|
||||
|
||||
276
shared_array.htm
276
shared_array.htm
@ -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>
|
||||
<head>
|
||||
<title>shared_array</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86"
|
||||
border="0"></A>shared_array class template</h1>
|
||||
<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>
|
||||
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>
|
||||
<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
|
||||
library containers. Comparison operators are supplied so that <b>shared_array</b>
|
||||
works with the standard library's associative containers.</p>
|
||||
<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">
|
||||
<b>shared_ptr</b></a> for that usage.</p>
|
||||
<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>
|
||||
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>
|
||||
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>
|
||||
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
|
||||
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
<head>
|
||||
<title>shared_array</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
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
|
||||
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>
|
||||
pointing to it is destroyed or reset.</p>
|
||||
<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
|
||||
library containers. Comparison operators are supplied so that <b>shared_array</b>
|
||||
works with the standard library's associative containers.</p>
|
||||
<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">
|
||||
<b>shared_ptr</b></a> for that usage.</p>
|
||||
<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>
|
||||
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>
|
||||
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>
|
||||
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
|
||||
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<class T> class shared_array {
|
||||
|
||||
@ -68,118 +68,116 @@
|
||||
template<class T> void <a href="#free-swap">swap</a>(shared_array<T> & a, shared_array<T> & b); // never throws
|
||||
|
||||
}</pre>
|
||||
<h2>Members</h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<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
|
||||
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">
|
||||
~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>
|
||||
is called.</p>
|
||||
<pre>template<class D> 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>.
|
||||
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
|
||||
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
|
||||
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>
|
||||
<pre>shared_array(shared_array const & r); // never throws</pre>
|
||||
<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
|
||||
is 1 more than the initial use count.</p>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~shared_array(); // never throws</pre>
|
||||
<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
|
||||
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
|
||||
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>
|
||||
<h3><a name="assignment">assignment</a></h3>
|
||||
<pre>shared_array & operator=(shared_array const & r); // never throws</pre>
|
||||
<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
|
||||
replaced object.</p>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0);</pre>
|
||||
<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
|
||||
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>
|
||||
<pre>template<class D> void reset(T * p, D d);</pre>
|
||||
<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
|
||||
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>
|
||||
is called.</p>
|
||||
<h3><a name="indexing">indexing</a></h3>
|
||||
<pre>T & 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
|
||||
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
|
||||
number of elements in the array.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<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>
|
||||
<h3><a name="unique">unique</a></h3>
|
||||
<pre>bool unique() const; // never throws</pre>
|
||||
<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 <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
|
||||
<h3><a name="use_count">use_count</a></h3>
|
||||
<pre>long use_count() const; // never throws</pre>
|
||||
<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">
|
||||
common requirements</a>.</p>
|
||||
<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
|
||||
count, it might be removed from some future version. Thus it should be used for
|
||||
debugging purposes only, and not production code.</p>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent
|
||||
to <code>get() != 0</code>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(shared_ptr & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="comparison">comparison</a></h3>
|
||||
<pre>template<class T>
|
||||
<h2>Members</h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<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
|
||||
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">
|
||||
~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>
|
||||
is called.</p>
|
||||
<pre>template<class D> 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>.
|
||||
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
|
||||
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
|
||||
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>
|
||||
<pre>shared_array(shared_array const & r); // never throws</pre>
|
||||
<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
|
||||
is 1 more than the initial use count.</p>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~shared_array(); // never throws</pre>
|
||||
<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
|
||||
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
|
||||
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>
|
||||
<h3><a name="assignment">assignment</a></h3>
|
||||
<pre>shared_array & operator=(shared_array const & r); // never throws</pre>
|
||||
<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
|
||||
replaced object.</p>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0);</pre>
|
||||
<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
|
||||
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>
|
||||
<pre>template<class D> void reset(T * p, D d);</pre>
|
||||
<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
|
||||
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>
|
||||
is called.</p>
|
||||
<h3><a name="indexing">indexing</a></h3>
|
||||
<pre>T & 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
|
||||
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
|
||||
number of elements in the array.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<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>
|
||||
<h3><a name="unique">unique</a></h3>
|
||||
<pre>bool unique() const; // never throws</pre>
|
||||
<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 <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
|
||||
<h3><a name="use_count">use_count</a></h3>
|
||||
<pre>long use_count() const; // never throws</pre>
|
||||
<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">
|
||||
common requirements</a>.</p>
|
||||
<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
|
||||
count, it might be removed from some future version. Thus it should be used for
|
||||
debugging purposes only, and not production code.</p>
|
||||
<h3><a name="conversions">conversions</a></h3>
|
||||
<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
|
||||
<p>Returns an unspecified value that, when used in boolean contexts, is equivalent
|
||||
to <code>get() != 0</code>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(shared_ptr & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="comparison">comparison</a></h3>
|
||||
<pre>template<class T>
|
||||
bool operator==(shared_array<T> const & a, shared_array<T> const & b); // never throws
|
||||
template<class T>
|
||||
bool operator!=(shared_array<T> const & a, shared_array<T> const & b); // never throws
|
||||
template<class T>
|
||||
bool operator<(shared_array<T> const & a, shared_array<T> const & b); // never throws</pre>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<p>The <b>operator<</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
|
||||
implementation uses <b>std::less<T *></b> to perform the comparison. This
|
||||
ensures that the comparison is handled correctly, since the standard mandates
|
||||
that relational operations on pointers are unspecified (5.9 [expr.rel]
|
||||
paragraph 2) but <b>std::less<></b> on pointers is well-defined (20.3.3
|
||||
[lib.comparisons] paragraph 8).</p>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T>
|
||||
<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
|
||||
requirements</a>.</p>
|
||||
<p>The <b>operator<</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
|
||||
implementation uses <b>std::less<T *></b> to perform the comparison. This
|
||||
ensures that the comparison is handled correctly, since the standard mandates
|
||||
that relational operations on pointers are unspecified (5.9 [expr.rel]
|
||||
paragraph 2) but <b>std::less<></b> on pointers is well-defined (20.3.3
|
||||
[lib.comparisons] paragraph 8).</p>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T>
|
||||
void swap(shared_array<T> & a, shared_array<T> & b) // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->
|
||||
09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310" --></p>
|
||||
<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
|
||||
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>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<hr>
|
||||
<p>$Date</p>
|
||||
<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
|
||||
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>
|
||||
|
||||
1216
shared_ptr.htm
1216
shared_ptr.htm
File diff suppressed because it is too large
Load Diff
431
smart_ptr.htm
431
smart_ptr.htm
@ -1,216 +1,221 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Smart Pointers</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86"
|
||||
border="0"></A>Smart Pointers</h1>
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#common_requirements">Common Requirements</a><br>
|
||||
<a href="#Exception_Safety">Exception Safety</a><br>
|
||||
<a href="#Exception-specifications">Exception-specifications</a><br>
|
||||
<a href="#History">History and Acknowledgements</a><br>
|
||||
<a href="#References">References</a></p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Smart pointers are objects which store pointers to dynamically allocated (heap)
|
||||
objects. They behave much like built-in C++ pointers except that they
|
||||
automatically delete the object pointed to at the appropriate time. Smart
|
||||
pointers are particularly useful in the face of exceptions as they ensure
|
||||
proper destruction of dynamically allocated objects. They can also be used to
|
||||
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
|
||||
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>
|
||||
<div align="left">
|
||||
<table border="1" cellpadding="4" cellspacing="0">
|
||||
<tr>
|
||||
<td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td>
|
||||
<td><a href="../../boost/scoped_ptr.hpp"><boost/scoped_ptr.hpp></a></td>
|
||||
<td>Simple sole ownership of single objects. Noncopyable.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="scoped_array.htm"><b>scoped_array</b></a></td>
|
||||
<td><a href="../../boost/scoped_array.hpp"><boost/scoped_array.hpp></a></td>
|
||||
<td>Simple sole ownership of arrays. Noncopyable.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
|
||||
<td><a href="../../boost/shared_ptr.hpp"><boost/shared_ptr.hpp></a></td>
|
||||
<td>Object ownership shared among multiple pointers.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="shared_array.htm"><b>shared_array</b></a></td>
|
||||
<td><a href="../../boost/shared_array.hpp"><boost/shared_array.hpp></a></td>
|
||||
<td>Array ownership shared among multiple pointers.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td>
|
||||
<td><a href="../../boost/weak_ptr.hpp"><boost/weak_ptr.hpp></a></td>
|
||||
<td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="intrusive_ptr.html"><b>intrusive_ptr</b></a></td>
|
||||
<td><a href="../../boost/intrusive_ptr.hpp"><boost/intrusive_ptr.hpp></a></td>
|
||||
<td>Shared ownership of objects with an embedded reference count.</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<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
|
||||
described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition,
|
||||
Section 14.4, Resource Management.</p>
|
||||
<p>Additionally, the smart pointer library provides efficient factory functions
|
||||
for creating smart pointer objects:</p>
|
||||
<div align="left">
|
||||
<table border="1" cellpadding="4" cellspacing="0">
|
||||
<tr>
|
||||
<td><a href="make_shared.html"><b>make_shared and allocate_shared for objects</b></a></td>
|
||||
<td><a href="../../boost/make_shared.hpp"><boost/make_shared.hpp></a></td>
|
||||
<td>Efficient creation of <code>shared_ptr</code> objects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="make_shared_array.html"><b>make_shared and allocate_shared for arrays</b></a></td>
|
||||
<td><a href="../../boost/make_shared.hpp"><boost/make_shared.hpp></a></td>
|
||||
<td>Efficient creation of <code>shared_ptr</code> arrays.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="make_unique.html"><b>make_unique</b></a></td>
|
||||
<td><a href="../../boost/make_unique.hpp"><boost/make_unique.hpp></a></td>
|
||||
<td>Creation of <code>unique_ptr</code> objects and arrays.</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
|
||||
provided to verify correct operation.</p>
|
||||
<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
|
||||
versions of the smart pointer implementation.</p>
|
||||
<p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of interest
|
||||
to those curious about performance issues.</p>
|
||||
<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>
|
||||
<h2><a name="common_requirements">Common Requirements</a></h2>
|
||||
<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
|
||||
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>
|
||||
<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
|
||||
points of smart pointer instantiation. Implementations are required to diagnose
|
||||
(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">
|
||||
<b>checked_delete</b></a> function template.</p>
|
||||
<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>
|
||||
<h3>Rationale</h3>
|
||||
<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
|
||||
pointer may appear in translation units where <b>T</b> is an incomplete type.
|
||||
This separates interface from implementation and hides implementation from
|
||||
translation units which merely use the interface. Examples described in the
|
||||
documentation for specific smart pointers illustrate use of smart pointers in
|
||||
these idioms.</p>
|
||||
<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>
|
||||
<h2><a name="Exception_Safety">Exception Safety</a></h2>
|
||||
<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
|
||||
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
|
||||
which resulted in the exception being thrown. This amounts to a guarantee that
|
||||
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 <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
|
||||
possibly throwing <b>std::bad_alloc</b>.</p>
|
||||
<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">
|
||||
exception-specification rationale</a>.</p>
|
||||
<p>All the smart pointer templates contain member functions which can never throw
|
||||
exceptions, because they neither throw exceptions themselves nor call other
|
||||
functions which may throw exceptions. These members are indicated by a comment: <code>
|
||||
// never throws</code>.
|
||||
</p>
|
||||
<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>
|
||||
<h2><a name="History">History</a> and Acknowledgements</h2>
|
||||
<p>January 2014. Glen Fernandes confined the overloads of <b>make_shared</b>
|
||||
and <b>allocate_shared</b> for arrays to the specification in
|
||||
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html">N3870</a>
|
||||
and implemented <b>make_unique</b> for arrays and objects.</p>
|
||||
<p>November 2012. Glen Fernandes provided implementations of <b>make_shared</b>
|
||||
and <b>allocate_shared</b> for arrays. They achieve a single allocation for an
|
||||
array that can be initialized with constructor arguments or initializer lists
|
||||
as well as overloads for default initialization and no value initialization.
|
||||
See the <a href="make_shared_array.html">make_shared and allocate_shared for
|
||||
arrays</a> page for more information.</p>
|
||||
<p>January 2002. Peter Dimov reworked all four classes, adding features, fixing
|
||||
bugs, and splitting them into four separate headers, and added <b>weak_ptr</b>.
|
||||
See the <a href="compatibility.htm">compatibility</a> page for a summary of the
|
||||
changes.</p>
|
||||
<p>May 2001. Vladimir Prus suggested requiring a complete type on destruction.
|
||||
Refinement evolved in discussions including Dave Abrahams, Greg Colvin, Beman
|
||||
Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, Shankar Sai, and
|
||||
others.</p>
|
||||
<p>November 1999. Darin Adler provided <b>operator ==</b>, <b>operator !=</b>, and <b>std::swap</b>
|
||||
and <b>std::less</b> specializations for shared types.</p>
|
||||
<p>September 1999. Luis Coelho provided <b>shared_ptr::swap</b> and <b>shared_array::swap</b></p>
|
||||
<p>May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a
|
||||
number of suggestions resulting in numerous improvements.</p>
|
||||
<p>October 1998. Beman Dawes proposed reviving the original semantics under the
|
||||
names <b>safe_ptr</b> and <b>counted_ptr</b>, meeting of Per Andersson, Matt
|
||||
Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar Kühl,
|
||||
Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new
|
||||
class names were finalized, it was decided that there was no need to exactly
|
||||
follow the <b>std::auto_ptr</b> interface, and various function signatures and
|
||||
semantics were finalized.</p>
|
||||
<p>Over the next three months, several implementations were considered for <b>shared_ptr</b>,
|
||||
and discussed on the <a href="http://www.boost.org">boost.org</a> mailing list.
|
||||
The implementation questions revolved around the reference count which must be
|
||||
kept, either attached to the pointed to object, or detached elsewhere. Each of
|
||||
those variants have themselves two major variants:
|
||||
<ul>
|
||||
<li>
|
||||
Direct detached: the shared_ptr contains a pointer to the object, and a pointer
|
||||
to the count.
|
||||
<li>
|
||||
Indirect detached: the shared_ptr contains a pointer to a helper object, which
|
||||
in turn contains a pointer to the object and the count.
|
||||
<li>
|
||||
Embedded attached: the count is a member of the object pointed to.
|
||||
<li>
|
||||
Placement attached: the count is attached via operator new manipulations.</li>
|
||||
</ul>
|
||||
<p>Each implementation technique has advantages and disadvantages. We went so far
|
||||
as to run various timings of the direct and indirect approaches, and found that
|
||||
at least on Intel Pentium chips there was very little measurable difference.
|
||||
Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar
|
||||
Kühl suggested an elegant partial template specialization technique to allow
|
||||
users to choose which implementation they preferred, and that was also
|
||||
experimented with.</p>
|
||||
<p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage
|
||||
users", and in the end we choose to supply only the direct implementation.</p>
|
||||
<p>Summer, 1994. Greg Colvin proposed to the C++ Standards Committee classes named <b>auto_ptr</b>
|
||||
and <b>counted_ptr</b> which were very similar to what we now call <b>scoped_ptr</b>
|
||||
and <b>shared_ptr</b>. <a href="#Col-94">[Col-94]</a> In one of the very few
|
||||
cases where the Library Working Group's recommendations were not followed by
|
||||
the full committee, <b>counted_ptr</b> was rejected and surprising
|
||||
transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p>
|
||||
<h2><a name="References">References</a></h2>
|
||||
<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">
|
||||
Exception Safe Smart Pointers</a>, C++ committee document 94-168/N0555,
|
||||
July, 1994.</p>
|
||||
<p>[<a name="E&D-94">E&D-94</a>] John R. Ellis & David L. Detlefs, <a href="http://www.usenix.org/publications/library/proceedings/c++94/full_papers/ellis.a">
|
||||
Safe, Efficient Garbage Collection for C++</a>, Usenix Proceedings,
|
||||
February, 1994. This paper includes an extensive discussion of weak pointers
|
||||
and an extensive bibliography.</p>
|
||||
<hr>
|
||||
<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>
|
||||
<head>
|
||||
<title>Smart Pointers</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">Smart Pointers</h1>
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#common_requirements">Common Requirements</a><br>
|
||||
<a href="#Exception_Safety">Exception Safety</a><br>
|
||||
<a href="#Exception-specifications">Exception-specifications</a><br>
|
||||
<a href="#History">History and Acknowledgements</a><br>
|
||||
<a href="#References">References</a></p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Smart pointers are objects which store pointers to dynamically allocated (heap)
|
||||
objects. They behave much like built-in C++ pointers except that they
|
||||
automatically delete the object pointed to at the appropriate time. Smart
|
||||
pointers are particularly useful in the face of exceptions as they ensure
|
||||
proper destruction of dynamically allocated objects. They can also be used to
|
||||
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
|
||||
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>
|
||||
<div align="left">
|
||||
<table border="1" cellpadding="4" cellspacing="0">
|
||||
<tr>
|
||||
<td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td>
|
||||
<td><a href="../../boost/scoped_ptr.hpp"><boost/scoped_ptr.hpp></a></td>
|
||||
<td>Simple sole ownership of single objects. Noncopyable.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="scoped_array.htm"><b>scoped_array</b></a></td>
|
||||
<td><a href="../../boost/scoped_array.hpp"><boost/scoped_array.hpp></a></td>
|
||||
<td>Simple sole ownership of arrays. Noncopyable.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
|
||||
<td><a href="../../boost/shared_ptr.hpp"><boost/shared_ptr.hpp></a></td>
|
||||
<td>Object ownership shared among multiple pointers.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="shared_array.htm"><b>shared_array</b></a></td>
|
||||
<td><a href="../../boost/shared_array.hpp"><boost/shared_array.hpp></a></td>
|
||||
<td>Array ownership shared among multiple pointers.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td>
|
||||
<td><a href="../../boost/weak_ptr.hpp"><boost/weak_ptr.hpp></a></td>
|
||||
<td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="intrusive_ptr.html"><b>intrusive_ptr</b></a></td>
|
||||
<td><a href="../../boost/intrusive_ptr.hpp"><boost/intrusive_ptr.hpp></a></td>
|
||||
<td>Shared ownership of objects with an embedded reference count.</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<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
|
||||
described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition,
|
||||
Section 14.4, Resource Management.</p>
|
||||
<p>Additionally, the smart pointer library provides efficient factory functions
|
||||
for creating smart pointer objects:</p>
|
||||
<div align="left">
|
||||
<table border="1" cellpadding="4" cellspacing="0">
|
||||
<tr>
|
||||
<td><a href="make_shared.html"><b>make_shared, allocate_shared</b></a> for objects</td>
|
||||
<td><a href="../../boost/make_shared.hpp"><boost/make_shared.hpp></a></td>
|
||||
<td>Efficient creation of <code>shared_ptr</code> objects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="make_shared_array.html"><b>make_shared, allocate_shared</b></a> for arrays</td>
|
||||
<td><a href="../../boost/make_shared.hpp"><boost/make_shared.hpp></a></td>
|
||||
<td>Efficient creation of <code>shared_ptr</code> arrays.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="make_unique.html"><b>make_unique</b></a></td>
|
||||
<td><a href="../../boost/make_unique.hpp"><boost/make_unique.hpp></a></td>
|
||||
<td>Creation of <code>unique_ptr</code> objects and arrays.</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
|
||||
provided to verify correct operation.</p>
|
||||
<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
|
||||
versions of the smart pointer implementation.</p>
|
||||
<p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of interest
|
||||
to those curious about performance issues.</p>
|
||||
<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>
|
||||
<h2><a name="common_requirements">Common Requirements</a></h2>
|
||||
<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
|
||||
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>
|
||||
<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
|
||||
points of smart pointer instantiation. Implementations are required to diagnose
|
||||
(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">
|
||||
<b>checked_delete</b></a> function template.</p>
|
||||
<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>
|
||||
<h3>Rationale</h3>
|
||||
<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
|
||||
pointer may appear in translation units where <b>T</b> is an incomplete type.
|
||||
This separates interface from implementation and hides implementation from
|
||||
translation units which merely use the interface. Examples described in the
|
||||
documentation for specific smart pointers illustrate use of smart pointers in
|
||||
these idioms.</p>
|
||||
<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>
|
||||
<h2><a name="Exception_Safety">Exception Safety</a></h2>
|
||||
<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
|
||||
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
|
||||
which resulted in the exception being thrown. This amounts to a guarantee that
|
||||
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 <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
|
||||
possibly throwing <b>std::bad_alloc</b>.</p>
|
||||
<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">
|
||||
exception-specification rationale</a>.</p>
|
||||
<p>All the smart pointer templates contain member functions which can never throw
|
||||
exceptions, because they neither throw exceptions themselves nor call other
|
||||
functions which may throw exceptions. These members are indicated by a comment: <code>
|
||||
// never throws</code>.
|
||||
</p>
|
||||
<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>
|
||||
<h2><a name="History">History</a> and Acknowledgements</h2>
|
||||
<p>February 2014. Glen Fernandes updated overloads of <b>make_shared</b> and
|
||||
<b>allocate_shared</b> to conform to the specification in C++ standard paper
|
||||
<a href="#D&F-14">[D&F-14]</a>, and implemented <b>make_unique</b> for
|
||||
arrays and objects. Peter Dimov and Glen Fernandes updated the scalar and
|
||||
array implementations, respectively, to resolve C++ standard library defect
|
||||
2070.</p>
|
||||
<p>November 2012. Glen Fernandes provided implementations of <b>make_shared</b>
|
||||
and <b>allocate_shared</b> for arrays. They achieve a single allocation for an
|
||||
array that can be initialized with constructor arguments or initializer lists
|
||||
as well as overloads for default initialization and no value initialization.
|
||||
See the <a href="make_shared_array.html">make_shared and allocate_shared for
|
||||
arrays</a> page for more information.</p>
|
||||
<p>January 2002. Peter Dimov reworked all four classes, adding features, fixing
|
||||
bugs, and splitting them into four separate headers, and added <b>weak_ptr</b>.
|
||||
See the <a href="compatibility.htm">compatibility</a> page for a summary of the
|
||||
changes.</p>
|
||||
<p>May 2001. Vladimir Prus suggested requiring a complete type on destruction.
|
||||
Refinement evolved in discussions including Dave Abrahams, Greg Colvin, Beman
|
||||
Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, Shankar Sai, and
|
||||
others.</p>
|
||||
<p>November 1999. Darin Adler provided <b>operator ==</b>, <b>operator !=</b>, and <b>std::swap</b>
|
||||
and <b>std::less</b> specializations for shared types.</p>
|
||||
<p>September 1999. Luis Coelho provided <b>shared_ptr::swap</b> and <b>shared_array::swap</b></p>
|
||||
<p>May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a
|
||||
number of suggestions resulting in numerous improvements.</p>
|
||||
<p>October 1998. Beman Dawes proposed reviving the original semantics under the
|
||||
names <b>safe_ptr</b> and <b>counted_ptr</b>, meeting of Per Andersson, Matt
|
||||
Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar Kühl,
|
||||
Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new
|
||||
class names were finalized, it was decided that there was no need to exactly
|
||||
follow the <b>std::auto_ptr</b> interface, and various function signatures and
|
||||
semantics were finalized.</p>
|
||||
<p>Over the next three months, several implementations were considered for <b>shared_ptr</b>,
|
||||
and discussed on the <a href="http://www.boost.org">boost.org</a> mailing list.
|
||||
The implementation questions revolved around the reference count which must be
|
||||
kept, either attached to the pointed to object, or detached elsewhere. Each of
|
||||
those variants have themselves two major variants:
|
||||
<ul>
|
||||
<li>
|
||||
Direct detached: the shared_ptr contains a pointer to the object, and a pointer
|
||||
to the count.
|
||||
<li>
|
||||
Indirect detached: the shared_ptr contains a pointer to a helper object, which
|
||||
in turn contains a pointer to the object and the count.
|
||||
<li>
|
||||
Embedded attached: the count is a member of the object pointed to.
|
||||
<li>
|
||||
Placement attached: the count is attached via operator new manipulations.</li>
|
||||
</ul>
|
||||
<p>Each implementation technique has advantages and disadvantages. We went so far
|
||||
as to run various timings of the direct and indirect approaches, and found that
|
||||
at least on Intel Pentium chips there was very little measurable difference.
|
||||
Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar
|
||||
Kühl suggested an elegant partial template specialization technique to allow
|
||||
users to choose which implementation they preferred, and that was also
|
||||
experimented with.</p>
|
||||
<p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage
|
||||
users", and in the end we choose to supply only the direct implementation.</p>
|
||||
<p>Summer, 1994. Greg Colvin proposed to the C++ Standards Committee classes named <b>auto_ptr</b>
|
||||
and <b>counted_ptr</b> which were very similar to what we now call <b>scoped_ptr</b>
|
||||
and <b>shared_ptr</b>. <a href="#Col-94">[Col-94]</a> In one of the very few
|
||||
cases where the Library Working Group's recommendations were not followed by
|
||||
the full committee, <b>counted_ptr</b> was rejected and surprising
|
||||
transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p>
|
||||
<h2><a name="References">References</a></h2>
|
||||
<p>[<a name="D&F-14">D&F-14</a>] Peter Dimov & Glen Fernandes, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html">
|
||||
Extending make_shared to Support Arrays, Revision 1</a>, C++ committee document N3870,
|
||||
January, 2014.</p>
|
||||
<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">
|
||||
Exception Safe Smart Pointers</a>, C++ committee document 94-168/N0555,
|
||||
July, 1994.</p>
|
||||
<p>[<a name="E&D-94">E&D-94</a>] John R. Ellis & David L. Detlefs, <a href="http://www.usenix.org/publications/library/proceedings/c++94/full_papers/ellis.a">
|
||||
Safe, Efficient Garbage Collection for C++</a>, Usenix Proceedings,
|
||||
February, 1994. This paper includes an extensive discussion of weak pointers
|
||||
and an extensive bibliography.</p>
|
||||
<hr>
|
||||
<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>
|
||||
|
||||
@ -7,9 +7,9 @@
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" WIDTH="277" HEIGHT="86">Smart Pointer Timings</h1>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
|
||||
<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
|
||||
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>
|
||||
</ul>
|
||||
<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>
|
||||
<p><EFBFBD> Copyright Gavin Collings 2000. Permission to copy, use, modify, sell
|
||||
<p>$Date$</p>
|
||||
<p>© Copyright Gavin Collings 2000. Permission to copy, use, modify, sell
|
||||
and distribute this document is granted provided this copyright notice appears in all
|
||||
copies. This document is provided "as is" without express or implied warranty,
|
||||
and with no claim as to its suitability for any purpose.</p>
|
||||
|
||||
@ -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>
|
||||
<head>
|
||||
<title>Smart Pointer Programming Techniques</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgColor="#ffffff">
|
||||
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
|
||||
border="0"></A>Smart Pointer Programming Techniques</h1>
|
||||
<p><A href="#incomplete">Using incomplete classes for implementation hiding</A><br>
|
||||
<A href="#pimpl">The "Pimpl" idiom</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="#array">Using a <code>shared_ptr</code> to hold a pointer to an array</A><br>
|
||||
<A href="#encapsulation">Encapsulating allocation details, wrapping factory
|
||||
functions</A><br>
|
||||
<A href="#static">Using a <code>shared_ptr</code> to hold a pointer to a statically
|
||||
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="#intrusive">Using a <code>shared_ptr</code> to hold a pointer to an object
|
||||
with an embedded reference count</A><br>
|
||||
<A href="#another_sp">Using a <code>shared_ptr</code> to hold another shared
|
||||
ownership smart 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>)
|
||||
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="#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
|
||||
exit</A><br>
|
||||
<A href="#pvoid">Using <code>shared_ptr<void></code> to hold an arbitrary
|
||||
object</A><br>
|
||||
<A href="#extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code>
|
||||
instances</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="#delayed">Delayed deallocation</A><br>
|
||||
<A href="#weak_without_shared">Weak pointers to objects not managed by a <code>shared_ptr</code></A><br>
|
||||
</p>
|
||||
<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
|
||||
implementation is to use a pointer to an incomplete class as an opaque handle:</p>
|
||||
<pre>class FILE;
|
||||
<head>
|
||||
<title>Smart Pointer Programming Techniques</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">Smart Pointer Programming Techniques</h1>
|
||||
<p><A href="#incomplete">Using incomplete classes for implementation hiding</A><br>
|
||||
<A href="#pimpl">The "Pimpl" idiom</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="#array">Using a <code>shared_ptr</code> to hold a pointer to an array</A><br>
|
||||
<A href="#encapsulation">Encapsulating allocation details, wrapping factory
|
||||
functions</A><br>
|
||||
<A href="#static">Using a <code>shared_ptr</code> to hold a pointer to a statically
|
||||
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="#intrusive">Using a <code>shared_ptr</code> to hold a pointer to an object
|
||||
with an embedded reference count</A><br>
|
||||
<A href="#another_sp">Using a <code>shared_ptr</code> to hold another shared
|
||||
ownership smart 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>)
|
||||
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="#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
|
||||
exit</A><br>
|
||||
<A href="#pvoid">Using <code>shared_ptr<void></code> to hold an arbitrary
|
||||
object</A><br>
|
||||
<A href="#extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code>
|
||||
instances</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="#delayed">Delayed deallocation</A><br>
|
||||
<A href="#weak_without_shared">Weak pointers to objects not managed by a <code>shared_ptr</code></A><br>
|
||||
</p>
|
||||
<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
|
||||
implementation is to use a pointer to an incomplete class as an opaque handle:</p>
|
||||
<pre>class FILE;
|
||||
|
||||
FILE * fopen(char const * name, char const * mode);
|
||||
void fread(FILE * f, void * data, size_t size);
|
||||
void fclose(FILE * f);
|
||||
</pre>
|
||||
<p>It is possible to express the above interface using <code>shared_ptr</code>,
|
||||
eliminating the need to manually call <code>fclose</code>:</p>
|
||||
<pre>class FILE;
|
||||
<p>It is possible to express the above interface using <code>shared_ptr</code>,
|
||||
eliminating the need to manually call <code>fclose</code>:</p>
|
||||
<pre>class FILE;
|
||||
|
||||
shared_ptr<FILE> fopen(char const * name, char const * mode);
|
||||
void fread(shared_ptr<FILE> f, void * data, size_t size);
|
||||
</pre>
|
||||
<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
|
||||
that <code>shared_ptr<X></code> can be copied and destroyed when <code>X</code>
|
||||
is incomplete.</p>
|
||||
<h2><A name="pimpl">The "Pimpl" idiom</A></h2>
|
||||
<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
|
||||
forwarding facade. <code>shared_ptr</code> can be used to implement a "Pimpl":</p>
|
||||
<pre>// file.hpp:
|
||||
<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
|
||||
that <code>shared_ptr<X></code> can be copied and destroyed when <code>X</code>
|
||||
is incomplete.</p>
|
||||
<h2><A name="pimpl">The "Pimpl" idiom</A></h2>
|
||||
<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
|
||||
forwarding facade. <code>shared_ptr</code> can be used to implement a "Pimpl":</p>
|
||||
<pre>// file.hpp:
|
||||
|
||||
class file
|
||||
{
|
||||
@ -79,7 +79,7 @@ public:
|
||||
void read(void * data, size_t size);
|
||||
};
|
||||
</pre>
|
||||
<pre>// file.cpp:
|
||||
<pre>// file.cpp:
|
||||
|
||||
#include "file.hpp"
|
||||
|
||||
@ -108,17 +108,17 @@ void file::read(void * data, size_t size)
|
||||
pimpl_->read(data, size);
|
||||
}
|
||||
</pre>
|
||||
<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>
|
||||
file</code> is <code>CopyConstructible</code> and <code>Assignable</code>,
|
||||
allowing its use in standard containers.</p>
|
||||
<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
|
||||
use abstract base classes and factory functions. The abstract classes are
|
||||
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
|
||||
the factory functions:</p>
|
||||
<pre>// X.hpp:
|
||||
<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>
|
||||
file</code> is <code>CopyConstructible</code> and <code>Assignable</code>,
|
||||
allowing its use in standard containers.</p>
|
||||
<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
|
||||
use abstract base classes and factory functions. The abstract classes are
|
||||
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
|
||||
the factory functions:</p>
|
||||
<pre>// X.hpp:
|
||||
|
||||
class X
|
||||
{
|
||||
@ -134,7 +134,7 @@ protected:
|
||||
|
||||
shared_ptr<X> createX();
|
||||
</pre>
|
||||
<pre>-- X.cpp:
|
||||
<pre>-- X.cpp:
|
||||
|
||||
class X_impl: public X
|
||||
{
|
||||
@ -162,18 +162,18 @@ shared_ptr<X> createX()
|
||||
return px;
|
||||
}
|
||||
</pre>
|
||||
<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
|
||||
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>;
|
||||
the <code>shared_ptr<X></code> instance returned from <code>createX</code>
|
||||
will correctly call <code>~X_impl</code>.</p>
|
||||
<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
|
||||
being managed by <code>shared_ptr</code>. The previous technique showed one
|
||||
possible approach, using a protected destructor. Another alternative is to use
|
||||
a private deleter:</p>
|
||||
<pre>class X
|
||||
<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
|
||||
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>;
|
||||
the <code>shared_ptr<X></code> instance returned from <code>createX</code>
|
||||
will correctly call <code>~X_impl</code>.</p>
|
||||
<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
|
||||
being managed by <code>shared_ptr</code>. The previous technique showed one
|
||||
possible approach, using a protected destructor. Another alternative is to use
|
||||
a private deleter:</p>
|
||||
<pre>class X
|
||||
{
|
||||
private:
|
||||
|
||||
@ -198,48 +198,48 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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
|
||||
with <code>new[]</code>:</p>
|
||||
<pre>shared_ptr<X> px(new X[1], <A href="../utility/checked_delete.html" >checked_array_deleter</A><X>());
|
||||
<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
|
||||
with <code>new[]</code>:</p>
|
||||
<pre>shared_ptr<X> px(new X[1], <A href="../utility/checked_delete.html" >checked_array_deleter</A><X>());
|
||||
</pre>
|
||||
<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,
|
||||
without <code>operator*</code> and <code>operator-></code>, and does not
|
||||
allow pointer conversions.</p>
|
||||
<h2><A name="encapsulation">Encapsulating allocation details, wrapping factory
|
||||
functions</A></h2>
|
||||
<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
|
||||
to encapsulate allocation details. As an example, consider this interface,
|
||||
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>
|
||||
<pre>X * CreateX();
|
||||
<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,
|
||||
without <code>operator*</code> and <code>operator-></code>, and does not
|
||||
allow pointer conversions.</p>
|
||||
<h2><A name="encapsulation">Encapsulating allocation details, wrapping factory
|
||||
functions</A></h2>
|
||||
<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
|
||||
to encapsulate allocation details. As an example, consider this interface,
|
||||
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>
|
||||
<pre>X * CreateX();
|
||||
void DestroyX(X *);
|
||||
</pre>
|
||||
<p>The only way to reliably destroy a pointer returned by <code>CreateX</code> is
|
||||
to call <code>DestroyX</code>.</p>
|
||||
<P>Here is how a <code>shared_ptr</code>-based wrapper may look like:</P>
|
||||
<pre>shared_ptr<X> createX()
|
||||
<p>The only way to reliably destroy a pointer returned by <code>CreateX</code> is
|
||||
to call <code>DestroyX</code>.</p>
|
||||
<P>Here is how a <code>shared_ptr</code>-based wrapper may look like:</P>
|
||||
<pre>shared_ptr<X> createX()
|
||||
{
|
||||
shared_ptr<X> px(CreateX(), DestroyX);
|
||||
return px;
|
||||
}
|
||||
</pre>
|
||||
<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>
|
||||
<h2><A name="static">Using a <code>shared_ptr</code> to hold a pointer to a statically
|
||||
allocated object</A></h2>
|
||||
<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
|
||||
destroy the object when there are no more references left. As an example, the
|
||||
factory function:</p>
|
||||
<pre>shared_ptr<X> createX();
|
||||
<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>
|
||||
<h2><A name="static">Using a <code>shared_ptr</code> to hold a pointer to a statically
|
||||
allocated object</A></h2>
|
||||
<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
|
||||
destroy the object when there are no more references left. As an example, the
|
||||
factory function:</p>
|
||||
<pre>shared_ptr<X> createX();
|
||||
</pre>
|
||||
<p>in certain situations may need to return a pointer to a statically allocated <code>X</code>
|
||||
instance.</p>
|
||||
<P>The solution is to use a custom deleter that does nothing:</P>
|
||||
<pre>struct null_deleter
|
||||
<p>in certain situations may need to return a pointer to a statically allocated <code>X</code>
|
||||
instance.</p>
|
||||
<P>The solution is to use a custom deleter that does nothing:</P>
|
||||
<pre>struct null_deleter
|
||||
{
|
||||
void operator()(void const *) const
|
||||
{
|
||||
@ -254,33 +254,33 @@ shared_ptr<X> createX()
|
||||
return px;
|
||||
}
|
||||
</pre>
|
||||
<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>
|
||||
<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>
|
||||
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>
|
||||
<pre>shared_ptr<IWhatever> make_shared_from_COM(IWhatever * 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>
|
||||
<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>
|
||||
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>
|
||||
<pre>shared_ptr<IWhatever> make_shared_from_COM(IWhatever * p)
|
||||
{
|
||||
p->AddRef();
|
||||
shared_ptr<IWhatever> pw(p, <A href="../bind/mem_fn.html" >mem_fn</A>(&IWhatever::Release));
|
||||
return pw;
|
||||
}
|
||||
</pre>
|
||||
<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
|
||||
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>
|
||||
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,
|
||||
you need to <A href="../bind/mem_fn.html#stdcall">#define
|
||||
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
|
||||
with an embedded reference count</A></h2>
|
||||
<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>,
|
||||
<code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code>:</p>
|
||||
<pre>template<class T> struct intrusive_deleter
|
||||
<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
|
||||
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>
|
||||
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,
|
||||
you need to <A href="../bind/mem_fn.html#stdcall">#define
|
||||
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
|
||||
with an embedded reference count</A></h2>
|
||||
<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>,
|
||||
<code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code>:</p>
|
||||
<pre>template<class T> struct intrusive_deleter
|
||||
{
|
||||
void operator()(T * p)
|
||||
{
|
||||
@ -295,15 +295,15 @@ shared_ptr<X> make_shared_from_intrusive(X * p)
|
||||
return px;
|
||||
}
|
||||
</pre>
|
||||
<h2><A name="another_sp">Using a <code>shared_ptr</code> to hold another shared
|
||||
ownership smart pointer</A></h2>
|
||||
<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>
|
||||
argument, but the object at hand is being managed by a different reference
|
||||
counted or linked smart pointer.</p>
|
||||
<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>
|
||||
<pre>template<class P> struct smart_pointer_deleter
|
||||
<h2><A name="another_sp">Using a <code>shared_ptr</code> to hold another shared
|
||||
ownership smart pointer</A></h2>
|
||||
<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>
|
||||
argument, but the object at hand is being managed by a different reference
|
||||
counted or linked smart pointer.</p>
|
||||
<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>
|
||||
<pre>template<class P> struct smart_pointer_deleter
|
||||
{
|
||||
private:
|
||||
|
||||
@ -332,17 +332,17 @@ shared_ptr<X> make_shared_from_another(another_ptr<X> qx)
|
||||
return px;
|
||||
}
|
||||
</pre>
|
||||
<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
|
||||
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
|
||||
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
|
||||
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,
|
||||
to recover the original smart pointer, using <code><A href="shared_ptr.htm#get_deleter">
|
||||
get_deleter</A></code>:</P>
|
||||
<pre>void extract_another_from_shared(shared_ptr<X> px)
|
||||
<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
|
||||
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
|
||||
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
|
||||
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,
|
||||
to recover the original smart pointer, using <code><A href="shared_ptr.htm#get_deleter">
|
||||
get_deleter</A></code>:</P>
|
||||
<pre>void extract_another_from_shared(shared_ptr<X> px)
|
||||
{
|
||||
typedef smart_pointer_deleter< another_ptr<X> > deleter;
|
||||
|
||||
@ -356,37 +356,37 @@ shared_ptr<X> make_shared_from_another(another_ptr<X> qx)
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
<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
|
||||
pointer to an object that is already managed by another <code>shared_ptr</code>
|
||||
instance. Example:</p>
|
||||
<pre>void f(X * p)
|
||||
<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
|
||||
pointer to an object that is already managed by another <code>shared_ptr</code>
|
||||
instance. Example:</p>
|
||||
<pre>void f(X * p)
|
||||
{
|
||||
shared_ptr<X> px(<i>???</i>);
|
||||
}
|
||||
</pre>
|
||||
<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>
|
||||
to take a <code>shared_ptr</code>, if possible:</P>
|
||||
<pre>void f(shared_ptr<X> px);
|
||||
<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>
|
||||
to take a <code>shared_ptr</code>, if possible:</P>
|
||||
<pre>void f(shared_ptr<X> px);
|
||||
</pre>
|
||||
<p>The same transformation can be used for nonvirtual member functions, to convert
|
||||
the implicit <code>this</code>:</p>
|
||||
<pre>void X::f(int m);
|
||||
<p>The same transformation can be used for nonvirtual member functions, to convert
|
||||
the implicit <code>this</code>:</p>
|
||||
<pre>void X::f(int m);
|
||||
</pre>
|
||||
<p>would become a free function with a <code>shared_ptr</code> first argument:</p>
|
||||
<pre>void f(shared_ptr<X> this_, int m);
|
||||
<p>would become a free function with a <code>shared_ptr</code> first argument:</p>
|
||||
<pre>void f(shared_ptr<X> this_, int m);
|
||||
</pre>
|
||||
<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
|
||||
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>
|
||||
<h2><A name="in_constructor">Obtaining a <code>shared_ptr</code> (<code>weak_ptr</code>)
|
||||
to <code>this</code> in a constructor</A></h2>
|
||||
<p>Some designs require objects to register themselves on construction with a
|
||||
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>
|
||||
<pre>class X
|
||||
<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
|
||||
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>
|
||||
<h2><A name="in_constructor">Obtaining a <code>shared_ptr</code> (<code>weak_ptr</code>)
|
||||
to <code>this</code> in a constructor</A></h2>
|
||||
<p>Some designs require objects to register themselves on construction with a
|
||||
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>
|
||||
<pre>class X
|
||||
{
|
||||
public:
|
||||
|
||||
@ -396,19 +396,19 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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
|
||||
created on the heap:</p>
|
||||
<pre>shared_ptr<X> px(new X);</pre>
|
||||
<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
|
||||
ownership with it.</P>
|
||||
<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">
|
||||
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>,
|
||||
use a static factory function:</P>
|
||||
<pre>class X
|
||||
<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
|
||||
created on the heap:</p>
|
||||
<pre>shared_ptr<X> px(new X);</pre>
|
||||
<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
|
||||
ownership with it.</P>
|
||||
<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">
|
||||
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>,
|
||||
use a static factory function:</P>
|
||||
<pre>class X
|
||||
{
|
||||
private:
|
||||
|
||||
@ -424,13 +424,13 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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>
|
||||
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">
|
||||
described in the previous technique</A> cannot be applied.</p>
|
||||
<P>A typical example:</P>
|
||||
<pre>class X
|
||||
<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>
|
||||
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">
|
||||
described in the previous technique</A> cannot be applied.</p>
|
||||
<P>A typical example:</P>
|
||||
<pre>class X
|
||||
{
|
||||
public:
|
||||
|
||||
@ -469,8 +469,8 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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
|
||||
<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
|
||||
{
|
||||
private:
|
||||
|
||||
@ -499,10 +499,10 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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
|
||||
solution:</p>
|
||||
<pre>class impl: public X, public Y, public enable_shared_from_this<impl>
|
||||
<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
|
||||
solution:</p>
|
||||
<pre>class impl: public X, public Y, public enable_shared_from_this<impl>
|
||||
{
|
||||
public:
|
||||
|
||||
@ -519,19 +519,19 @@ public:
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
<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>.
|
||||
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>
|
||||
<p>Some library interfaces use opaque handles, a variation of the <A href="#incomplete">
|
||||
incomplete class technique</A> described above. An example:</p>
|
||||
<pre>typedef void * HANDLE;
|
||||
<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>.
|
||||
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>
|
||||
<p>Some library interfaces use opaque handles, a variation of the <A href="#incomplete">
|
||||
incomplete class technique</A> described above. An example:</p>
|
||||
<pre>typedef void * HANDLE;
|
||||
HANDLE CreateProcess();
|
||||
void CloseHandle(HANDLE);
|
||||
</pre>
|
||||
<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>
|
||||
<pre>typedef shared_ptr<void> handle;
|
||||
<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>
|
||||
<pre>typedef shared_ptr<void> handle;
|
||||
|
||||
handle createProcess()
|
||||
{
|
||||
@ -539,42 +539,42 @@ handle createProcess()
|
||||
return pv;
|
||||
}
|
||||
</pre>
|
||||
<h2><A name="on_block_exit">Using <code>shared_ptr</code> to execute code on block exit</A></h2>
|
||||
<p><code>shared_ptr<void></code> can automatically execute cleanup code when
|
||||
control leaves a scope.</p>
|
||||
<UL>
|
||||
<LI>
|
||||
Executing <code>f(p)</code>, where <code>p</code> is a pointer:</LI></UL>
|
||||
<pre> shared_ptr<void> guard(p, f);
|
||||
<h2><A name="on_block_exit">Using <code>shared_ptr</code> to execute code on block exit</A></h2>
|
||||
<p><code>shared_ptr<void></code> can automatically execute cleanup code when
|
||||
control leaves a scope.</p>
|
||||
<UL>
|
||||
<LI>
|
||||
Executing <code>f(p)</code>, where <code>p</code> is a pointer:</LI></UL>
|
||||
<pre> shared_ptr<void> guard(p, f);
|
||||
</pre>
|
||||
<UL>
|
||||
<LI>
|
||||
Executing arbitrary code: <code>f(x, y)</code>:</LI></UL>
|
||||
<pre> shared_ptr<void> guard(static_cast<void*>(0), <A href="../bind/bind.html" >bind</A>(f, x, y));
|
||||
<UL>
|
||||
<LI>
|
||||
Executing arbitrary code: <code>f(x, y)</code>:</LI></UL>
|
||||
<pre> shared_ptr<void> guard(static_cast<void*>(0), <A href="../bind/bind.html" >bind</A>(f, x, y));
|
||||
</pre>
|
||||
<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">
|
||||
http://www.cuj.com/experts/1812/alexandr.htm?topic=experts</A>.</P>
|
||||
<h2><A name="pvoid">Using <code>shared_ptr<void></code> to hold an arbitrary
|
||||
object</A></h2>
|
||||
<p><code>shared_ptr<void></code> can act as a generic object pointer similar
|
||||
to <code>void*</code>. When a <code>shared_ptr<void></code> instance
|
||||
constructed as:</p>
|
||||
<pre> shared_ptr<void> pv(new X);
|
||||
<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">
|
||||
http://www.cuj.com/experts/1812/alexandr.htm?topic=experts</A>.</P>
|
||||
<h2><A name="pvoid">Using <code>shared_ptr<void></code> to hold an arbitrary
|
||||
object</A></h2>
|
||||
<p><code>shared_ptr<void></code> can act as a generic object pointer similar
|
||||
to <code>void*</code>. When a <code>shared_ptr<void></code> instance
|
||||
constructed as:</p>
|
||||
<pre> shared_ptr<void> pv(new X);
|
||||
</pre>
|
||||
<p>is destroyed, it will correctly dispose of the <code>X</code> object by
|
||||
executing <code>~X</code>.</p>
|
||||
<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<void></code>
|
||||
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>
|
||||
<h2><A name="extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code>
|
||||
instances</A></h2>
|
||||
<p><code>shared_ptr</code> and <code>weak_ptr</code> support <code>operator<</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
|
||||
managed by <code>shared_ptr</code>:</p>
|
||||
<pre>typedef int Data;
|
||||
<p>is destroyed, it will correctly dispose of the <code>X</code> object by
|
||||
executing <code>~X</code>.</p>
|
||||
<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<void></code>
|
||||
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>
|
||||
<h2><A name="extra_data">Associating arbitrary data with heterogeneous <code>shared_ptr</code>
|
||||
instances</A></h2>
|
||||
<p><code>shared_ptr</code> and <code>weak_ptr</code> support <code>operator<</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
|
||||
managed by <code>shared_ptr</code>:</p>
|
||||
<pre>typedef int Data;
|
||||
|
||||
std::map< shared_ptr<void>, Data > userData;
|
||||
// or std::map< weak_ptr<void>, Data > userData; to not affect the lifetime
|
||||
@ -585,11 +585,11 @@ shared_ptr<int> pi(new int(3));
|
||||
userData[px] = 42;
|
||||
userData[pi] = 91;
|
||||
</pre>
|
||||
<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
|
||||
noncopyable lock cannot be returned by value. It is possible to use <code>shared_ptr</code>
|
||||
as a mutex lock:</p>
|
||||
<pre>class mutex
|
||||
<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
|
||||
noncopyable lock cannot be returned by value. It is possible to use <code>shared_ptr</code>
|
||||
as a mutex lock:</p>
|
||||
<pre>class mutex
|
||||
{
|
||||
public:
|
||||
|
||||
@ -603,9 +603,9 @@ shared_ptr<mutex> lock(mutex & m)
|
||||
return shared_ptr<mutex>(&m, mem_fn(&mutex::unlock));
|
||||
}
|
||||
</pre>
|
||||
<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>
|
||||
<pre>class shared_lock
|
||||
<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>
|
||||
<pre>class shared_lock
|
||||
{
|
||||
private:
|
||||
|
||||
@ -616,17 +616,17 @@ public:
|
||||
template<class Mutex> explicit shared_lock(Mutex & m): pv((m.lock(), &m), mem_fn(&Mutex::unlock)) {}
|
||||
};
|
||||
</pre>
|
||||
<p><code>shared_lock</code> can now be used as:</p>
|
||||
<pre> shared_lock lock(m);
|
||||
<p><code>shared_lock</code> can now be used as:</p>
|
||||
<pre> shared_lock lock(m);
|
||||
</pre>
|
||||
<p>Note that <code>shared_lock</code> is not templated on the mutex type, thanks to <code>
|
||||
shared_ptr<void></code>'s ability to hide type information.</p>
|
||||
<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>
|
||||
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>).
|
||||
An implementation is given below:</p>
|
||||
<pre>template<class T> class pointer
|
||||
<p>Note that <code>shared_lock</code> is not templated on the mutex type, thanks to <code>
|
||||
shared_ptr<void></code>'s ability to hide type information.</p>
|
||||
<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>
|
||||
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>).
|
||||
An implementation is given below:</p>
|
||||
<pre>template<class T> class pointer
|
||||
{
|
||||
private:
|
||||
|
||||
@ -669,10 +669,10 @@ int main()
|
||||
px->g();
|
||||
}
|
||||
</pre>
|
||||
<h2><A name="delayed">Delayed deallocation</A></h2>
|
||||
<p>In some situations, a single <code>px.reset()</code> can trigger an expensive
|
||||
deallocation in a performance-critical region:</p>
|
||||
<pre>class X; // ~X is expensive
|
||||
<h2><A name="delayed">Delayed deallocation</A></h2>
|
||||
<p>In some situations, a single <code>px.reset()</code> can trigger an expensive
|
||||
deallocation in a performance-critical region:</p>
|
||||
<pre>class X; // ~X is expensive
|
||||
|
||||
class Y
|
||||
{
|
||||
@ -686,10 +686,10 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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
|
||||
response times are not an issue:</p>
|
||||
<pre>vector< shared_ptr<void> > free_list;
|
||||
<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
|
||||
response times are not an issue:</p>
|
||||
<pre>vector< shared_ptr<void> > free_list;
|
||||
|
||||
class Y
|
||||
{
|
||||
@ -706,9 +706,9 @@ public:
|
||||
|
||||
// periodically invoke free_list.clear() when convenient
|
||||
</pre>
|
||||
<p>Another variation is to move the free list logic to the construction point by
|
||||
using a delayed deleter:</p>
|
||||
<pre>struct delayed_deleter
|
||||
<p>Another variation is to move the free list logic to the construction point by
|
||||
using a delayed deleter:</p>
|
||||
<pre>struct delayed_deleter
|
||||
{
|
||||
template<class T> void operator()(T * p)
|
||||
{
|
||||
@ -723,9 +723,9 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<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>
|
||||
<pre>class X
|
||||
<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>
|
||||
<pre>class X
|
||||
{
|
||||
private:
|
||||
|
||||
@ -748,18 +748,18 @@ public:
|
||||
|
||||
X & operator=(X const & rhs)
|
||||
{
|
||||
i_ = rhs.i_;
|
||||
i_ = rhs.i_;
|
||||
}
|
||||
|
||||
weak_ptr<X> get_weak_ptr() const { return this_; }
|
||||
};
|
||||
</pre>
|
||||
<p>When the object's lifetime ends, <code>X::this_</code> will be destroyed, and
|
||||
all weak pointers will automatically expire.</p>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<p><small>Copyright <EFBFBD> 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
|
||||
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
|
||||
</body>
|
||||
<p>When the object's lifetime ends, <code>X::this_</code> will be destroyed, and
|
||||
all weak pointers will automatically expire.</p>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<p><small>Copyright © 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
|
||||
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>
|
||||
|
||||
332
weak_ptr.htm
332
weak_ptr.htm
@ -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>
|
||||
<head>
|
||||
<title>weak_ptr</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgColor="#ffffff">
|
||||
<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
|
||||
border="0"></A>weak_ptr class template</h1>
|
||||
<p><A href="#Introduction">Introduction</A><br>
|
||||
<A href="#Synopsis">Synopsis</A><br>
|
||||
<A href="#Members">Members</A><br>
|
||||
<A href="#functions">Free Functions</A><br>
|
||||
<A href="#FAQ">Frequently Asked Questions</A>
|
||||
</p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's
|
||||
already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>weak_ptr</STRONG>
|
||||
can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
|
||||
the <STRONG>shared_ptr</STRONG> constructor</A> or the member function <STRONG><A href="#lock">
|
||||
lock</A></STRONG>. When the last <b>shared_ptr</b> to the object goes
|
||||
away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
|
||||
from the <b>weak_ptr</b> instances that refer to the deleted object will fail:
|
||||
the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>,
|
||||
and <STRONG>weak_ptr::lock</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
|
||||
<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements
|
||||
of the C++ Standard Library, and so can be used in standard library containers.
|
||||
Comparison operators are supplied so that <b>weak_ptr</b> works with the
|
||||
standard library's associative containers.</p>
|
||||
<P><STRONG>weak_ptr</STRONG> operations never throw exceptions.</P>
|
||||
<p>The class template is parameterized on <b>T</b>, the type of the object pointed
|
||||
to.</p>
|
||||
<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a
|
||||
very limited subset of operations since accessing its stored pointer is often
|
||||
dangerous in multithreaded programs, and sometimes unsafe even within a single
|
||||
thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b>
|
||||
has a <b>get</b> member function that returns a raw pointer, and consider this
|
||||
innocent piece of code:</P>
|
||||
<pre>shared_ptr<int> p(new int(5));
|
||||
<head>
|
||||
<title>weak_ptr</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">weak_ptr class template</h1>
|
||||
<p><A href="#Introduction">Introduction</A><br>
|
||||
<A href="#Synopsis">Synopsis</A><br>
|
||||
<A href="#Members">Members</A><br>
|
||||
<A href="#functions">Free Functions</A><br>
|
||||
<A href="#FAQ">Frequently Asked Questions</A>
|
||||
</p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's
|
||||
already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>weak_ptr</STRONG>
|
||||
can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
|
||||
the <STRONG>shared_ptr</STRONG> constructor</A> or the member function <STRONG><A href="#lock">
|
||||
lock</A></STRONG>. When the last <b>shared_ptr</b> to the object goes
|
||||
away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
|
||||
from the <b>weak_ptr</b> instances that refer to the deleted object will fail:
|
||||
the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>,
|
||||
and <STRONG>weak_ptr::lock</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
|
||||
<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements
|
||||
of the C++ Standard Library, and so can be used in standard library containers.
|
||||
Comparison operators are supplied so that <b>weak_ptr</b> works with the
|
||||
standard library's associative containers.</p>
|
||||
<P><STRONG>weak_ptr</STRONG> operations never throw exceptions.</P>
|
||||
<p>The class template is parameterized on <b>T</b>, the type of the object pointed
|
||||
to.</p>
|
||||
<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a
|
||||
very limited subset of operations since accessing its stored pointer is often
|
||||
dangerous in multithreaded programs, and sometimes unsafe even within a single
|
||||
thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b>
|
||||
has a <b>get</b> member function that returns a raw pointer, and consider this
|
||||
innocent piece of code:</P>
|
||||
<pre>shared_ptr<int> p(new int(5));
|
||||
weak_ptr<int> q(p);
|
||||
|
||||
// some time later
|
||||
@ -46,12 +46,12 @@ if(int * r = q.get())
|
||||
// use *r
|
||||
}
|
||||
</pre>
|
||||
<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 a dangling pointer.</P>
|
||||
<P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
|
||||
from <STRONG>q</STRONG>:</P>
|
||||
<pre>shared_ptr<int> p(new int(5));
|
||||
<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 a dangling pointer.</P>
|
||||
<P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
|
||||
from <STRONG>q</STRONG>:</P>
|
||||
<pre>shared_ptr<int> p(new int(5));
|
||||
weak_ptr<int> q(p);
|
||||
|
||||
// some time later
|
||||
@ -61,13 +61,13 @@ if(shared_ptr<int> r = q.<A href="#lock" >lock</A>())
|
||||
// use *r
|
||||
}
|
||||
</pre>
|
||||
<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>.
|
||||
Even if <code>p.reset()</code> is executed in another thread, the object will
|
||||
stay alive until <STRONG>r</STRONG> goes out of scope or is reset. By obtaining
|
||||
a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it
|
||||
against destruction.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>.
|
||||
Even if <code>p.reset()</code> is executed in another thread, the object will
|
||||
stay alive until <STRONG>r</STRONG> goes out of scope or is reset. By obtaining
|
||||
a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it
|
||||
against destruction.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<class T> class weak_ptr {
|
||||
|
||||
@ -101,119 +101,119 @@ if(shared_ptr<int> r = q.<A href="#lock" >lock</A>())
|
||||
void <A href="#free-swap" >swap</A>(weak_ptr<T> & a, weak_ptr<T> & b);
|
||||
}
|
||||
</pre>
|
||||
<h2><a name="Members">Members</a></h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<blockquote>
|
||||
<p>Provides the type of the template parameter T.</p>
|
||||
</blockquote>
|
||||
<h3><a name="default-constructor">constructors</a></h3>
|
||||
<pre>weak_ptr();</pre>
|
||||
<blockquote>
|
||||
<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>Throws:</b> nothing.</p>
|
||||
</blockquote><a name="constructors"></a>
|
||||
<pre>template<class Y> weak_ptr</A>(shared_ptr<Y> const & r);
|
||||
<h2><a name="Members">Members</a></h2>
|
||||
<h3><a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<blockquote>
|
||||
<p>Provides the type of the template parameter T.</p>
|
||||
</blockquote>
|
||||
<h3><a name="constructors">constructors</a></h3>
|
||||
<pre><a name="default-constructor">weak_ptr();</a></pre>
|
||||
<blockquote>
|
||||
<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>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<class Y> weak_ptr(shared_ptr<Y> const & r);
|
||||
weak_ptr(weak_ptr const & r);
|
||||
template<class Y> weak_ptr(weak_ptr<Y> const & r);</pre>
|
||||
<blockquote>
|
||||
<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
|
||||
ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the
|
||||
pointer stored in <b>r</b>.</p>
|
||||
<p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~weak_ptr();</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object
|
||||
its stored pointer points to.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="assignment">assignment</a></h3>
|
||||
<pre>weak_ptr & operator=(weak_ptr const & r);
|
||||
<blockquote>
|
||||
<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
|
||||
ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the
|
||||
pointer stored in <b>r</b>.</p>
|
||||
<p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="destructor">destructor</a></h3>
|
||||
<pre>~weak_ptr();</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object
|
||||
its stored pointer points to.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="assignment">assignment</a></h3>
|
||||
<pre>weak_ptr & operator=(weak_ptr const & r);
|
||||
template<class Y> weak_ptr & operator=(weak_ptr<Y> const & r);
|
||||
template<class Y> weak_ptr & operator=(shared_ptr<Y> const & r);</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
<P><B>Notes:</B> The implementation is free to meet the effects (and the implied
|
||||
guarantees) via different means, without creating a temporary.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="use_count">use_count</a></h3>
|
||||
<pre>long use_count() const;</pre>
|
||||
<blockquote>
|
||||
<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>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only
|
||||
for debugging and testing purposes, not for production code.</P>
|
||||
</blockquote>
|
||||
<h3><a name="expired">expired</a></h3>
|
||||
<pre>bool expired() const;</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>use_count() == 0</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
|
||||
</blockquote>
|
||||
<h3><a name="lock">lock</a></h3>
|
||||
<pre>shared_ptr<T> lock() const;</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Returns:</B> <code>expired()? shared_ptr<T>(): shared_ptr<T>(*this)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset();</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(weak_ptr & b);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="comparison">comparison</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
<P><B>Notes:</B> The implementation is free to meet the effects (and the implied
|
||||
guarantees) via different means, without creating a temporary.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="use_count">use_count</a></h3>
|
||||
<pre>long use_count() const;</pre>
|
||||
<blockquote>
|
||||
<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>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only
|
||||
for debugging and testing purposes, not for production code.</P>
|
||||
</blockquote>
|
||||
<h3><a name="expired">expired</a></h3>
|
||||
<pre>bool expired() const;</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>use_count() == 0</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
|
||||
</blockquote>
|
||||
<h3><a name="lock">lock</a></h3>
|
||||
<pre>shared_ptr<T> lock() const;</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Returns:</B> <code>expired()? shared_ptr<T>(): shared_ptr<T>(*this)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset();</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(weak_ptr & b);</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="comparison">comparison</a></h3>
|
||||
<pre>template<class T, class U>
|
||||
bool operator<(weak_ptr<T> const & a, weak_ptr<U> const & b);</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> an unspecified value such that</p>
|
||||
<UL>
|
||||
<LI>
|
||||
<b>operator<</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
|
||||
of the C++ standard;
|
||||
<LI>
|
||||
under the equivalence relation defined by <STRONG>operator<</STRONG>, <code>!(a
|
||||
< b) && !(b < 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>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in
|
||||
associative containers.</P>
|
||||
</blockquote>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> an unspecified value such that</p>
|
||||
<UL>
|
||||
<LI>
|
||||
<b>operator<</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
|
||||
of the C++ standard;
|
||||
<LI>
|
||||
under the equivalence relation defined by <STRONG>operator<</STRONG>, <code>!(a
|
||||
< b) && !(b < 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>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in
|
||||
associative containers.</P>
|
||||
</blockquote>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<class T>
|
||||
void swap(weak_ptr<T> & a, weak_ptr<T> & b)</pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
|
||||
generic programming.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h2><a name="FAQ">Frequently Asked Questions</a></h2>
|
||||
<P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its
|
||||
constructor?</P>
|
||||
<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
|
||||
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
|
||||
all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P>
|
||||
<P>The solution is to make the constructor private, and supply a factory function
|
||||
that returns a <STRONG>shared_ptr</STRONG>:<BR>
|
||||
</P>
|
||||
<pre>
|
||||
<BLOCKQUOTE>
|
||||
<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
|
||||
<P><B>Throws:</B> nothing.</P>
|
||||
<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
|
||||
generic programming.</P>
|
||||
</BLOCKQUOTE>
|
||||
<h2><a name="FAQ">Frequently Asked Questions</a></h2>
|
||||
<P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its
|
||||
constructor?</P>
|
||||
<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
|
||||
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
|
||||
all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P>
|
||||
<P>The solution is to make the constructor private, and supply a factory function
|
||||
that returns a <STRONG>shared_ptr</STRONG>:<BR>
|
||||
</P>
|
||||
<pre>
|
||||
class X
|
||||
{
|
||||
private:
|
||||
@ -230,13 +230,11 @@ public:
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
<p><br>
|
||||
</p>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<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
|
||||
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>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
<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
|
||||
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>
|
||||
|
||||
Reference in New Issue
Block a user