| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|
| 2 | <html>
|
|---|
| 3 | <head>
|
|---|
| 4 | <title>make_shared and allocate_shared</title>
|
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|---|
| 6 | </head>
|
|---|
| 7 | <body text="#000000" bgColor="#ffffff">
|
|---|
| 8 | <h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
|
|---|
| 9 | border="0"></A>make_shared and allocate_shared function templates</h1>
|
|---|
| 10 | <p><A href="#Introduction">Introduction</A><br>
|
|---|
| 11 | <A href="#Synopsis">Synopsis</A><br>
|
|---|
| 12 | <A href="#functions">Free Functions</A><br>
|
|---|
| 13 | <A href="#example">Example</A><br>
|
|---|
| 14 | <h2><a name="Introduction">Introduction</a></h2>
|
|---|
| 15 | <p>Consistent use of <a href="shared_ptr.htm"><code>shared_ptr</code></a>
|
|---|
| 16 | can eliminate the need to use an explicit <code>delete</code>,
|
|---|
| 17 | but alone it provides no support in avoiding explicit <code>new</code>.
|
|---|
| 18 | There have been repeated requests from users for a factory function that creates
|
|---|
| 19 | an object of a given type and returns a <code>shared_ptr</code> to it.
|
|---|
| 20 | Besides convenience and style, such a function is also exception safe and
|
|---|
| 21 | considerably faster because it can use a single allocation for both the object
|
|---|
| 22 | and its corresponding control block, eliminating a significant portion of
|
|---|
| 23 | <code>shared_ptr</code>'s construction overhead.
|
|---|
| 24 | This eliminates one of the major efficiency complaints about <code>shared_ptr</code>.
|
|---|
| 25 | </p>
|
|---|
| 26 | <p>The header file <boost/make_shared.hpp> provides a family of overloaded function templates,
|
|---|
| 27 | <code>make_shared</code> and <code>allocate_shared</code>, to address this need.
|
|---|
| 28 | <code>make_shared</code> uses the global operator <code>new</code> to allocate memory,
|
|---|
| 29 | whereas <code>allocate_shared</code> uses an user-supplied allocator, allowing finer control.</p>
|
|---|
| 30 | <p>
|
|---|
| 31 | The rationale for choosing the name <code>make_shared</code> is that the expression
|
|---|
| 32 | <code>make_shared<Widget>()</code> can be read aloud and conveys the intended meaning.</p>
|
|---|
| 33 | <h2><a name="Synopsis">Synopsis</a></h2>
|
|---|
| 34 | <pre>namespace boost {
|
|---|
| 35 |
|
|---|
| 36 | template<typename T> class shared_ptr;
|
|---|
| 37 |
|
|---|
| 38 | template<typename T>
|
|---|
| 39 | shared_ptr<T> <a href="#functions">make_shared</a>();
|
|---|
| 40 |
|
|---|
| 41 | template<typename T, typename A>
|
|---|
| 42 | shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & );
|
|---|
| 43 |
|
|---|
| 44 | #if defined( BOOST_HAS_VARIADIC_TMPL ) && defined( BOOST_HAS_RVALUE_REFS ) // C++0x prototypes
|
|---|
| 45 |
|
|---|
| 46 | template<typename T, typename... Args>
|
|---|
| 47 | shared_ptr<T> <a href="#functions">make_shared</a>( Args && ... args );
|
|---|
| 48 |
|
|---|
| 49 | template<typename T, typename A, typename... Args>
|
|---|
| 50 | shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & a, Args && ... args );
|
|---|
| 51 |
|
|---|
| 52 | #else // no C++0X support
|
|---|
| 53 |
|
|---|
| 54 | template<typename T, typename Arg1 >
|
|---|
| 55 | shared_ptr<T> <a href="#functions">make_shared</a>( Arg1 const & arg1 );
|
|---|
| 56 | template<typename T, typename Arg1, typename Arg2 >
|
|---|
| 57 | shared_ptr<T> <a href="#functions">make_shared</a>( Arg1 const & arg1, Arg2 const & arg2 );
|
|---|
| 58 | // ...
|
|---|
| 59 | template<typename T, typename Arg1, typename Arg2, ..., typename ArgN >
|
|---|
| 60 | shared_ptr<T> <a href="#functions">make_shared</a>( Arg1 const & arg1, Arg2 const & arg2, ..., ArgN const & argN );
|
|---|
| 61 |
|
|---|
| 62 | template<typename T, typename A, typename Arg1 >
|
|---|
| 63 | shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & a, Arg1 const & arg1 );
|
|---|
| 64 | template<typename T, typename A, typename Arg1, typename Arg2 >
|
|---|
| 65 | shared_ptr<T> <a href="#functions">allocate_shared</a>( Arg1 const & arg1, Arg2 const & arg2 );
|
|---|
| 66 | // ...
|
|---|
| 67 | template<typename T, typename A, typename Arg1, typename Arg2, ..., typename ArgN >
|
|---|
| 68 | shared_ptr<T> <a href="#functions">allocate_shared</a>( A const & a, Arg1 const & arg1, Arg2 const & arg2, ..., ArgN const & argN );
|
|---|
| 69 |
|
|---|
| 70 | #endif
|
|---|
| 71 | }</pre>
|
|---|
| 72 | <h2><a name="functions">Free Functions</a></h2>
|
|---|
| 73 | <pre>template<class T, class... Args>
|
|---|
| 74 | shared_ptr<T> make_shared( Args && ... args );
|
|---|
| 75 | template<class T, class A, class... Args>
|
|---|
| 76 | shared_ptr<T> allocate_shared( A const & a, Args && ... args );</pre>
|
|---|
| 77 | <blockquote>
|
|---|
| 78 | <p><b>Requires:</b> The expression <code>new( pv ) T( std::forward<Args>(args)... )</code>,
|
|---|
| 79 | where <code>pv</code> is a <code>void*</code> pointing to storage suitable
|
|---|
| 80 | to hold an object of type <code>T</code>,
|
|---|
| 81 | shall be well-formed. <code>A</code> shall be an <em>Allocator</em>,
|
|---|
| 82 | as described in section 20.1.5 (<stong>Allocator requirements</strong>) of the C++ Standard.
|
|---|
| 83 | The copy constructor and destructor of <code>A</code> shall not throw.</p>
|
|---|
| 84 | <p><b>Effects:</b> Allocates memory suitable for an object of type <code>T</code>
|
|---|
| 85 | and constructs an object in it via the placement new expression <code>new( pv ) T()</code>
|
|---|
| 86 | or <code>new( pv ) T( std::forward<Args>(args)... )</code>.
|
|---|
| 87 | <code>allocate_shared</code> uses a copy of <code>a</code> to allocate memory.
|
|---|
| 88 | If an exception is thrown, has no effect.</p>
|
|---|
| 89 | <p><b>Returns:</b> A <code>shared_ptr</code> instance that stores and owns the address
|
|---|
| 90 | of the newly constructed object of type <code>T</code>.</p>
|
|---|
| 91 | <p><b>Postconditions:</b> <code>get() != 0 && use_count() == 1</code>.</p>
|
|---|
| 92 | <p><b>Throws:</b> <code>bad_alloc</code>, or an exception thrown from <code>A::allocate</code>
|
|---|
| 93 | or the constructor of <code>T</code>.</p>
|
|---|
| 94 | <p><b>Notes:</b> This implementation allocates the memory required for the
|
|---|
| 95 | returned <code>shared_ptr</code> and an object of type <code>T</code> in a single
|
|---|
| 96 | allocation. This provides efficiency equivalent to an intrusive smart pointer.</p>
|
|---|
| 97 | <p>The prototypes shown above are used if your compiler supports rvalue references
|
|---|
| 98 | and variadic templates. They perfectly forward the <code>args</code> parameters to
|
|---|
| 99 | the constructors of <code>T</code>.</p>
|
|---|
| 100 | <p>Otherwise, the implementation will fall back on
|
|---|
| 101 | forwarding the arguments to the constructors of <code>T</code> as const references.
|
|---|
| 102 | If you need to pass a non-const reference to a constructor of <code>T</code>,
|
|---|
| 103 | you may do so by wrapping the parameter in a call to <code>boost::ref</code>.
|
|---|
| 104 | In addition, you will be
|
|---|
| 105 | limited to a maximum of 9 arguments (not counting the allocator argument of
|
|---|
| 106 | allocate_shared).</p>
|
|---|
| 107 | </blockquote>
|
|---|
| 108 | <h2><a name="example">Example</a></h2>
|
|---|
| 109 | <pre>boost::shared_ptr<std::string> x = boost::make_shared<std::string>("hello, world!");
|
|---|
| 110 | std::cout << *x;</pre>
|
|---|
| 111 | <hr>
|
|---|
| 112 | <p>
|
|---|
| 113 | $Date: 2008-05-19 15:42:39 -0400 (Mon, 19 May 2008) $</p>
|
|---|
| 114 | <p><small>Copyright 2008 Peter Dimov. Copyright 2008 Frank Mori Hess.
|
|---|
| 115 | Distributed under the Boost Software License,
|
|---|
| 116 | Version 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
|
|---|
| 117 | or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
|
|---|
| 118 | </body>
|
|---|
| 119 | </html>
|
|---|
