# std::atomic<std::shared_ptr>

> C++ Atlas: `cppatlas.com/w/cpp/memory/shared_ptr/atomic2` | Source: https://en.cppreference.com/w/cpp/memory/shared_ptr/atomic2 | Domain: Memory management | Standards: C++11, C++20

The partial template specialization of std::atomic for std::shared_ptr<T> allows users to manipulate shared_ptr objects atomically.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <memory>

template< class T >
struct std::atomic<std::shared_ptr<T>>; // (since C++20)
```

The partial template specialization of `std::atomic` for `std::shared_ptr<T>` allows users to manipulate `shared_ptr` objects atomically.

If multiple threads of execution access the same `std::shared_ptr` object without synchronization and any of those accesses uses a non-const member function of `shared_ptr` then a data race will occur unless all such access is performed through an instance of `std::atomic<std::shared_ptr>` (or, deprecated as of C++20, through the standalone functions for atomic access to `std::shared_ptr`).

Associated `use_count` increments are guaranteed to be part of the atomic operation. Associated `use_count` decrements are sequenced after the atomic operation, but are not required to be part of it, except for the `use_count` change when overriding `expected` in a failed CAS. Any associated deletion and deallocation are sequenced after the atomic update step and are not part of the atomic operation.

Note that the control block of a `shared_ptr` is thread-safe: different non-atomic `std::shared_ptr` objects can be accessed using mutable operations, such as `operator=` or `reset`, simultaneously by multiple threads, even when these instances are copies, and share the same control block internally.

The type T may be an incomplete type.

#### Member types

**Member type — Definition**

- `value_type`: `std::shared_ptr<T>`

#### Member functions

All non-specialized `std::atomic` functions are also provided by this specialization, and no additional member functions.

### atomic\<shared_ptr\<T>>::atomic

```cpp
constexpr atomic() noexcept = default; // (1)
constexpr atomic( std::nullptr_t ) noexcept : atomic() {} // (2)
atomic( std::shared_ptr<T> desired ) noexcept; // (3)
atomic( const atomic& ) = delete; // (4)
```

1,2) Initializes the underlying `shared_ptr<T>` to the null value.

3) Initializes the underlying `shared_ptr<T>` to a copy of `desired`. As with any `std::atomic` type, initialization is not an atomic operation.

4) Atomic types are not copy/move constructible.

### atomic\<shared_ptr\<T>>::operator=

```cpp
void operator=( const atomic& ) = delete; // (1)
void operator=( std::shared_ptr<T> desired ) noexcept; // (2)
void operator=( std::nullptr_t ) noexcept; // (3)
```

1) Atomic types are not copy/move assignable.

2) Value assignment, equivalent to `store(desired)`.

3) Resets the atomic shared pointer to null pointer value. Equivalent to `store(nullptr);`.

### atomic\<shared_ptr\<T>>::is_lock_free

```cpp
bool is_lock_free() const noexcept;
```

Returns `true` if the atomic operations on all objects of this type are lock-free, `false` otherwise.

### atomic\<shared_ptr\<T>>::store

```cpp
void store( std::shared_ptr<T> desired,
            std::memory_order order = std::memory_order_seq_cst ) noexcept;
```

Atomically replaces the value of `*this` with the value of `desired` as if by `p.swap(desired)` where `p` is the underlying `std::shared_ptr<T>`. Memory is ordered according to `order`. The behavior is undefined if `order` is `std::memory_order_consume`, `std::memory_order_acquire`, or `std::memory_order_acq_rel`.

### atomic\<shared_ptr\<T>>::load

```cpp
std::shared_ptr<T> load( std::memory_order order = std::memory_order_seq_cst ) const noexcept;
```

Atomically returns a copy of the underlying shared pointer. Memory is ordered according to `order`. The behavior is undefined if `order` is `std::memory_order_release` or `std::memory_order_acq_rel`.

### atomic\<shared_ptr\<T>>::operator std::shared_ptr\<T>

```cpp
operator std::shared_ptr<T>() const noexcept;
```

Equivalent to `return load();`.

### atomic\<shared_ptr\<T>>::exchange

```cpp
std::shared_ptr<T> exchange( std::shared_ptr<T> desired,
                             std::memory_order order = std::memory_order_seq_cst ) noexcept;
```

Atomically replaces the underlying `std::shared_ptr<T>` with `desired` as if by `p.swap(desired)` where `p` is the underlying `std::shared_ptr<T>` and returns a copy of the value that `p` had immediately before the swap. Memory is ordered according to `order`. This is an atomic read-modify-write operation.

### atomic\<shared_ptr\<T>>::compare_exchange_weak, compare_exchange_strong

```cpp
bool compare_exchange_strong( std::shared_ptr<T>& expected, std::shared_ptr<T> desired,
                              std::memory_order success, std::memory_order failure ) noexcept; // (1)

bool compare_exchange_weak( std::shared_ptr<T>& expected, std::shared_ptr<T> desired,
                            std::memory_order success, std::memory_order failure ) noexcept; // (2)

bool compare_exchange_strong( std::shared_ptr<T>& expected, std::shared_ptr<T> desired,
                              std::memory_order order = std::memory_order_seq_cst ) noexcept; // (3)

bool compare_exchange_weak( std::shared_ptr<T>& expected, std::shared_ptr<T> desired,
                            std::memory_order order = std::memory_order_seq_cst ) noexcept; // (4)
```

1) If the underlying `std::shared_ptr<T>` stores the same `T*` as `expected` and shares ownership with it, or if both underlying and `expected` are empty, assigns from `desired` to the underlying `std::shared_ptr<T>`, returns `true`, and orders memory according to `success`, otherwise assigns from the underlying `std::shared_ptr<T>` to `expected`, returns `false`, and orders memory according to `failure`. The behavior is undefined if `failure` is `std::memory_order_release` or `std::memory_order_acq_rel`. On success, the operation is an atomic read-modify-write operation on `*this` and `expected` is not accessed after the atomic update. On failure, the operation is an atomic load operation on `*this` and `expected` is updated with the existing value read from the atomic object. This update to `expected`'s `use_count` is part of this atomic operation, although the write itself (and any subsequent deallocation/destruction) is not required to be.

2) Same as (1), but may also fail spuriously.

3) Equivalent to: `return compare_exchange_strong(expected, desired, order, fail_order);`, where `fail_order` is the same as `order` except that `std::memory_order_acq_rel` is replaced by `std::memory_order_acquire` and `std::memory_order_release` is replaced by `std::memory_order_relaxed`.

4) Equivalent to: `return compare_exchange_weak(expected, desired, order, fail_order);`, where `fail_order` is the same as `order` except that `std::memory_order_acq_rel` is replaced by `std::memory_order_acquire` and `std::memory_order_release` is replaced by `std::memory_order_relaxed`.

### atomic\<shared_ptr\<T>>::wait

```cpp
void wait( std::shared_ptr<T> old,
           std::memory_order order = std::memory_order_seq_cst ) const noexcept;
```

Performs an atomic waiting operation.

Compares `load(order)` with `old` and if they are equivalent then blocks until `*this` is notified by `notify_one()` or `notify_all()`. This is repeated until `load(order)` changes. This function is guaranteed to return only if value has changed, even if underlying implementation unblocks spuriously.

Memory is ordered according to `order`. The behavior is undefined if `order` is `std::memory_order_release` or `std::memory_order_acq_rel`.

Notes: two `shared_ptr`s are equivalent if they store the same pointer and either share ownership or are both empty.

### atomic\<shared_ptr\<T>>::notify_one

```cpp
void notify_one() noexcept;
```

Performs an atomic notifying operation.

If there is a thread blocked in atomic waiting operations (i.e. `wait()`) on `*this`, then unblocks at least one such thread; otherwise does nothing.

### atomic\<shared_ptr\<T>>::notify_all

```cpp
void notify_all() noexcept;
```

Performs an atomic notifying operation.

Unblocks all threads blocked in atomic waiting operations (i.e. `wait()`) on `*this`, if there are any; otherwise does nothing.

#### Member constants

The only standard `std::atomic` member constant `is_always_lock_free` is also provided by this specialization.

### atomic\<shared_ptr\<T>>::is_always_lock_free

```cpp
static constexpr bool is_always_lock_free = /*implementation-defined*/;
```

#### Notes

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_atomic_shared_ptr` | `201711L` | (C++20) | `std::atomic<std::shared_ptr>` |

#### Example

> Note: This section is incomplete Reason: no example

#### 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 3661 | C++20 | `atomic<shared_ptr<T>>` was not constant-initializable from `nullptr` | made constant-initializable |
| LWG 3893 | C++20 | LWG3661 made `atomic<shared_ptr<T>>` not assignable from `nullptr_t` | assignability restored |

#### See also

- [`atomic`](https://en.cppreference.com/w/cpp/atomic/atomic) (C++11): atomic class template and specializations for bool, integral, floating-point, (since C++20) and pointer types (class template)

---
Attribution: content from https://en.cppreference.com/w/cpp/memory/shared_ptr/atomic2 (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.