boost-react-native-bundle

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>make_shared and allocate_shared for arrays</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 for arrays</h1> <a href="#introduction">Introduction</a> <a href="#synopsis">Synopsis</a> <a href="#common">Common Requirements</a> <a href="#functions">Free Functions</a> <a href="#history">History</a> <a href="#references">References</a> <h2><a name="introduction">Introduction</a></h2> Originally the Boost function templates <code>make_shared</code> and <code>allocate_shared</code> were for efficient allocation of shared objects only. There was a need to have efficient allocation of shared arrays. One criticism of class template <code>shared_array</code> was always the lack of a <a href="make_shared.html">make_shared</a> utility which ensures only a single allocation. The header files <boost/smart_ptr/make_shared_array.hpp> and <boost/smart_ptr/allocate_shared_array.hpp> provide function templates, overloads of <code>make_shared</code> and <code>allocate_shared</code> for array types, 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. <h2><a name="synopsis">Synopsis</a></h2> <pre>namespace boost { template<class U> // U is T[] shared_ptr <a href="#functions">make_shared</a>(size_t size); template<class U, class A> // U is T[] shared_ptr <a href="#functions">allocate_shared</a>(const A& allocator, size_t size); template<class U> // U is T[N] shared_ptr <a href="#functions">make_shared</a>(); template<class U, class A> // U is T[N] shared_ptr <a href="#functions">allocate_shared</a>(const A& allocator); template<class U> // U is T[] shared_ptr <a href="#functions">make_shared</a>(size_t size, const T& value); template<class U, class A> // U is T[] shared_ptr <a href="#functions">allocate_shared</a>(const A& allocator, size_t size, const T& value); template<class U> // U is T[N] shared_ptr <a href="#functions">make_shared</a>(const T& value); template<class U, class A> // U is T[N] shared_ptr <a href="#functions">allocate_shared</a>(const A& allocator, const T& value); template<class U> // U is T[] shared_ptr <a href="#functions">make_shared_noinit</a>(size_t size); template<class U, class A> // U is T[] shared_ptr <a href="#functions">allocate_shared_noinit</a>(const A& allocator, size_t size); template<class U> // U is T[N] shared_ptr <a href="#functions">make_shared_noinit</a>(); template<class U, class A> // U is T[N] shared_ptr <a href="#functions">allocate_shared_noinit</a>(const A& allocator); }</pre> <h2><a name="common">Common Requirements</a></h2> <pre>template<class U> shared_ptr make_shared(args); template<class U, class A> shared_ptr allocate_shared(const A& allocator, args); template<class U> shared_ptr make_shared_noinit(args); template<class U, class A> shared_ptr allocate_shared_noinit(const A& allocator, args);</pre> <blockquote> Requires: <code>U</code> is of the form <code>T[]</code> or <code>T[N]</code>. <code>A</code> shall be an Allocator, as described in section 17.6.3.5 [Allocator requirements] of the C++ Standard. The copy constructor and destructor of <code>A</code> shall not throw exceptions. Effects: Allocates memory for an object of type <code>U</code> (or <code>T[size]</code> when <code>U</code> is <code>T[]</code>, where <code>size</code> is determined from <code>args</code> as specified by the concrete overload). The object is initialized as specified by the concrete overload. The templates <code>allocate_shared</code> and <code>allocate_shared_noinit</code> use a copy of <code>allocator</code> to allocate memory. If an exception is thrown, the functions have no effect. Returns: A <code>shared_ptr</code> instance that stores and owns the address of the newly constructed object. Postconditions: <code>r.get() != 0 && r.use_count() == 1</code>, where <code>r</code> is the return value. Throws: <code>bad_alloc</code>, an exception thrown from <code>A::allocate</code>, or from the initialization of the object. Remarks: <blockquote> This implementation performs no more than one memory allocation. This provides efficiency to equivalent to an intrusive smart pointer. When an object of an array type <code>T</code> is specified to be initialized to a value of the same type <code>value</code>, this shall be interpreted to mean that each array element of the object is initialized to the corresponding element from <code>value</code>. When an object of an array type is specified to be value-initialized, this shall be interpreted to mean that each array element of the object is value-initialized. Array elements are initialized in ascending order of their addresses. When a subobject of a non-array type <code>T</code> is specified to be initialized to a value <code>value</code>, <code>make_shared</code> shall perform this initialization via the expression <code>::new(ptr) T(value)</code>, where <code>ptr</code> has type <code>void*</code> and points to storage suitable to hold an object of type <code>T</code>. When a subobject of non-array type <code>T</code> is specified to be initialized to a value <code>value</code>, <code>allocate_shared</code> shall perform this initialization via the expression <code>allocator_traits<A2>::construct(a2, ptr, value)</code>, where <code>ptr</code> points to storage suitable to hold an object of type <code>T</code> and <code>a2</code> of type A2 is a rebound copy of the allocator <code>allocator</code> passed to <code>allocate_shared</code> such that its <code>value_type</code> is <code>T</code>. When a subobject of non-array type <code>T</code> is specified to be value-initialized, <code>make_shared</code> shall perform this initialization via the expression <code>::new(ptr) T()</code>, where <code>ptr</code> has type <code>void*</code> and points to storage suitable to hold an object of type <code>T</code>. When a subobject of non-array type <code>T</code> is specified to be value-initialized, <code>allocate_shared</code> shall perform this initialization via the expression <code>allocator_traits<A2>::construct(a2, ptr)</code>, where <code>ptr</code> points to storage suitable to hold an object of type <code>T</code> and <code>a2</code> of type A2 is a rebound copy of the allocator <code>allocator</code> passed to <code>allocate_shared</code> such that its <code>value_type</code> is <code>T</code>. When a subobject of non-array type <code>T</code> is specified to be default-initialized, <code>make_shared_noinit</code> and <code>allocate_shared_noinit</code> shall perform this initialization via the expression <code>::new(ptr) T</code>, where <code>ptr</code> has type <code>void*</code> and points to storage suitable to hold an object of type <code>T</code>. When the lifetime of the object managed by the return value ends, or when the initialization of an array element throws an exception, the initialized elements should be destroyed in the reverse order of their construction. </blockquote> Notes: These functions will typically allocate more memory than <code>sizeof(U)</code> to allow for internal bookkeeping structures such as the reference counts. </blockquote> <h2><a name="functions">Free Functions</a></h2> <pre>template<class U> shared_ptr make_shared(size_t size); template<class U, class A> shared_ptr allocate_shared(const A& allocator, size_t size);</pre> <blockquote> Returns: A <code>shared_ptr</code> to a value-initialized object of type <code>T[size]</code>. Remarks: These overloads shall only participate in overload resolution when <code>U</code> is of the form <code>T[]</code>. Examples: <blockquote> <pre>boost::shared_ptr<int[]> a1 = boost::make_shared<int[]>(size); boost::shared_ptr<int[][2]> a2 = boost::make_shared<int[][2]>(size);</pre> </blockquote> </blockquote> <pre>template<class U> shared_ptr make_shared(); template<class U, class A> shared_ptr allocate_shared(const A& allocator);</pre> <blockquote> Returns: A <code>shared_ptr</code> to a value-initialized object of type <code>T[N]</code>. Remarks: These overloads shall only participate in overload resolution when <code>U</code> is of the form <code>T[N]</code>. Examples: <blockquote> <pre>boost::shared_ptr<int[8]> a1 = boost::make_shared<int[8]>(); boost::shared_ptr<int[4][2]> a2 = boost::make_shared<int[4][2]>();</pre> </blockquote> </blockquote> <pre>template<class U> shared_ptr make_shared(size_t size, const T& value); template<class U, class A> shared_ptr allocate_shared(const A& allocator, size_t size, const T& value);</pre> <blockquote> Returns: A <code>shared_ptr</code> to an object of type <code>T[size]</code>, where each array element of type <code>T</code> is initialized to <code>value</code>. Remarks: These overloads shall only participate in overload resolution when <code>U</code> is of the form <code>T[]</code>. Examples: <blockquote> <pre>boost::shared_ptr<int[]> a1 = boost::make_shared<int[]>(size, 1); boost::shared_ptr<int[][2]> a2 = boost::make_shared<int[][2]>(size, {1, 2});</pre> </blockquote> </blockquote> <pre>template<class U> shared_ptr make_shared(const T& value); template<class U, class A> shared_ptr allocate_shared(const A& allocator, const T& value);</pre> <blockquote> Returns: A <code>shared_ptr</code> to an object of type <code>T[N]</code>, where each array element of type <code>T</code> is initialized to <code>value</code>. Remarks: These overloads shall only participate in overload resolution when <code>U</code> is of the form <code>T[N]</code>. Examples: <blockquote> <pre>boost::shared_ptr<int[8]> a1 = boost::make_shared<int[8]>(1); boost::shared_ptr<int[4][2]> a2 = boost::make_shared<int[4][2]>({1, 2});</pre> </blockquote> </blockquote> <pre>template<class U> shared_ptr make_shared_noinit(size_t size); template<class U, class A> shared_ptr allocate_shared_noinit(const A& allocator, size_t size);</pre> <blockquote> Returns: A <code>shared_ptr</code> to a default-initialized object of type <code>T[size]</code>. Remarks: These overloads shall only participate in overload resolution when <code>U</code> is of the form <code>T[]</code>. Examples: <blockquote> <pre>boost::shared_ptr<int[]> a1 = boost::make_shared_noinit<int[]>(size); boost::shared_ptr<int[][2]> a2 = boost::make_shared_noinit<int[][2]>(size);</pre> </blockquote> </blockquote> <pre>template<class U> shared_ptr make_shared_noinit(); template<class U, class A> shared_ptr allocate_shared_noinit(const A& allocator);</pre> <blockquote> Returns: A <code>shared_ptr</code> to a default-initialized object of type <code>T[N]</code>. Remarks: These overloads shall only participate in overload resolution when <code>U</code> is of the form <code>T[N]</code>. Examples: <blockquote> <pre>boost::shared_ptr<int[8]> a1 = boost::make_shared_noinit<int[8]>(); boost::shared_ptr<int[4][2]> a2 = boost::make_shared_noinit<int[4][2]>();</pre> </blockquote> </blockquote> <h2><a name="history">History</a></h2> February 2014. Glen Fernandes updated overloads of make_shared and allocate_shared to conform to the specification in C++ standard paper <a href="#N3870">N3870</a>, including resolving C++ standard library defect report 2070, and reduced the spatial overhead of the internal bookkeeping structures. November 2012. Glen Fernandes contributed implementations of make_shared and allocate_shared for arrays. <h2><a name="references">References</a></h2> <a name="N3870">N3870</a>, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html"> Extending make_shared to Support Arrays, Revision 1</a>, Peter Dimov & Glen Fernandes, January, 2014. <hr> $Date$ Copyright 2012-2014 Glen Fernandes. 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>. </body> </html>