Namespaces
Variants
Views
Actions

std::allocate_shared

From cppreference.com
< cpp‎ | memory‎ | shared ptr
 
 
 
Dynamic memory management
Uninitialized storage
(C++17)
(deprecated since c++17)
(deprecated since c++17)
(deprecated since c++17)
Garbage collection support
Miscellaneous
(C++11)
(C++11)
C Library
Low level memory management
 
 
Defined in header <memory>
template< class T, class Alloc, class... Args >
shared_ptr<T> allocate_shared( const Alloc& alloc, Args&&... args );
(since C++11)

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.

All memory allocation is done using a copy of alloc, which must satisfy the Allocator requirements.

The std::shared_ptr constructor called by this function enables shared_from_this with a pointer to the newly constructed object of type T.

Contents

[edit] Parameters

alloc - The Allocator to use.
args... - list of arguments with which an instance of T will be constructed.

[edit] Return value

std::shared_ptr of an instance of type T.

[edit] Exceptions

Can throw the exceptions thrown from Alloc::allocate() or from the constructor of T. If an exception is thrown, this function has no effect.

[edit] Notes

This function typically allocates memory for the T object and for the shared_ptr's control block with a single memory allocation (it is a non-binding requirement in the Standard). In contrast, the declaration std::shared_ptr<T> p(new T(Args...)) performs at least two memory allocations, which may incur unnecessary overhead.

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.

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

A constructor enables shared_from_this with a pointer ptr of type U* means that it determines if U has an unambiguous and accessible 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.

[edit] See also

constructs new shared_ptr
(public member function) [edit]
creates a shared pointer that manages a new object
(function template) [edit]