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