std::weak_ptr

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Memory management library

voidify

(exposition only*)

Allocators

allocator
allocator_traits (C++11)
allocation_result (C++23)
scoped_allocator_adaptor (C++11)
pmr::polymorphic_allocator (C++17)

allocator_arg (C++11)
uses_allocator (C++11)
uses_allocator_construction_args (C++20)
make_obj_using_allocator (C++20)
uninitialized_construct_using_allocator (C++20)

Uninitialized memory algorithms

uninitialized_copy
uninitialized_fill
uninitialized_move (C++17)
uninitialized_copy_n (C++11)
uninitialized_fill_n
uninitialized_move_n (C++17)
construct_at (C++20)

uninitialized_default_construct (C++17)
uninitialized_value_construct (C++17)
destroy (C++17)
uninitialized_default_construct_n (C++17)
uninitialized_value_construct_n (C++17)
destroy_n (C++17)
destroy_at (C++17)

Constrained uninitialized memory algorithms

ranges::uninitialized_copy (C++20)
ranges::uninitialized_fill (C++20)
ranges::uninitialized_move (C++20)
ranges::uninitialized_copy_n (C++20)
ranges::uninitialized_fill_n (C++20)
ranges::uninitialized_move_n (C++20)
ranges::construct_at (C++20)

ranges::uninitialized_default_construct (C++20)
ranges::uninitialized_value_construct (C++20)
ranges::destroy (C++20)
ranges::uninitialized_default_construct_n (C++20)
ranges::uninitialized_value_construct_n (C++20)
ranges::destroy_n (C++20)
ranges::destroy_at (C++20)

Memory resources

pmr::memory_resource (C++17)
pmr::get_default_resource (C++17)
pmr::set_default_resource (C++17)
pmr::new_delete_resource (C++17)
pmr::pool_options (C++17)

pmr::null_memory_resource (C++17)
pmr::synchronized_pool_resource (C++17)
pmr::unsynchronized_pool_resource (C++17)
pmr::monotonic_buffer_resource (C++17)

Explicit lifetime management
start_lifetime_as (C++23)
start_lifetime_as_array (C++23)

Types for composite class design
indirect (C++26)
polymorphic (C++26)

Uninitialized storage(until C++20)

raw_storage_iterator (until C++20*)
get_temporary_buffer (until C++20*)

return_temporary_buffer (until C++20*)

Garbage collector support(until C++23)

declare_reachable (C++11)(until C++23)
declare_no_pointers (C++11)(until C++23)
pointer_safety (C++11)(until C++23)

undeclare_reachable (C++11)(until C++23)
undeclare_no_pointers (C++11)(until C++23)
get_pointer_safety (C++11)(until C++23)

Low level memory
management

operator newoperator new[]

operator deleteoperator delete[]

(C++11)

(C++11)

(C++17)

(C++20)

(C++17)

(C++11)

(C++11)

weak_ptr

(C++11)

(until C++17*)

(C++11)

(C++17)

(C++26)

(C++26)

enable_shared_from_this

(C++11)

(C++11)

(C++11)

(C++23)

(C++23)

(C++11)

(C++20)

(C++11)

(C++11)

(C++20)

is_sufficiently_aligned

(C++26)

C Library

malloc
calloc
realloc

free
aligned_alloc (C++17)

[edit]

std::weak_ptr

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
weak_ptr::owner_hash (C++26)
weak_ptr::owner_equal (C++26)
Non-member functions
swap(std::weak_ptr)
Helper classes
atomic<std::weak_ptr> (C++20)
Deduction guides(C++17)

[edit]

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 bystd::shared_ptr. It must be converted tostd::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 tostd::shared_ptr to acquire temporary ownership. If the originalstd::shared_ptr is destroyed at this time, the object's lifetime is extended until the temporarystd::shared_ptr is destroyed as well.

Another use forstd::weak_ptr is to break reference cycles formed by objects managed bystd::shared_ptr. If such cycle is orphaned (i.e., there are no outside shared pointers into the cycle), theshared_ptr reference counts cannot reach zero and the memory is leaked. To prevent this, one of the pointers in the cyclecan be made weak.

[edit]Member types

Member type Definition

element_type

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

[edit]Member functions

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

[edit]Non-member functions

std::swap(std::weak_ptr)

(C++11)

specializes thestd::swap algorithm
(function template)[edit]

[edit]Helper classes

std::atomic<std::weak_ptr>

(C++20)

atomic weak pointer
(class template specialization)[edit]

[edit]Deduction guides(since C++17)

[edit]Notes

Likestd::shared_ptr, a typical implementation ofweak_ptr stores two pointers:

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

A separate stored pointer is necessary to ensure that converting ashared_ptr toweak_ptr and then back works correctly, even for aliasedshared_ptrs. It is not possible to access the stored pointer in aweak_ptr without locking it into ashared_ptr.

Feature-test macro	Value	Std	Feature
`__cpp_lib_smart_ptr_owner_equality`	`202306L`	(C++26)	Enabling the use of`std::weak_ptr` as keys inunordered associative containers

[edit]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<<"gw.use_count() == "<< gw.use_count()<<"; ";// we have to make a copy of shared pointer before usage:if(std::shared_ptr<int> spt= gw.lock())std::cout<<"*spt == "<<*spt<<'\n';elsestd::cout<<"gw is expired\n";} int main(){{auto sp=std::make_shared<int>(42);        gw= sp;         observe();}     observe();}

Output:

gw.use_count() == 1; *spt == 42gw.use_count() == 0; gw is expired

[edit]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

[edit]See also

unique_ptr (C++11)	smart pointer with unique object ownership semantics (class template)[edit]
shared_ptr (C++11)	smart pointer with shared object ownership semantics (class template)[edit]