forked from boostorg/smart_ptr
Merged [51699] and [51700] from trunk to release.
Closes #1897 [SVN r51703]
This commit is contained in:
Frank Mori Hess
119
make_shared.html
Normal file
119
make_shared.html
Normal 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 <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;
|
||||
|
||||
template<typename T>
|
||||
shared_ptr<T> <a href="#functions">make_shared</a>();
|
||||
|
||||
template<typename T, typename A>
|
||||
shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & );
|
||||
|
||||
#if defined( BOOST_HAS_VARIADIC_TMPL ) && defined( BOOST_HAS_RVALUE_REFS ) // C++0x prototypes
|
||||
|
||||
template<typename T, typename... Args>
|
||||
shared_ptr<T> <a href="#functions">make_shared</a>( Args && ... args );
|
||||
|
||||
template<typename T, typename A, typename... Args>
|
||||
shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & a, Args && ... args );
|
||||
|
||||
#else // no C++0X support
|
||||
|
||||
template<typename T, typename Arg1 >
|
||||
shared_ptr<T> <a href="#functions">make_shared</a>( Arg1 const & arg1 );
|
||||
template<typename T, typename Arg1, typename Arg2 >
|
||||
shared_ptr<T> <a href="#functions">make_shared</a>( Arg1 const & arg1, Arg2 const & arg2 );
|
||||
// ...
|
||||
template<typename T, typename Arg1, typename Arg2, ..., typename ArgN >
|
||||
shared_ptr<T> <a href="#functions">make_shared</a>( Arg1 const & arg1, Arg2 const & arg2, ..., ArgN const & argN );
|
||||
|
||||
template<typename T, typename A, typename Arg1 >
|
||||
shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & a, Arg1 const & arg1 );
|
||||
template<typename T, typename A, typename Arg1, typename Arg2 >
|
||||
shared_ptr<T> <a href="#functions">allocate_shared</a>( Arg1 const & arg1, Arg2 const & arg2 );
|
||||
// ...
|
||||
template<typename T, typename A, typename Arg1, typename Arg2, ..., typename ArgN >
|
||||
shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & a, Arg1 const & arg1, Arg2 const & arg2, ..., ArgN const & argN );
|
||||
|
||||
#endif
|
||||
}</pre>
|
||||
<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!");
|
||||
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>
|
||||
@@ -90,6 +90,11 @@ void bad()
|
||||
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">
|
||||
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>
|
||||
<pre>namespace boost {
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
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 five smart pointer class templates:</p>
|
||||
<p>The smart pointer library provides six smart pointer class templates:</p>
|
||||
<div align="left">
|
||||
<table border="1" cellpadding="4" cellspacing="0">
|
||||
<tr>
|
||||
@@ -38,7 +38,7 @@
|
||||
<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>
|
||||
<td>Object ownership shared among multiple pointers.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<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
|
||||
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 <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"><boost/make_shared.hpp></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
|
||||
provided to verify correct operation.</p>
|
||||
<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>
|
||||
<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<EFBFBD>hl,
|
||||
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
|
||||
@@ -156,7 +167,7 @@
|
||||
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<EFBFBD>hl suggested an elegant partial template specialization technique to allow
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user