std::weak_ptr

Defined in header `<memory>`
template< class T > class weak_ptr;		(since C++11)

std::weak_ptr is a smart pointer that holds a non-owning ("weak") reference to an object that is managed by std::shared_ptr. It must be converted to std::shared_ptr in order to access the referenced object.

std::weak_ptr models temporary ownership: when an object needs to be accessed only if it exists, and it may be deleted at any time by someone else, std::weak_ptr is used to track the object, and it is converted to std::shared_ptr to assume temporary ownership. If the original std::shared_ptr is destroyed at this time, the object's lifetime is extended until the temporary std::shared_ptr is destroyed as well.

In addition, std::weak_ptr is used to break circular references of std::shared_ptr.

Member types

Member type

Definition

element_type

T	(until C++17)
std::remove_extent_t<T>	(since C++17)

Member functions

(constructor)	creates a new `weak_ptr` (public member function)
(destructor)	destroys a `weak_ptr` (public member function)
operator=	assigns the `weak_ptr` (public member function)
Modifiers
reset	releases the ownership of the managed object (public member function)
swap	swaps the managed objects (public member function)
Observers
use_count	returns the number of `shared_ptr` objects that manage the object (public member function)
expired	checks whether the referenced object was already deleted (public member function)
lock	creates a `shared_ptr` that manages the referenced object (public member function)
owner_before	provides owner-based ordering of weak pointers (public member function)

Non-member functions

std::swap(std::weak_ptr)

(C++11)

specializes the std::swap algorithm
(function template)

Helper classes

std::atomic<std::weak_ptr>

(C++20)

atomic weak pointer
(class template specialization)

Deduction guides(since C++17)

Notes

Like std::shared_ptr, a typical implementation of weak_ptr stores two pointers:

a pointer to the control block; and
the stored pointer of the shared_ptr it was constructed from.

A separate stored pointer is necessary to ensure that converting a shared_ptr to weak_ptr and then back works correctly, even for aliased shared_ptrs. It is not possible to access the stored pointer in a weak_ptr without locking it into a shared_ptr.

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 3001	C++17	`element_type` was not updated for array support	updated

Example

Demonstrates how lock is used to ensure validity of the pointer.

Run this code

#include <iostream>
#include <memory>

std::weak_ptr<int> gw;

void observe()
{
    std::cout << "use_count == " << gw.use_count() << ": ";
    if (auto spt = gw.lock()) { // Has to be copied into a shared_ptr before usage
	std::cout << *spt << "\n";
    }
    else {
        std::cout << "gw is expired\n";
    }
}

int main()
{
    {
        auto sp = std::make_shared<int>(42);
	gw = sp;

	observe();
    }

    observe();
}

Output:

use_count == 1: 42
use_count == 0: gw is expired

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
weak_ptr::weak_ptr
weak_ptr::~weak_ptr
weak_ptr::operator=
Modifiers
weak_ptr::reset
weak_ptr::swap
Observers
weak_ptr::use_count
weak_ptr::expired
weak_ptr::lock
weak_ptr::owner_before
Non-member functions
std::swap
Helper classes
std::atomic<std::weak_ptr> (C++20)
Deduction guides(C++17)