# 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.