std::shared_ptr<T>::reset
void reset() noexcept; | (1) |
(since C++11) (constexpr since C++26) |
template< class Y > void reset( Y* ptr ); | (2) |
(since C++11) (constexpr since C++26) |
template< class Y, class Deleter > void reset( Y* ptr, Deleter d ); | (3) |
(since C++11) (constexpr since C++26) |
template< class Y, class Deleter, class Alloc > void reset( Y* ptr, Deleter d, Alloc alloc ); | (4) |
(since C++11) (constexpr since C++26) |
Replaces the managed object with an object pointed to by ptr. Optional deleter d can be supplied, which is later used to destroy the new object when no shared_ptr objects own it.
If *this already owns an object and it is the last shared_ptr owning it, the object is destroyed through the owned deleter.
1) Releases the ownership of the managed object (if any). After the call,
*this manages no object.
Equivalent to
shared_ptr<T>().swap(*this);.
2-4) Replaces the managed object with an object pointed to by
ptr.
2) Uses the delete expression as the deleter.
Equivalent to
shared_ptr<T>(ptr).swap(*this);.
3) Uses the specified deleter
d as the deleter.
Equivalent to
shared_ptr<T>(ptr, d).swap(*this);.
4) Same as (3), but additionally uses a copy of
alloc for allocation of data for internal use.
Equivalent to
shared_ptr<T>(ptr, d, alloc).swap(*this);.Parameters
| ptr | - | pointer to an object to acquire ownership of |
| d | - | deleter to store for deletion of the object |
| alloc | - | allocator to use for internal allocations |
Notes
Proper delete expression corresponding to the supplied type is always selected, this is the reason why the function is implemented as template using a separate parameter Y.
In order for the internally invoked shared_ptr constructor to have well-defined behavior, the same conditions also need to be satisfied. For example, if the object pointed to by ptr is already owned by another shared_ptr, invoking the function generally results in undefined behavior.
Exceptions
2)
std::bad_alloc if required additional memory could not be obtained. May throw implementation-defined exception for other errors. delete ptr is evaluated if an exception occurs.
3,4)
std::bad_alloc if required additional memory could not be obtained. May throw implementation-defined exception for other errors. d(ptr) is evaluated if an exception occurs.Example
#include <iostream>
#include <memory>
struct Foo
{
Foo(int n = 0) noexcept : bar(n)
{
std::cout << "Foo::Foo(), bar = " << bar << " @ " << this << '\n';
}
~Foo()
{
std::cout << "Foo::~Foo(), bar = " << bar << " @ " << this << '\n';
}
int getBar() const noexcept { return bar; }
private:
int bar;
};
int main()
{
std::cout << "1) unique ownership\n";
{
std::shared_ptr<Foo> sptr = std::make_shared<Foo>(100);
std::cout << "Foo::bar = " << sptr->getBar() << ", use_count() = "
<< sptr.use_count() << '\n';
// Reset the shared_ptr without handing it a fresh instance of Foo.
// The old instance will be destroyed after this call.
std::cout << "call sptr.reset()...\n";
sptr.reset(); // calls Foo's destructor here
std::cout << "After reset(): use_count() = " << sptr.use_count()
<< ", sptr = " << sptr << '\n';
} // No call to Foo's destructor, it was done earlier in reset().
std::cout << "\n2) unique ownership\n";
{
std::shared_ptr<Foo> sptr = std::make_shared<Foo>(200);
std::cout << "Foo::bar = " << sptr->getBar() << ", use_count() = "
<< sptr.use_count() << '\n';
// Reset the shared_ptr, hand it a fresh instance of Foo.
// The old instance will be destroyed after this call.
std::cout << "call sptr.reset()...\n";
sptr.reset(new Foo{222});
std::cout << "After reset(): use_count() = " << sptr.use_count()
<< ", sptr = " << sptr << "\nLeaving the scope...\n";
} // Calls Foo's destructor.
std::cout << "\n3) multiple ownership\n";
{
std::shared_ptr<Foo> sptr1 = std::make_shared<Foo>(300);
std::shared_ptr<Foo> sptr2 = sptr1;
std::shared_ptr<Foo> sptr3 = sptr2;
std::cout << "Foo::bar = " << sptr1->getBar() << ", use_count() = "
<< sptr1.use_count() << '\n';
// Reset the shared_ptr sptr1, hand it a fresh instance of Foo.
// The old instance will stay shared between sptr2 and sptr3.
std::cout << "call sptr1.reset()...\n";
sptr1.reset(new Foo{333});
std::cout << "After reset():\n"
<< "sptr1.use_count() = " << sptr1.use_count()
<< ", sptr1 @ " << sptr1 << '\n'
<< "sptr2.use_count() = " << sptr2.use_count()
<< ", sptr2 @ " << sptr2 << '\n'
<< "sptr3.use_count() = " << sptr3.use_count()
<< ", sptr3 @ " << sptr3 << '\n'
<< "Leaving the scope...\n";
} // Calls two destructors of: 1) Foo owned by sptr1,
// 2) Foo shared between sptr2/sptr3.
}
Possible output:
1) unique ownership Foo::Foo(), bar = 100 @ 0x23c5040 Foo::bar = 100, use_count() = 1 call sptr.reset()... Foo::~Foo(), bar = 100 @ 0x23c5040 After reset(): use_count() = 0, sptr = 0 2) unique ownership Foo::Foo(), bar = 200 @ 0x23c5040 Foo::bar = 200, use_count() = 1 call sptr.reset()... Foo::Foo(), bar = 222 @ 0x23c5050 Foo::~Foo(), bar = 200 @ 0x23c5040 After reset(): use_count() = 1, sptr = 0x23c5050 Leaving the scope... Foo::~Foo(), bar = 222 @ 0x23c5050 3) multiple ownership Foo::Foo(), bar = 300 @ 0x23c5080 Foo::bar = 300, use_count() = 3 call sptr1.reset()... Foo::Foo(), bar = 333 @ 0x23c5050 After reset(): sptr1.use_count() = 1, sptr1 @ 0x23c5050 sptr2.use_count() = 2, sptr2 @ 0x23c5080 sptr3.use_count() = 2, sptr3 @ 0x23c5080 Leaving the scope... Foo::~Foo(), bar = 300 @ 0x23c5080 Foo::~Foo(), bar = 333 @ 0x23c5050
See also
constructs new shared_ptr (public member function) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/memory/shared_ptr/reset
