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

Documentation fixes (reflecting Dave Abrahams' comments)

Browse Source 
[SVN r15382]
This commit is contained in:
Peter Dimov
2002-09-16 15:26:52 +00:00
parent 4ea6decc7d
commit 0f05f41306
3 changed files with 242 additions and 319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
scoped_array.htm
View File

@ -1,53 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head>
<head> <title>scoped_array</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>scoped_array</title> </head>
</head> <body bgcolor="#ffffff" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"><a name="scoped_array">scoped_array</a>
<body bgcolor="#FFFFFF" text="#000000"> class template</h1>
<p>The <b>scoped_array</b> class template stores a pointer to a dynamically
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"><a name="scoped_array">scoped_array</a> class template</h1> 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
<p>The <b>scoped_array</b> class template stores a pointer to a dynamically allocated destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p>
array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b> <p>The <b>scoped_array</b> template is a simple solution for simple needs. It
expression.) The array pointed to is guaranteed to be deleted, supplies a basic "resource acquisition is initialization" facility, without
either on destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p> shared-ownership or transfer-of-ownership semantics. Both its name and
enforcement of semantics (by being <a href="../utility/utility.htm#class noncopyable">
<p>The <b>scoped_array</b> template is a simple solution for simple noncopyable</a>) signal its intent to retain ownership solely within the
needs. It supplies a basic &quot;resource acquisition is current scope. Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>,
initialization&quot; facility, without shared-ownership or transfer-of-ownership it is safer than <b>shared_array</b> for pointers which should not be copied.</p>
semantics. Both its name and enforcement of semantics (by being <p>Because <b>scoped_array</b> is so simple, in its usual implementation every
<a href="../utility/utility.htm#class noncopyable">noncopyable</a>) operation is as fast as a built-in array pointer and it has no more space
signal its intent to retain ownership solely within the current scope. overhead that a built-in array pointer.</p>
Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is <p>It cannot be used in C++ standard library containers. See <a href="shared_array.htm">
safer than <b>shared_array</b> for pointers which should not be copied.</p> <b>shared_array</b></a> if <b>scoped_array</b> does not meet your needs.</p>
<p>It cannot correctly hold a pointer to a single object. See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
<p>Because <b>scoped_array</b> is so simple, in its usual implementation for that usage.</p>
every operation is as fast as a built-in array pointer and it has no <p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is a bit
more space overhead that a built-in array pointer.</p> heavier duty but far more flexible. A <b>boost::array</b> is an alternative
that does not use dynamic allocation.</p>
<p>It cannot be used in C++ standard library containers. <p>The class template is parameterized on <b>T</b>, the type of the object pointed
See <a href="shared_array.htm"><b>shared_array</b></a> to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">
if <b>scoped_array</b> does not meet your needs.</p> common requirements</a>.</p>
<h2>Synopsis</h2>
<p>It cannot correctly hold a pointer to a single object. <pre>namespace boost {
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&lt;typename T&gt; class scoped_array : <a href="../utility/utility.htm#noncopyable">noncopyable</a> { template&lt;typename T&gt; class scoped_array : <a href="../utility/utility.htm#noncopyable">noncopyable</a> {
@ -59,7 +44,7 @@ pointed to. <b>T</b> must meet the smart pointer
void <a href="#reset">reset</a>(T * p = 0); // never throws void <a href="#reset">reset</a>(T * p = 0); // never throws
T &amp; <a href="#operator[]">operator[]</a>(std::size_t i) const; // never throws T &amp; <a href="#operator[]">operator[]</a>(std::ptrdiff_t i) const; // never throws
T * <a href="#get">get</a>() const; // never throws T * <a href="#get">get</a>() const; // never throws
void <a href="#swap">swap</a>(scoped_array &amp; b); // never throws void <a href="#swap">swap</a>(scoped_array &amp; b); // never throws
@ -68,78 +53,59 @@ pointed to. <b>T</b> must meet the smart pointer
template&lt;typename T&gt; void <a href="#free-swap">swap</a>(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws template&lt;typename T&gt; void <a href="#free-swap">swap</a>(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws
}</pre> }</pre>
<h2>Members</h2>
<h2>Members</h2> <h3>
<a name="element_type">element_type</a></h3>
<h3> <pre>typedef T element_type;</pre>
<a name="element_type">element_type</a></h3> <p>Provides the type of the stored pointer.</p>
<pre>typedef T element_type;</pre> <h3><a name="ctor">constructors</a></h3>
<p>Provides the type of the stored pointer.</p> <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
<h3><a name="ctor">constructors</a></h3> been allocated via a C++ <b>new</b>[] expression or be 0. <b>T</b> is not
<pre>explicit scoped_array(T * p = 0); // never throws</pre> required be a complete type. See the smart pointer <a href="smart_ptr.htm#Common requirements">
<p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must common requirements</a>.</p>
have been allocated via a C++ <b>new</b>[] expression or be 0. <h3><a name="~scoped_array">destructor</a></h3>
<b>T</b> is not required be a complete type. <pre>~scoped_array(); // never throws</pre>
See the smart pointer <p>Deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> 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'
<h3><a name="~scoped_array">destructor</a></h3> destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#Common requirements">
<pre>~scoped_array(); // never throws</pre> common requirements</a>.</p>
<p>Deletes the array pointed to by the stored pointer. <h3><a name="reset">reset</a></h3>
Note that <b>delete[]</b> on a pointer with a value of 0 is harmless. <pre>void reset(T * p = 0); // never throws</pre>
The guarantee that this does not throw exceptions depends on the requirement that the <p>If p is not equal to the stored pointer, deletes the array pointed to by the
deleted array's objects' destructors do not throw exceptions. stored pointer and then stores a copy of p, which must have been allocated via
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> 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'
<h3><a name="reset">reset</a></h3> destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#Common requirements">
<pre>void reset(T * p = 0); // never throws</pre> common requirements</a>.</p>
<p>If p is not equal to the stored pointer, deletes the array pointed to by the <h3><a name="operator[]">subscripting</a></h3>
stored pointer and then stores a copy of p, which must have been allocated via a <pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
C++ <b>new[]</b> expression or be 0. <p>Returns a reference to element <b>i</b> of the array pointed to by the stored
The guarantee that this does not throw exceptions depends on the requirement that the pointer. Behavior is undefined and almost certainly undesirable if the stored
deleted array's objects' destructors do not throw exceptions. pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> number of elements in the array.</p>
<h3><a name="get">get</a></h3>
<h3><a name="operator[]">subscripting</a></h3> <pre>T * get() const; // never throws</pre>
<pre>T &amp; operator[](std::size_t i) const; // never throws</pre> <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
<p>Returns a reference to element <b>i</b> of the array pointed to by the pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
stored pointer. <h3><a name="swap">swap</a></h3>
Behavior is undefined and almost certainly undesirable if the stored pointer is 0, <pre>void swap(scoped_array &amp; b); // never throws</pre>
or if <b>i</b> is less than 0 or is greater than or equal to the number of elements <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
in the array.</p> complete type. See the smart pointer <a href="smart_ptr.htm#Common requirements">common
requirements</a>.</p>
<h3><a name="get">get</a></h3> <h2><a name="functions">Free Functions</a></h2>
<pre>T * get() const; // never throws</pre> <h3><a name="free-swap">swap</a></h3>
<p>Returns the stored pointer. <pre>template&lt;typename T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws</pre>
<b>T</b> need not be a complete type. <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
See the smart pointer Provided as an aid to generic programming.</p>
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->
<h3><a name="swap">swap</a></h3> 1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="13964"--></p>
<pre>void swap(scoped_array &amp; b); // never throws</pre> <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
<p>Exchanges the contents of the two smart pointers. Permission to copy, use, modify, sell and distribute this document is granted
<b>T</b> need not be a complete type. provided this copyright notice appears in all copies. This document is provided
See the smart pointer "as is" without express or implied warranty, and with no claim as to its
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> suitability for any purpose.</p>
</body>
<h2><a name="functions">Free Functions</a></h2>
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="13964"--></p>
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Permission to copy, use, modify, sell and distribute this document is granted
provided this copyright notice appears in all copies.
This document is provided &quot;as is&quot; without express or implied warranty,
and with no claim as to its suitability for any purpose.</p>
</body>
</html> </html>

313
shared_array.htm
View File

@ -1,47 +1,35 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head>
<head> <title>shared_array</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>shared_array</title> </head>
</head> <body bgcolor="#ffffff" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">shared_array
<body bgcolor="#FFFFFF" text="#000000"> class template</h1>
<p>The <b>shared_array</b> class template stores a pointer to a dynamically
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">shared_array class template</h1> 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>
<p>The <b>shared_array</b> class template stores a pointer to a dynamically allocated pointing to it is destroyed or reset.</p>
array. (Dynamically allocated array are allocated with the C++ <b>new[]</b> <p>Every <b>shared_array</b> meets the <b>CopyConstructible</b> and <b>Assignable</b>
expression.) The object pointed to is guaranteed to be deleted when requirements of the C++ Standard Library, and so can be used in standard
the last <b>shared_array</b> pointing to it is destroyed or reset.</p> library containers. Comparison operators are supplied so that <b>shared_array</b>
works with the standard library's associative containers.</p>
<p>Every <b>shared_array</b> meets the <b>CopyConstructible</b> <p>Normally, a <b>shared_array</b> cannot correctly hold a pointer to a single
and <b>Assignable</b> requirements of the C++ Standard Library, and so dynamically allocated object. See <a href="shared_ptr.htm"><b>shared_ptr</b></a>
can be used in standard library containers. Comparison operators for that usage.</p>
are supplied so that <b>shared_array</b> works with <p>Because the implementation uses reference counting, <b>shared_array</b> will not
the standard library's associative containers.</p> work correctly with cyclic data structures. 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>
<p>Normally, a <b>shared_array</b> cannot correctly hold a pointer to a back to <b>A</b>, <b>A</b>'s use count will be 2. Destruction of the original <b>shared_array</b>
single dynamically allocated object. See <a href="shared_ptr.htm"><b>shared_ptr</b></a> will leave <b>A</b> dangling with a use count of 1.</p>
for that usage.</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>Because the implementation uses reference counting, <b>shared_array</b> will not work <p>The class template is parameterized on <b>T</b>, the type of the object pointed
correctly with cyclic data structures. For example, if <b>main()</b> holds a <b>shared_array</b> to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">
to <b>A</b>, which directly or indirectly holds a <b>shared_array</b> back to <b>A</b>, common requirements</a>.</p>
<b>A</b>'s use count will be 2. Destruction of the original <b>shared_array</b> <h2>Synopsis</h2>
will leave <b>A</b> dangling with a use count of 1.</p> <pre>namespace boost {
<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&lt;typename T&gt; class shared_array { template&lt;typename T&gt; class shared_array {
@ -78,147 +66,114 @@ pointed to. <b>T</b> must meet the smart pointer
template&lt;typename T&gt; void <a href="#free-swap">swap</a>(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b); // never throws template&lt;typename T&gt; void <a href="#free-swap">swap</a>(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b); // never throws
}</pre> }</pre>
<h2>Members</h2>
<h2>Members</h2> <h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre>
<h3><a name="element_type">element_type</a></h3> <p>Provides the type of the stored pointer.</p>
<pre>typedef T element_type;</pre> <h3><a name="constructors">constructors</a></h3>
<p>Provides the type of the stored pointer.</p> <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
<h3><a name="constructors">constructors</a></h3> 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">
<pre>explicit shared_array(T * p = 0);</pre> ~shared_array</a>). The only exception which may be thrown by this
<p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b>, which constructor is <b>std::bad_alloc</b>. If an exception is thrown, <b>delete[] p</b>
must be a pointer to an array that was allocated via a C++ <b>new[]</b> expression or be 0. is called.</p>
Afterwards, the <a href="#use_count">use count</a> is 1 (even if p == 0; see <a href="#destructor">~shared_array</a>). <pre>template&lt;typename D&gt; shared_array(T * p, D d);</pre>
The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>. <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b> and of <b>d</b>.
If an exception is thrown, <b>delete[] p</b> is called.</p> 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
<pre>template&lt;typename D&gt; shared_array(T * p, D d);</pre> the array pointed to by <b>p</b>, the object <b>d</b> is used in the statement <b>d(p)</b>.
<p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b> and of <b>d</b>. Invoking the object <b>d</b> with parameter <b>p</b> in this way must not
Afterwards, the <a href="#use_count">use count</a> is 1. throw. The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
<b>D</b>'s copy constructor and destructor must not throw. If an exception is thrown, <b>d(p)</b> is called.</p>
When the the time comes to delete the array pointed to by <b>p</b>, the object <pre>shared_array(shared_array const &amp; r); // never throws</pre>
<b>d</b> is used in the statement <b>d(p)</b>. Invoking the object <b>d</b> with <p>Constructs a <b>shared_array</b>, as if by storing a copy of the pointer stored
parameter <b>p</b> in this way must not throw. in <b>r</b>. Afterwards, the <a href="#use_count">use count</a> for all copies
The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>. is 1 more than the initial use count.</p>
If an exception is thrown, <b>d(p)</b> is called.</p> <h3><a name="destructor">destructor</a></h3>
<pre>~shared_array(); // never throws</pre>
<pre>shared_array(shared_array const &amp; r); // never throws</pre> <p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0,
<p>Constructs a <b>shared_array</b>, as if by storing a copy of the deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
pointer stored in <b>r</b>. Afterwards, the <a href="#use_count">use count</a> a pointer with a value of 0 is harmless. <b>T</b> need not be a complete type.
for all copies is 1 more than the initial use count.</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
<h3><a name="destructor">destructor</a></h3> pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="operator=">assignment</a></h3>
<pre>~shared_array(); // never throws</pre> <pre>shared_array &amp; <a href="#assignment">operator=</a>(shared_array const &amp; r); // never throws</pre>
<p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0, <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
deletes the array pointed to by the stored pointer. then replaces this <b>shared_array</b> with the new one, destroying the
Note that <b>delete[]</b> on a pointer with a value of 0 is harmless. replaced object.</p>
<b>T</b> need not be a complete type. <h3><a name="reset">reset</a></h3>
The guarantee that this does not throw exceptions depends on the requirement that the <pre>void reset(T * p = 0);</pre>
deleted object's destructor does not throw exceptions. <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> 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>.
<h3><a name="operator=">assignment</a></h3> If an exception is thrown, <b>delete[] p</b> is called.</p>
<pre>template&lt;typename D&gt; void reset(T * p, D d);</pre>
<pre>shared_array &amp; <a href="#assignment">operator=</a>(shared_array const &amp; r); // never throws</pre> <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, then replaces this <b>shared_array</b> with the new one, destroying the
then replaces this <b>shared_array</b> with the new one, destroying the replaced object.</p> replaced object. <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>
<h3><a name="reset">reset</a></h3> is called.</p>
<h3><a name="indirection">indexing</a></h3>
<pre>void reset(T * p = 0);</pre> <pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, <p>Returns a reference to element <b>i</b> of the array pointed to by the stored
then replaces this <b>shared_array</b> with the new one, destroying the replaced object. pointer. Behavior is undefined and almost certainly undesirable if the stored
The only exception which may be thrown is <b>std::bad_alloc</b>. If pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
an exception is thrown, <b>delete[] p</b> is called.</p> number of elements in the array.</p>
<h3><a name="get">get</a></h3>
<pre>template&lt;typename D&gt; void reset(T * p, D d);</pre> <pre>T * get() const; // never throws</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
then replaces this <b>shared_array</b> with the new one, destroying the replaced object. pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<b>D</b>'s copy constructor must not throw. <h3><a name="unique">unique</a></h3>
The only exception which may be thrown is <b>std::bad_alloc</b>. If <pre>bool unique() const; // never throws</pre>
an exception is thrown, <b>d(p)</b> is called.</p> <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
<h3><a name="indirection">indexing</a></h3> pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<pre>T &amp; operator[](std::size_t i) const; // never throws</pre> <h3><a name="use_count">use_count</a></h3>
<p>Returns a reference to element <b>i</b> of the array pointed to by the stored pointer. <pre>long use_count() const; // never throws</pre>
Behavior is undefined and almost certainly undesirable if the stored pointer is 0, <p>Returns the number of <b>shared_array</b> objects sharing ownership of the
or if <b>i</b> is less than 0 or is greater than or equal to the number of elements stored pointer. <b>T</b> need not be a complete type. See the smart pointer <a href="smart_ptr.htm#Common requirements">
in the array.</p> common requirements</a>.</p>
<p>Because <b>use_count</b> is not necessarily efficient to implement for
<h3><a name="get">get</a></h3> implementations of <b>shared_array</b> that do not use an explicit reference
<pre>T * get() const; // never throws</pre> count, it might be removed from some future version. Thus it should be used for
<p>Returns the stored pointer. debugging purposes only, and not production code.</p>
<b>T</b> need not be a complete type. <h3><a name="swap">swap</a></h3>
See the smart pointer <pre>void swap(shared_ptr &amp; b); // never throws</pre>
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> <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
<h3><a name="unique">unique</a></h3> requirements</a>.</p>
<pre>bool unique() const; // never throws</pre> <h2><a name="functions">Free Functions</a></h2>
<p>Returns true if no other <b>shared_array</b> is sharing ownership of <h3><a name="comparison">comparison</a></h3>
the stored pointer, false otherwise. <pre>template&lt;typename T&gt;
<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="swap">swap</a></h3>
<pre>void swap(shared_ptr &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers.
<b>T</b> need not be a 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&lt;typename T&gt;
bool operator==(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws bool operator==(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
template&lt;typename T&gt; template&lt;typename T&gt;
bool operator!=(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws bool operator!=(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
template&lt;typename T&gt; template&lt;typename T&gt;
bool operator&lt;(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws</pre> bool operator&lt;(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws</pre>
<p>Compares the stored pointers of the two smart pointers. <p>Compares the stored pointers of the two smart pointers. <b>T</b> need not be a
<b>T</b> need not be a complete type. complete type. See the smart pointer <a href="smart_ptr.htm#Common requirements">common
See the smart pointer requirements</a>.</p>
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p> <p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>shared_array</b>
<p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>shared_array</b> objects can be used in associative containers such as <b>std::map</b>. The
objects can be used in associative containers such as <b>std::map</b>. implementation uses <b>std::less&lt;T *&gt;</b> to perform the comparison. This
The implementation uses <b>std::less&lt;T *&gt;</b> to perform the ensures that the comparison is handled correctly, since the standard mandates
comparison. This ensures that the comparison is handled correctly, since the that relational operations on pointers are unspecified (5.9 [expr.rel]
standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel] paragraph 2) but <b>std::less&lt;&gt;</b> on pointers is well-defined (20.3.3
paragraph 2) but <b>std::less&lt;&gt;</b> on pointers is well-defined (20.3.3 [lib.comparisons] [lib.comparisons] paragraph 8).</p>
paragraph 8).</p> <h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt;
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt;
void swap(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b) // never throws</pre> void swap(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b) // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>. <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p> Provided as an aid to generic programming.</p>
<hr>
<hr> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->
8 February 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->8 February 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p> <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Permission to copy, use, modify, sell and distribute this document is granted
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. provided this copyright notice appears in all copies. This document is provided
Permission to copy, use, modify, sell and distribute this document is granted "as is" without express or implied warranty, and with no claim as to its
provided this copyright notice appears in all copies. suitability for any purpose.</p>
This document is provided &quot;as is&quot; without express or implied warranty, </body>
and with no claim as to its suitability for any purpose.</p>
</body>
</html> </html>

36
shared_ptr.htm
View File

@ -19,9 +19,9 @@
<A href="smarttests.htm">Smart Pointer Timings</A></p> <A href="smarttests.htm">Smart Pointer Timings</A></p>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>The <b>shared_ptr</b> class template stores a pointer to a dynamically allocated <p>The <b>shared_ptr</b> class template stores a pointer to a dynamically allocated
object. (Dynamically allocated objects are allocated with the C++ <b>new</b> expression.) object, typically with a C++ <EM>new-expression</EM> . The object pointed to is
The object pointed to is guaranteed to be deleted when the last <b>shared_ptr</b> guaranteed to be deleted when the last <b>shared_ptr</b> pointing to it is
pointing to it is destroyed or reset. See the <A href="#example">example</A>.</p> destroyed or reset. See the <A href="#example">example</A>.</p>
<p>Every <b>shared_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> <p>Every <b>shared_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b>
requirements of the C++ Standard Library, and so can be used in standard requirements of the C++ Standard Library, and so can be used in standard
library containers. Comparison operators are supplied so that <b>shared_ptr</b> library containers. Comparison operators are supplied so that <b>shared_ptr</b>
@ -29,11 +29,11 @@
<p>Normally, a <b>shared_ptr</b> cannot correctly hold a pointer to a dynamically <p>Normally, a <b>shared_ptr</b> cannot correctly hold a pointer to a dynamically
allocated array. See <A href="shared_array.htm"><b>shared_array</b></A> for allocated array. See <A href="shared_array.htm"><b>shared_array</b></A> for
that usage.</p> that usage.</p>
<p>Because the implementation uses reference counting, <b>shared_ptr</b> will not <p>Because the implementation uses reference counting, cycles of <b>shared_ptr</b> instances
work correctly with cyclic data structures. For example, if <b>main()</b> holds will not be reclaimed. For example, if <b>main()</b> holds a <b>shared_ptr</b> to
a <b>shared_ptr</b> to <b>A</b>, which directly or indirectly holds a <b>shared_ptr</b> <b>A</b>, which directly or indirectly holds a <b>shared_ptr</b> back to <b>A</b>,
back to <b>A</b>, <b>A</b>'s use count will be 2. Destruction of the original <b>shared_ptr</b> <b>A</b>'s use count will be 2. Destruction of the original <b>shared_ptr</b> will
will leave <b>A</b> dangling with a use count of 1. Use <A href="weak_ptr.htm">weak_ptr</A> leave <b>A</b> dangling with a use count of 1. Use <A href="weak_ptr.htm">weak_ptr</A>
to "break cycles."</p> to "break cycles."</p>
<p>The class template is parameterized on <b>T</b>, the type of the object pointed <p>The class template is parameterized on <b>T</b>, the type of the object pointed
to. <STRONG>shared_ptr</STRONG> and most of its member functions place no to. <STRONG>shared_ptr</STRONG> and most of its member functions place no
@ -148,10 +148,11 @@ void bad()
}</pre> }</pre>
<P><EM>[It might be&nbsp;convenient to relax the requirements on <STRONG>shared_ptr</STRONG>'s <P><EM>[It might be&nbsp;convenient to relax the requirements on <STRONG>shared_ptr</STRONG>'s
signature, allowing an additional, defaulted, template parameter. This would signature, allowing an additional, defaulted, template parameter; the parameter
help in detecting possible ODR violations. On the other hand, using <STRONG>shared_ptr</STRONG> can encode the threading model, for example. This would help in detecting
as an argument to a&nbsp;template template parameter requires an exact possible ODR violations. On the other hand, using <STRONG>shared_ptr</STRONG> as
signature match.]</EM></P> an argument to a&nbsp;template template parameter requires an exact signature
match.]</EM></P>
<h2><a name="Members">Members</a></h2> <h2><a name="Members">Members</a></h2>
<h3><a name="element_type">element_type</a></h3> <h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
@ -229,16 +230,17 @@ void bad()
<pre>template&lt;typename Y, typename D&gt; shared_ptr(Y * p, D d);</pre> <pre>template&lt;typename Y, typename D&gt; shared_ptr(Y * p, D d);</pre>
<blockquote> <blockquote>
<p><b>Requirements:</b> <B>p</B> must be convertible to <B>T *</B>. The copy <p><b>Requirements:</b> <B>p</B> must be convertible to <B>T *</B>. The copy
constructor and destructor of <b>D</b> must not throw. The expression <code>d(p)</code> constructor and destructor of <b>D</b> must not throw. The expression <code>d2(p)</code>,
must be well-formed, must not invoke undefined behavior, and must not throw where <STRONG>d2</STRONG> is a copy of <STRONG>d</STRONG>, must be well-formed,
exceptions. must not invoke undefined behavior, and must not throw exceptions.
</p> </p>
<p><b>Effects:</b> Constructs a <b>shared_ptr</b>, storing a copy of <b>p</b> and <b>d</b>.</p> <p><b>Effects:</b> Constructs a <b>shared_ptr</b>, storing a copy of <b>p</b> and <b>d</b>.</p>
<p><b>Postconditions:</b> <A href="#use_count">use count</A> is 1.</p> <p><b>Postconditions:</b> <A href="#use_count">use count</A> is 1.</p>
<p><b>Throws:</b> <b>std::bad_alloc</b>.</p> <p><b>Throws:</b> <b>std::bad_alloc</b>.</p>
<p><b>Exception safety:</b> If an exception is thrown, <code>d(p)</code> is called.</p> <p><b>Exception safety:</b> If an exception is thrown, <code>d(p)</code> is called.</p>
<p><b>Notes:</b> When the the time comes to delete the object pointed to by <b>p</b>, <p><b>Notes:</b> When the the time comes to delete the object pointed to by <b>p</b>,
<code>d(p)</code> is invoked.</p> <code>d2(p)</code> is invoked, where <STRONG>d2</STRONG> is the stored copy of <STRONG>
d</STRONG>.</p>
</blockquote> </blockquote>
<P><EM>[Custom deallocators allow a factory function returning a <STRONG>shared_ptr</STRONG> <P><EM>[Custom deallocators allow a factory function returning a <STRONG>shared_ptr</STRONG>
to insulate the user from its memory allocation strategy. Since the deallocator to insulate the user from its memory allocation strategy. Since the deallocator
@ -647,7 +649,7 @@ int * p = a.release();
implementation or a linked list implementation, or some other specific implementation or a linked list implementation, or some other specific
implementation. This is not the intent.</p> implementation. This is not the intent.</p>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan --> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->
23 July 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p> 23 July 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Copyright 2002 Peter Dimov. Permission to copy, use, modify, sell and Copyright 2002 Peter Dimov. Permission to copy, use, modify, sell and