std::experi...nge_strong,(3)

💅 NAME 💅

std::experimental::atomic_shared_ptr::compare_exchange_strong, -
std::experimental::atomic_shared_ptr::compare_exchange_strong,

okay so bestie, this is the std::experi...nge_strong,(3) page from the C++ Standard Libary (that spelling is literally in the header, not mine 😭), and the NAME section is that same compare_exchange_strong name twice. We're already iconic.

🔥 Synopsis 🔥

bool compare_exchange_weak( std::shared_ptr<T>& expected, const
std::shared_ptr<T>& desired,
(1)
                        std::memory_order success,
std::memory_order
failure ) noexcept;
bool compare_exchange_weak( std::shared_ptr<T>& expected,
std::shared_ptr<T>&&
desired,
(2)
                        std::memory_order success,
std::memory_order
failure ) noexcept;
bool compare_exchange_weak( std::shared_ptr<T>& expected, const
std::shared_ptr<T>& desired,
(3)
                        std::memory_order order =
std::memory_order_seq_cst
) noexcept;
bool compare_exchange_weak( std::shared_ptr<T>& expected,
std::shared_ptr<T>&&
desired,
(4)
                        std::memory_order order =
std::memory_order_seq_cst
) noexcept;
bool compare_exchange_strong( std::shared_ptr<T>& expected, const
std::shared_ptr<T>& desired,
(5)
                          std::memory_order success,
std::memory_order
failure ) noexcept;
bool compare_exchange_strong( std::shared_ptr<T>& expected,
std::shared_ptr<T>&& desired,
(6)
                          std::memory_order success,
std::memory_order
failure ) noexcept;
bool compare_exchange_strong( std::shared_ptr<T>& expected, const
std::shared_ptr<T>& desired,
(7)
                          std::memory_order order =
std::memory_order_seq_cst ) noexcept;
bool compare_exchange_strong( std::shared_ptr<T>& expected,
std::shared_ptr<T>&& desired,
(8)
                          std::memory_order order =
std::memory_order_seq_cst ) noexcept;

okay so here's the actual tea: these functions atomically compare the underlying shared_ptr in *this with expected. If they're equivalent, they replace the former with desired — that's a read-modify-write operation. If they're not equivalent, they load the actual value stored in *this into expected — that's a load operation. The replacement is performed as if by the copy or move assignment operator of shared_ptr, as appropriate. 🫶

Two shared_ptrs are equivalent if and only if they store the same pointer value and share ownership. No vibes-based equivalence, bestie.

The memory models for the read-modify-write and load operations are success and failure respectively. For overloads (3,4,7,8), order is used for both read-modify-write and load operations, except that std::memory_order_acquire and std::memory_order_relaxed are used for the load operation if order == std::memory_order_acq_rel, or order == std::memory_order_release respectively.

The weak versions (1-4) may fail spuriously. Yep, they're allowed to be dramatic like that 💀.

🎀 Parameters 🎀

• expected — reference to the value expected to be found in the atomic object
• desired — the value to store in the atomic object if it is as expected
• success — the memory synchronization ordering for the read-modify-write operation if the comparison succeeds. All values are permitted
• failure — the memory synchronization ordering for the load operation if the comparison fails. Cannot be std::memory_order_release or std::memory_order_acq_rel and cannot specify stronger ordering than success
• order — the memory synchronization ordering for both operations

💖 Return value 💖

true if the underlying atomic value was changed, false otherwise. That's it. That's the whole return vibe check ✨.

🌸 Remarks 🌸

All changes to the atomic_shared_ptr object itself, and all associated use_count increments, are guaranteed to be performed atomically. Associated use_count decrements take place after the atomic operation, but are not required to be part of it. Any associated destruction or deallocation operations take place after the atomic operation and are not part of it.

If the compare-exchange operation returns true, expected is not accessed after the atomic update step. If it returns false, expected is updated with the existing value read from the atomic_shared_ptr object in the attempted atomic update. The use_count update corresponding to the write to expected is part of the atomic operation, but the write to expected itself is not required to be part of the atomic operation.

For overloads (1,3,5,7), desired is not accessed after the atomic update step.

For overloads (2,4,6,8), desired is moved from only if the compare-exchange operation returns true; the moving occurs after the atomic update step.

✨ Notes ✨

The weak forms (1-4) of the functions are allowed to fail spuriously, that is, act as if *this and expected are not equivalent even when they are. When a compare-and-exchange is in a loop, the weak version will yield better performance on some platforms. So if you're looping, weak is lowkey the move 👀.

🦋 See also 🦋

okay so the See also section is giving atomic-operations-for-std::shared_ptr mood. Here's the whole crew:

• std::atomic_is_lock_free(std::shared_ptr)
• std::atomic_load(std::shared_ptr)
• std::atomic_load_explicit(std::shared_ptr)
• std::atomic_store(std::shared_ptr)
• std::atomic_store_explicit(std::shared_ptr)
• std::atomic_exchange(std::shared_ptr)
• std::atomic_exchange_explicit(std::shared_ptr)
• std::atomic_compare_exchange_weak(std::shared_ptr)
• std::atomic_compare_exchange_strong(std::shared_ptr)
• std::atomic_compare_exchange_weak_explicit(std::shared_ptr)
• std::atomic_compare_exchange_strong_explicit(std::shared_ptr)

The original page also says specializes atomic operations for std::shared_ptr and (function template) in this area, and it tags the crew with (deprecated in C++20) and (removed in C++26). So yeah: cute atomic std::shared_ptr functions, but with big deprecated/removed energy 💀.

---

source/version + date tea, bestie: http://cppreference.com, 2024.06.10, and this iconic page is std::experi...nge_strong,(3). Go be atomic about your boundaries 💅✨