-<!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;
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
+#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 );
#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>
-
<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>
projects / platform / upstream / boost.git / blobdiff