boostorg/smart_ptr
1
0
Fork 1
mirror of https://github.com/boostorg/smart_ptr.git synced 2025-08-02 14:14:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merged [51699] and [51700] from trunk to release.

Browse Source 
Closes #1897


[SVN r51703]
This commit is contained in:
Frank Mori Hess
2009-03-11 15:08:14 +00:00
parent 31e06b4a1d
commit 1742c37942
3 changed files with 361 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
make_shared.html Normal file
View File

@@ -0,0 +1,119 @@
<!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 &lt;boost/make_shared.hpp&gt; 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&lt;Widget&gt;()</code> can be read aloud and conveys the intended meaning.</p>
<h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost {
template&lt;typename T&gt; class shared_ptr;
template&lt;typename T&gt;
shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>();
template&lt;typename T, typename A&gt;
shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( A const &amp; );
#if defined( BOOST_HAS_VARIADIC_TMPL ) && defined( BOOST_HAS_RVALUE_REFS ) // C++0x prototypes
template&lt;typename T, typename... Args&gt;
shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>( Args &amp;&amp; ... args );
template&lt;typename T, typename A, typename... Args&gt;
shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( A const &amp; a, Args &amp;&amp; ... args );
#else // no C++0X support
template&lt;typename T, typename Arg1 &gt;
shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>( Arg1 const &amp; arg1 );
template&lt;typename T, typename Arg1, typename Arg2 &gt;
shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>( Arg1 const &amp; arg1, Arg2 const &amp; arg2 );
// ...
template&lt;typename T, typename Arg1, typename Arg2, ..., typename ArgN &gt;
shared_ptr&lt;T&gt; <a href="#functions">make_shared</a>( Arg1 const &amp; arg1, Arg2 const &amp; arg2, ..., ArgN const &amp; argN );
template&lt;typename T, typename A, typename Arg1 &gt;
shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( A const &amp; a, Arg1 const &amp; arg1 );
template&lt;typename T, typename A, typename Arg1, typename Arg2 &gt;
shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( Arg1 const &amp; arg1, Arg2 const &amp; arg2 );
// ...
template&lt;typename T, typename A, typename Arg1, typename Arg2, ..., typename ArgN &gt;
shared_ptr&lt;T&gt; <a href="#functions">allocate_shared</a>( A const &amp; a, Arg1 const &amp; arg1, Arg2 const &amp; arg2, ..., ArgN const &amp; argN );
#endif
}</pre>
<h2><a name="functions">Free Functions</a></h2>
<pre>template&lt;class T, class... Args&gt;
shared_ptr&lt;T&gt; make_shared( Args &amp;&amp; ... args );
template&lt;class T, class A, class... Args&gt;
shared_ptr&lt;T&gt; allocate_shared( A const &amp; a, Args &amp;&amp; ... args );</pre>
<blockquote>
<p><b>Requires:</b> The expression <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>,
where <code>pv</code> is a <code>void*</code> pointing to storage suitable
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&lt;Args&gt;(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 &amp;&amp; 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&lt;std::string&gt; x = boost::make_shared&lt;std::string&gt;("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>
</html>

5
shared_ptr.htm
View File

@@ -90,6 +90,11 @@ void bad()
shared_ptr </STRONG>constructor if <STRONG>g</STRONG> throws an exception. shared_ptr </STRONG>constructor if <STRONG>g</STRONG> throws an exception.
See <A href="http://www.gotw.ca/gotw/056.htm">Herb Sutter's treatment</A> (also <A href="http://www.cuj.com/reference/articles/2002/0212/0212_sutter.htm"> See <A href="http://www.gotw.ca/gotw/056.htm">Herb Sutter's treatment</A> (also <A href="http://www.cuj.com/reference/articles/2002/0212/0212_sutter.htm">
here</A>) of the issue for more information.</P> here</A>) of the issue for more information.</P>
<P>The exception safety problem described above may also be eliminated by using
the <a href="make_shared.html"><code>make_shared</code></a>
or <a href="make_shared.html"><code>allocate_shared</code></a>
factory functions defined in boost/make_shared.hpp. These factory functions also provide
an efficiency benefit by consolidating allocations.<P>
<h2><a name="Synopsis">Synopsis</a></h2> <h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost { <pre>namespace boost {

19
smart_ptr.htm
View File

@@ -22,7 +22,7 @@
keep track of dynamically allocated objects shared by multiple owners.</p> keep track of dynamically allocated objects shared by multiple owners.</p>
<p>Conceptually, smart pointers are seen as owning the object pointed to, and thus <p>Conceptually, smart pointers are seen as owning the object pointed to, and thus
responsible for deletion of the object when it is no longer needed.</p> responsible for deletion of the object when it is no longer needed.</p>
<p>The smart pointer library provides five smart pointer class templates:</p> <p>The smart pointer library provides six smart pointer class templates:</p>
<div align="left"> <div align="left">
<table border="1" cellpadding="4" cellspacing="0"> <table border="1" cellpadding="4" cellspacing="0">
<tr> <tr>
@@ -38,7 +38,7 @@
<tr> <tr>
<td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td> <td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
<td><a href="../../boost/shared_ptr.hpp">&lt;boost/shared_ptr.hpp&gt;</a></td> <td><a href="../../boost/shared_ptr.hpp">&lt;boost/shared_ptr.hpp&gt;</a></td>
<td>Object ownership shared among multiple pointers</td> <td>Object ownership shared among multiple pointers.</td>
</tr> </tr>
<tr> <tr>
<td><a href="shared_array.htm"><b>shared_array</b></a></td> <td><a href="shared_array.htm"><b>shared_array</b></a></td>
@@ -61,6 +61,17 @@
<p>They are examples of the "resource acquisition is initialization" idiom <p>They are examples of the "resource acquisition is initialization" idiom
described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition, described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition,
Section 14.4, Resource Management.</p> Section 14.4, Resource Management.</p>
<p>Additionally, the smart pointer library provides efficient factory functions
for creating <code>shared_ptr</code> 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</b></a></td>
<td><a href="../../boost/make_shared.hpp">&lt;boost/make_shared.hpp&gt;</a></td>
<td>Efficient creation of <code>shared_ptr</code> objects.</td>
</tr>
</table>
</div>
<p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is <p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
provided to verify correct operation.</p> provided to verify correct operation.</p>
<p>A page on <a href="compatibility.htm">compatibility</a> with older versions of <p>A page on <a href="compatibility.htm">compatibility</a> with older versions of
@@ -130,7 +141,7 @@
number of suggestions resulting in numerous improvements.</p> number of suggestions resulting in numerous improvements.</p>
<p>October 1998. Beman Dawes proposed reviving the original semantics under the <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 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<EFBFBD>hl, Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar K&uuml;hl,
Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new 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 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 follow the <b>std::auto_ptr</b> interface, and various function signatures and
@@ -156,7 +167,7 @@
as to run various timings of the direct and indirect approaches, and found that 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. at least on Intel Pentium chips there was very little measurable difference.
Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar
K<EFBFBD>hl suggested an elegant partial template specialization technique to allow K&uuml;hl suggested an elegant partial template specialization technique to allow
users to choose which implementation they preferred, and that was also users to choose which implementation they preferred, and that was also
experimented with.</p> experimented with.</p>
<p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage <p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage