std::allocate_shared

Defined in header `<memory>`
template< class T, class Alloc, class... Args > shared_ptr<T> allocate_shared( const Alloc& alloc, Args&&... args );	(1)	(since C++11) (T is non-array)
template<class T, class A> shared_ptr<T> allocate_shared(const A& a, std::size_t N);	(2)	(since C++20) (T is U[])
template<class T, class A> shared_ptr<T> allocate_shared(const A& a);	(3)	(since C++20) (T is U[N])
template<class T, class A> shared_ptr<T> allocate_shared(const A& a, std::size_t N, const std::remove_extent_t<T>& u);	(4)	(since C++20) (T is U[])
template<class T, class A> shared_ptr<T> allocate_shared(const A& a, const std::remove_extent_t<T>& u);	(5)	(since C++20) (T is U[N])

1) Constructs an object of type T and wraps it in a std::shared_ptr using args as the parameter list for the constructor of T. The object is constructed as if by the expression std::allocator_traits<A2>::construct(a, pv, v)), where pv is an internal void* pointer to storage suitable to hold an object of type T and a is a copy of the allocator rebound to std::remove_cv_t<T>. The storage is typically larger than sizeof(T) in order to use one allocation for both the control block of the shared pointer and the T object. The std::shared_ptr constructor called by this function enables shared_from_this with a pointer to the newly constructed object of type T. All memory allocation is done using a copy of alloc, which must satisfy the Allocator requirements. This overload only participates in overload resolution if T is not an array type

2,3) Same as (1), but the object constructed is a possibly-multidimensional array whose every non-array element is initialized as if by the expression std::allocator_traits<A2>::construct(a2, pv) where a2 of type A2 is the copy of the allocator rebound to manage objects of type std::remove_cv_t<std::remove_all_extents_t<T>>. The overload (2) creates an array of size N along its first dimension. The array elements are initialized in ascending order of their addresses, and when their lifetime ends are destroyed in the reverse order of their original construction.

4,5) Same as (2,3), but the elements of the array are initialized from the default value u. If std::remove_extent_t<T> is not itself an array type, then this is performed as if by the same allocator expression as in (1), except that the allocator is rebound to the std::remove_cv_t<std::remove_all_extents_t<T>>. Otherwise, this is performed as if by initializing every non-array element of the (possibly multidimensional) array with the corresponding element from u using the same allocator expression as in (1), except that the allocator is rebound to the type std::remove_cv_t<std::remove_all_extents_t<T>>. The overload (4) creates an array of size N along the first dimension. The array elements are initialized in ascending order of their addresses, and when their lifetime ends are destroyed in the reverse order of their original construction.

Parameters

alloc	-	The Allocator to use.
args...	-	list of arguments with which an instance of `T` will be constructed.
N	-	array size to use
u	-	the initial value to initialize every element of the array

Return value

std::shared_ptr of an instance of type T.

Exceptions

Can throw the exceptions thrown from Alloc::allocate() or from the constructor of T. If an exception is thrown, (1) has no effect. If an exception is thrown during the construction of the array, already-initialized elements are destroyed in reverse order (since C++20)

Notes

Like std::make_shared, this function typically performs only one allocation, and places both the T object and the control block in the allocated memory block (the standard recommends but does not require this, all known implementations do this). A copy of alloc is stored as part of the control block so that it can be used to deallocate it once both shared and weak reference counts reach zero.

Unlike the std::shared_ptr constructors, std::allocate_shared does not accept a separate custom deleter: the supplied allocator is used for destruction of the control block and the T object, and for deallocation of their shared memory block.

std::shared_ptr supports array types (as of C++17), but std::allocate_shared does not. This functionality is supported by boost::allocate_shared

(until C++20)

A constructor enables shared_from_this with a pointer ptr of type U* means that it determines if U has an unambiguous and accessible (since C++17) base class that is a specialization of std::enable_shared_from_this, and if so, the constructor evaluates the statement:

if (ptr != nullptr && ptr->weak_this.expired())
  ptr->weak_this = std::shared_ptr<std::remove_cv_t<U>>(*this,
                                  const_cast<std::remove_cv_t<U>*>(ptr));

Where weak_this is the hidden mutable std::weak_ptr member of std::shared_from_this. The assignment to the weak_this member is not atomic and conflicts with any potentially concurrent access to the same object. This ensures that future calls to shared_from_this() would share ownership with the shared_ptr created by this raw pointer constructor.

The test ptr->weak_this.expired() in the exposition code above makes sure that weak_this is not reassigned if it already indicates an owner. This test is required as of C++17.

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 3007		`allocate_shared` may (incorrectly) rebind allocator to cv-qualified type	remove cv-qualifiers before rebind

Language
Headers
Freestanding and hosted implementations
Named requirements
Language support library
Concepts library (C++20)
Diagnostics library
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

Member functions
shared_ptr::shared_ptr
shared_ptr::~shared_ptr
shared_ptr::operator=
Modifiers
shared_ptr::reset
shared_ptr::swap
Observers
shared_ptr::get
shared_ptr::operator*shared_ptr::operator->
shared_ptr::operator[] (C++17)
shared_ptr::use_count
shared_ptr::unique (until C++20)
shared_ptr::operator bool
shared_ptr::owner_before
Non-member functions
std::swap
make_shared
allocate_shared
static_pointer_castdynamic_pointer_castconst_pointer_castreinterpret_pointer_cast (C++17)
get_deleter
operator==operator\|=operator<operator<=operator>operator>=
operator<<
atomic_xxx functions (deprecated in C++20)
std::atomic<std::shared_ptr> (C++20)
std::hash
Deduction guides(C++17)