bsl::shared_ptr

Synopsis

Declared in <bslstl_sharedptr.h>

template<class ELEMENT_TYPE>
class shared_ptr;

Description

Note that the object referred to by a shared pointer representation is usually the same as the object referred to by that shared pointer (of the same ELEMENT_TYPE), but this need not always be true in the presence of conversions or "aliasing": the object referred to (of template parameter type ELEMENT_TYPE) by the shared pointer may differ from the object of type COMPATIBLE_TYPE (see the "Aliasing" section in the component-level documentation) referred to by the shared pointer representation.

More generally, this class supports a complete set of in-core pointer semantic operations.

Type Aliases

Name	Description
`element_type`	For shared pointers to non-array types, `element_type` is an alias to the `ELEMENT_TYPE` template parameter. Otherwise, it is an alias to the type contained in the array.
`weak_type`	`weak_type` is an alias to a weak pointer with the same element type as this `shared_ptr`.

Member Functions

Name	Description
`shared_ptr` [constructor]	Constructors
`~shared_ptr` [destructor]	Destroy this shared pointer. If this shared pointer refers to a (possibly shared) object, then release the reference to that object, and destroy the shared object using its associated deleter if this shared pointer is the last reference to that object.
`operator=`	Assignment operators
`clear`	Reset this shared pointer to the empty state. If this shared pointer is managing a (possibly shared) object, then release the reference to the shared object, calling the associated deleter to destroy the shared object if this shared pointer is the last reference. Note that the behavior of this method is the same as `reset()`.
`createInplace`	`createInplace` overloads
`get`	Return the address providing modifiable access to the object referred to by this shared pointer, or 0 if this shared pointer does not refer to an object.
`load`	`load` overloads
`loadAlias`	Modify this shared pointer to manage the same modifiable object (if any) as the specified `source` shared pointer to the (template parameter) type `ANY_TYPE`, and refer to the modifiable object at the specified `object` address (i.e., make this shared pointer an "alias" of `source`). If this shared pointer is already managing a (possibly shared) object, then release the shared reference to that shared object, and destroy it using its associated deleter if this shared pointer held the last shared reference to that object. Note that typically the objects referred to by `source` and `object` have identical lifetimes (e.g., one might be a part of the other), so that the deleter for `source` will destroy them both, but they do not necessarily have the same type. Also note that if `source` is empty, then this shared pointer will be reset to an empty state, even if `object` is not null (in which case this empty shared pointer will refer to the same object as `object`). Also note that if `object` is null and `source` is not empty, then this shared pointer will be reset to a (reference-counted) null pointer alias. Also note that this function is logically equivalent to: ` *this = shared_ptr<ELEMENT_TYPE>(source, object); ` Further note that the behavior of this method is the same as `reset(source, object)`.
`managedPtr`	Return a managed pointer that refers to the same object as this shared pointer. If this shared pointer is not empty, and is not null, then increment the shared count on the shared object, and give the managed pointer a deleter that decrements the reference count for the shared object. Note that if this `shared_ptr` is reference- counting a null pointer, the empty `bslma::ManagedPtr` returned will not participate in that shared ownership.
`numReferences`	Return a "snapshot" of the number of shared pointers (including this one) that share ownership of the object managed by this shared pointer. Note that the behavior of this function is the same as `use_count`, and the result may be unreliable in multi-threaded code for the same reasons.
`operator*`	Return a reference providing modifiable access to the object referred to by this shared pointer. The behavior is undefined unless this shared pointer refers to an object, and `ELEMENT_TYPE` is not (potentially `const` or `volatile` qualified) `void`.
`operator->`	Return the address providing modifiable access to the object referred to by this shared pointer, or 0 if this shared pointer does not refer to an object. Note that applying this operator conventionally (e.g., to invoke a method) to an shared pointer that does not refer to an object will result in undefined behavior.
`operator[]`	Return a reference providing modifiable access to the object at the specified `index` offset in the object referred to by this shared pointer. The behavior is undefined unless this shared pointer is not empty, `ELEMENT_TYPE` is not `void` (a compiler error will be generated if this operator is instantiated within the `shared_ptr<void>` class), and this shared pointer refers to an array of `ELEMENT_TYPE` objects. Instead of `element_type &`, we use `add_lvalue_reference<element_type>::type` for the return type because that allows people to instantiate `shared_ptr<cv_void>`, as long as they don't use this method. Note that this method is logically equivalent to `*(get() + index)`.
`owner_before`	`owner_before` overloads
`owner_equal`	`owner_equal` overloads
`owner_hash`	Return an unspecified value such that, for any object `x` where `owner_equal(x)` is true, `owner_hash() == x.owner_hash()` is true. Note that this is based on the hash of the address of the `BloombergLP::bslma::SharedPtrRep` object used by this object. Note also that for two empty smart pointers `x` and `y`, `x.owner_hash() == y.owner_hash()` is true.
`ptr`	Return the address providing modifiable access to the object referred to by this shared pointer, or 0 if this shared pointer does not refer to an object. Note that the behavior of this function is the same as `get`.
`release`	Return the pair consisting of the addresses of the modifiable `ELEMENT_TYPE` object referred to, and the representation shared by, this shared pointer, and reset this shared pointer to the empty state, referring to no object, with no effect on the representation. The reference counter is not modified nor is the shared object deleted; if the reference count of the representation is greater than one, then it is not safe to release the representation (thereby destroying the shared object), but it is always safe to create another shared pointer with the representation using the constructor with the following signature: ` 'shared_ptr(ELEMENT_TYPE ptr, BloombergLP::bslma::SharedPtrRep rep)' ` Note that this function returns a pair of null pointers if this shared pointer is empty.
`rep`	Return the address providing modifiable access to the `BloombergLP::bslma::SharedPtrRep` object used by this shared pointer, or 0 if this shared pointer is empty.
`reset`	`reset` overloads
`swap`	Efficiently exchange the states of this shared pointer and the specified `other` shared pointer such that each will refer to the object formerly referred to by the other and each will manage the object formerly managed by the other.
`unique`	Return `true` if this shared pointer is not empty and does not share ownership of the object it managed with any other shared pointer, and `false` otherwise. Note that a shared pointer with a custom deleter can refer to a null pointer without being empty, and so may be `unique`. Also note that the result of this function may not be reliable in a multi-threaded program, where a weak pointer may be locked on another thread.
`use_count`	Return a "snapshot" of the number of shared pointers (including this one) that share ownership of the object managed by this shared pointer. Note that 0 is returned if this shared pointer is empty. Also note that any result other than 0 may be unreliable in a multi-threaded program, where another pointer sharing ownership in a different thread may be copied or destroyed, or a weak pointer may be locked in the case that 1 is returned (that would otherwise indicate unique ownership).
`operator BloombergLP::bslmf::NestedTraitDeclaration<shared_ptr<ELEMENT_TYPE>, is_nothrow_move_constructible>`	Nested trait declaration for `is_nothrow_move_constructible`.
`operator BoolType`	Return a value of an "unspecified bool" type that evaluates to `false` if this shared pointer does not refer to an object, and `true` otherwise. Note that this conversion operator allows a shared pointer to be used within a conditional context (e.g., within an `if` or `while` statement), but does not allow shared pointers to unrelated types to be compared (e.g., via `<` or `>`).

Deduction Guides

Name	Description
`shared_ptr<ELEMENT_TYPE>`	Deduce the specified type `ELEMENT_TYPE` corresponding template parameter of the `bslma::ManagedPtr` supplied to the constructor of `shared_ptr`.
`shared_ptr<ELEMENT_TYPE>`	Deduce the specified type `ELEMENT_TYPE` corresponding template parameter of the `bsl::weak_ptr` supplied to the constructor of `shared_ptr`.
`shared_ptr<ELEMENT_TYPE>`	Deduce the specified type `ELEMENT_TYPE` corresponding template parameter of the `std::unique_ptr` supplied to the constructor of `shared_ptr`.
`shared_ptr<ELEMENT_TYPE>`	Deduce the specified type `ELEMENT_TYPE` corresponding template parameter of the `bslma::ManagedPtr` supplied to the constructor of `shared_ptr`. This guide does not participate in deduction unless the specified `ALLOC` inherits from `bslma::Allocator`.
`shared_ptr<ELEMENT_TYPE>`	Deduce the specified type `ELEMENT_TYPE` corresponding template parameter of the `std::unique_ptr` supplied to the constructor of `shared_ptr`. This guide does not participate in deduction unless the specified `ALLOC` inherits from `bslma::Allocator`.

Friends

Name Description

bsl::shared_ptr This class provides a thread-safe reference-counted "smart pointer" to support "shared ownership" of objects: a shared pointer ensures that the shared object is destroyed, using the appropriate deletion method, only when there are no shared references to it. The object (of template parameter type ELEMENT_TYPE) referred to by a shared pointer may be accessed directly using the -> operator, or the dereference operator (operator *) can be used to obtain a reference to that object.

Name	Description
`bsl::shared_ptr`	This class provides a thread-safe reference-counted "smart pointer" to support "shared ownership" of objects: a shared pointer ensures that the shared object is destroyed, using the appropriate deletion method, only when there are no shared references to it. The object (of template parameter type `ELEMENT_TYPE`) referred to by a shared pointer may be accessed directly using the `->` operator, or the dereference operator (operator `*`) can be used to obtain a reference to that object.

Non-Member Functions

Name	Description
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ELEMENT_TYPE` object. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ELEMENT_TYPE` object, which is initialized by calling `allocator_traits<ALLOC>::construct` passing `basicAllocator`, an `ELEMENT_TYPE *` pointer to space for the new shared object, and the specified arguments `std::forward<ARGS>(args)...`.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and each element in the array is constructed from the specified `value`.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and each element in the array is constructed from the specified `value`. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and each element in the array is default constructed. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and each element in the array is constructed from the specified `value`.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and each element in the array is default constructed.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and each element in the array is default constructed. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ELEMENT_TYPE` object. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ELEMENT_TYPE` object, which is initialized using the `ELEMENT_TYPE` constructor that takes the specified arguments `std::forward<ARGS>(args)...`. If `ELEMENT_TYPE` uses `bslma` allocators, then `basicAllocator` is passed as an extra argument in the final position. If `basicAllocator` is 0, then the default allocator will be used instead, and passed as the allocator, when appropriate, to the `ELEMENT_TYPE` constructor.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and each element in the array is constructed from the specified `value`. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and each element in the array is default constructed.
`allocate_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and the array is default-constructed. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ELEMENT_TYPE` object. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ELEMENT_TYPE` object, which is default-constructed. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ELEMENT_TYPE` object. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ELEMENT_TYPE` object, which is default-constructed.
`allocate_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and the array is default-constructed.
`allocate_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and the array is default-constructed. If `basicAllocator` is 0, then the default allocator will be used instead.
`allocate_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The specified `basicAllocator` will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and the array is default-constructed.
`const_pointer_cast`	Return a `shared_ptr<TO_TYPE>` object sharing ownership of the same object as the specified `source` shared pointer to the (template parameter) `FROM_TYPE`, and referring to `const_cast<TO_TYPE >(source.get())`. Note that if `source` cannot be `const`-cast to `TO_TYPE `, then a compiler diagnostic will be emitted indicating the error.
`dynamic_pointer_cast`	Return a `shared_ptr<TO_TYPE>` object sharing ownership of the same object as the specified `source` shared pointer to the (template parameter) `FROM_TYPE`, and referring to `dynamic_cast<TO_TYPE>(source.get())`. If `source` cannot be dynamically cast to `TO_TYPE `, then an empty `shared_ptr<TO_TYPE>` object is returned.
`get_deleter`	Return the address of deleter used by the specified `p` shared pointer if the (template parameter) type `DELETER` is the type of the deleter installed in `p`, and a null pointer value otherwise.
`make_shared`	Return a `shared_ptr` object referring to and managing a new `ELEMENT_TYPE` object. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ELEMENT_TYPE` object, which is initialized using the `ELEMENT_TYPE` constructor that takes the specified arguments `std::forward<ARGS>(args)...`. If `ELEMENT_TYPE` uses `bslma` allocators, then the default allocator is passed as an extra argument in the final position.
`make_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and each element in the array is constructed from the specified `value`.
`make_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and each element in the array is default constructed.
`make_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and each element in the array is constructed from the specified `value`.
`make_shared`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and each element in the array is default constructed.
`make_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a unbounded array. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` containing the specified `numElements` number of elements, and the array is default-constructed.
`make_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ELEMENT_TYPE` object. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ELEMENT_TYPE` object, which is default-constructed.
`make_shared_for_overwrite`	Return a `shared_ptr` object referring to and managing a new `ARRAY_TYPE` object, where `ARRAY_TYPE` is a bounded array. The default allocator will be used to supply a single contiguous region of memory holding the returned shared pointer's internal representation and the new `ARRAY_TYPE` object, and the array is default-constructed.
`operator<=>`	Perform a three-way comparison of the specified `ptr` and null pointer by using the comparison operators of `TYPE *`; return the result of that comparison.
`operator<=>`	Perform a three-way comparison of the specified `lhs` and the specified `rhs` pointers by using the comparison operators of `LHS_TYPE ` and `RHS_TYPE `; return the result of that comparison.
`operator==`	Return `true` if the specified `lhs` shared pointer refers to the same object (if any) as that referred to by the specified `rhs` shared pointer (if any), and `false` otherwise; a compiler diagnostic will be emitted indicating the error unless a (raw) pointer to `LHS_TYPE` can be compared to a (raw) pointer to `RHS_TYPE`. Note that two shared pointers that compare equal do not necessarily manage the same object due to aliasing.
`operator==`	Return `true` if the specified `lhs` shared pointer does not refer to an object, and `false` otherwise.
`reinterpret_pointer_cast`	Return a `shared_ptr<TO_TYPE>` object sharing ownership of the same object as the specified `source` shared pointer to the (template parameter) `FROM_TYPE`, and referring to `reinterpret_cast<TO_TYPE >(source.get())`. Note that if `source` cannot be reinterpret_cast-ed to `TO_TYPE `, then a compiler diagnostic will be emitted indicating the error.
`static_pointer_cast`	Return a `shared_ptr<TO_TYPE>` object sharing ownership of the same object as the specified `source` shared pointer to the (template parameter) `FROM_TYPE`, and referring to `static_cast<TO_TYPE >(source.get())`. Note that if `source` cannot be statically cast to `TO_TYPE `, then a compiler diagnostic will be emitted indicating the error.
`swap`	Efficiently exchange the states of the specified `a` and `b` shared pointers such that each will refer to the object formerly referred to by the other, and each will manage the object formerly managed by the other.