Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

allocate_shared and make_shared for arrays

Introduction

Originally the Boost function templates allocate_shared and make_shared were for efficient allocation of shared scalar objects only. There was a need to have efficient allocation of shared arrays. One criticism of class template shared_array was always the lack of a utility like make_shared that uses only a single allocation.

The header files <boost/smart_ptr/allocate_shared_array.hpp> and <boost/smart_ptr/make_shared_array.hpp> provide function templates, overloads of allocate_shared and make_shared for array types, to address this need. allocate_shared uses a user-supplied allocator for allocation, while make_shared uses allocate_shared with the Default Allocator.

Synopsis

Header <boost/smart_ptr/allocate_shared_array.hpp>

namespace boost {
template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, std::size_t n);
template<class T, class A>
shared_ptr<T> allocate_shared(const A& a);
template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, std::size_t n, const E& v);
template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, const E& v);
template<class T, class A>
shared_ptr<T> allocate_shared_noinit(const A& a, std::size_t n);
template<class T, class A>
shared_ptr<T> allocate_shared_noinit(const A& a);
}

Header <boost/smart_ptr/make_shared_array.hpp>

namespace boost {
template<class T, class A>
shared_ptr<T> make_shared(std::size_t n);
template<class T, class A>
shared_ptr<T> make_shared();
template<class T, class A>
shared_ptr<T> make_shared(std::size_t n, const E& v);
template<class T, class A>
shared_ptr<T> make_shared(const E& v);
template<class T, class A>
shared_ptr<T> make_shared_noinit(std::size_t n);
template<class T, class A>
shared_ptr<T> make_shared_noinit();
}

Common Requirements

template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, args);

Requires:
T is of the form E[N] or E[]. A shall be an Allocator, as described in section 17.6.3.5 [Allocator requirements] of the C++ Standard. The copy constructor and destructor of A shall not throw exceptions.
Effects:
Allocates storage for an object of type E (or E[size] when T is E[], where size is determined from args as specified by the concrete overload). A copy of the allocator is used to allocate storage. The storage is initialized as specified by the concrete overload. If an exception is thrown, the functions have no effect.
Returns:
A shared_ptr instance that stores and owns the address of the newly allocated and constructed object.
Postconditions:
r.get() != 0 and r.use_count() == 1, where r is the return value.
Throws:
An exception thrown from A::allocate(), or from the initialization of the object.
Remarks:
  • 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 T is specified to be initialized to a value of the same type v, this shall be interpreted to mean that each array element of the object is initialized to the corresponding element from v.
  • When an object of an array type T 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 scalar type S is specified to be initialized to a value v, allocate_shared shall perform this initialization via the expression std::allocator_traits<A>::construct(b, p, v), where p points to storage suitable to hold an object of type S and b of is a copy of the allocator a passed to allocate_shared such that its value_type is S.
  • When a subobject of scalar type S is specified to be value-initialized, allocate_shared shall perform this initialization via the expression std::allocator_traits<A>::construct(b, p), where p points to storage suitable to hold an object of type S and b is a copy of the allocator a passed to allocate_shared such that its value_type is S.
  • When a subobject of scalar type S is specified to be default-initialized, allocate_shared_noinit shall perform this initialization via the expression ::new(p) S, where p has type void* and points to storage suitable to hold an object of type S.
  • 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.
Notes:
These functions will typically allocate more memory than the size of sizeof(E) to allow for internal bookkeeping structures such as the reference counts.

Free Functions

template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, std::size_t n);

Returns:
A shared_ptr to a value-initialized object of type E[size].
Remarks:
This overload shall only participate in overload resolution when T is of the form E[].
Example:
boost::allocate_shared<int[]>(std::allocator<int>(), 8);

template<class T, class A>
shared_ptr<T> allocate_shared(const A& a);

Returns:
A shared_ptr to a value-initialized object of type E[N].
Remarks:
This overload shall only participate in overload resolution when T is of the form E[N].
Example:
boost::allocate_shared<int[8]>(std::allocator<int>());

template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, std::size_t n, const E& v);

Returns:
A shared_ptr to an object of type E[size], where each array element of type E is initialized to v.
Remarks:
This overload shall only participate in overload resolution when T is of the form E[].
Example:
boost::allocate_shared<double[]>(std::allocator<double>(), 8, 1.0);

template<class T, class A>
shared_ptr<T> allocate_shared(const A& a, const E& v);

Returns:
A shared_ptr to an object of type E[N], where each array element of type E is initialized to v.
Remarks:
This overload shall only participate in overload resolution when T is of the form E[N].
Example:
boost::allocate_shared<double[8]>(std::allocator<double>(), 1.0);

template<class T, class A>
shared_ptr<T> allocate_shared_noinit(const A& a, std::size_t n);

Returns:
A shared_ptr to a default-initialized object of type E[size].
Remarks:
This overload shall only participate in overload resolution when T is of the form E[].
Example:
boost::allocate_shared_noinit<int[]>(std::allocator<int>(), 8);

template<class T, class A>
shared_ptr<T> allocate_shared_noinit(const A& a);

Returns:
A shared_ptr to a default-initialized object of type E[N].
Remarks:
This overload shall only participate in overload resolution when T is of the form E[N].
Example:
boost::allocate_shared_noinit<int[8]>(std::allocator<int>());

template<class T>
shared_ptr<T> make_shared(std::size_t n);

Returns:
allocate_shared<T>(std::allocator<S>(), n);
Remarks:
This overload shall only participate in overload resolution when T is of the form E[].
Example:
boost::make_shared<int[]>(8);

template<class T>
shared_ptr<T> make_shared();

Returns:
allocate_shared<T>(std::allocator<S>());
Remarks:
This overload shall only participate in overload resolution when T is of the form E[N].
Example:
boost::make_shared<int[8]>();

template<class T>
shared_ptr<T> make_shared(std::size_t n, const E& v);

Returns:
allocate_shared<T>(std::allocator<S>(), n, v);
Remarks:
This overload shall only participate in overload resolution when T is of the form E[].
Example:
boost::make_shared<double[]>(8, 1.0);

template<class T>
shared_ptr<T> make_shared(const E& v);

Returns:
allocate_shared<T>(std::allocator<S>(), v);
Remarks:
This overload shall only participate in overload resolution when T is of the form E[N].
Example:
boost::make_shared<double[8]>(1.0);

template<class T>
shared_ptr<T> make_shared_noinit(std::size_t n);

Returns:
allocate_shared_noinit<T>(std::allocator<S>(), n);
Remarks:
This overload shall only participate in overload resolution when T is of the form E[].
Example:
boost::make_shared_noinit<int[]>(8);

template<class T>
shared_ptr<T> make_shared_noinit();

Returns:
allocate_shared_noinit<T>(std::allocator<S>());
Remarks:
This overload shall only participate in overload resolution when T is of the form E[N].
Example:
boost::make_shared_noinit<int[8]>();

History

Boost 1.64
Glen Fernandes rewrote allocate_shared and make_shared for a more optimal and more maintainable implementation.
Boost 1.56
Glen Fernandes updated overloads of make_shared and allocate_shared to conform to the specification in C++ standard paper N3870, including resolving C++ standard library defect report DR 2070.
Boost 1.53
Glen Fernandes contributed implementations of make_shared and allocate_shared for arrays.

References

  1. N3870, Extending make_shared to Support Arrays, Revision 1, Peter Dimov & Glen Fernandes, January, 2014.
  2. DR 2070, allocate_shared should use allocator_traits<A>::construct, Jonathan Wakely, July, 2011.
Copyright 2012-2017 Glen Fernandes. Distributed under the Boost Software License, Version 1.0.