std::atomic::operator+=,-=(3)

💖 std::atomic::operator+=,-= 💖

Bestie, this page is from the C++ Standard Libary manual (yes, that's the manual name, we keep it 💅), and it's all about the atomic += and -= operators. Read-modify-write main character energy, no cap. 🦋

---

🌸 NAME 🌸

std::atomic::operator+=,-= — std::atomic::operator+=,-=

---

✨ SYNOPSIS ✨

Okay so first: these are member only of atomic<Integral > specializations and atomic<Floating > specializations (since C++20). 🎀

T operator+=( T arg ) noexcept;                        (1) (since C++11)
T operator+=( T arg ) volatile noexcept;               (2) (since C++11)
T operator-=( T arg ) noexcept;                        (3) (since C++11)
T operator-=( T arg ) volatile noexcept;               (4) (since C++11)

And these are member only of the atomic<T*> partial specialization:

T* operator+=( std::ptrdiff_t arg ) noexcept;          (5) (since C++11)
T* operator+=( std::ptrdiff_t arg ) volatile noexcept; (6) (since C++11)
T* operator-=( std::ptrdiff_t arg ) noexcept;          (7) (since C++11)
T* operator-=( std::ptrdiff_t arg ) volatile noexcept; (8) (since C++11)

So what's the vibe? It atomically replaces the current value with the result of computation involving the previous value and arg. The operation is a read-modify-write operation. 💫

• operator+= performs atomic addition. Equivalent to return fetch_add(arg) + arg;.
• operator-= performs atomic subtraction. Equivalent to return fetch_sub(arg) - arg;.

Here's the breakdown, bestie:

• 1-4) For signed integral types, arithmetic is defined to use two’s complement representation. There are no undefined results. 🫶

For floating-point types, the floating-point environment in effect may be different from the calling thread's floating-point environment. The operation need not be conform to the corresponding std::numeric_limits (since C++20) traits but is encouraged to do so. If the result is not a representable value for its type, the result is unspecified but the operation otherwise has no undefined behavior.

• 5-8) The result may be an undefined address, but the operations otherwise have no undefined behavior. If T is not a complete object type, the program is ill-formed.

🚨 Warning, bestie: it is deprecated if std::atomic<T>::is_always_lock_free is false and (since C++20) any volatile overload participates in overload resolution. Like, noted. 💀

---

🎀 PARAMETERS 🎀

• arg — the argument for the arithmetic operation.

---

💫 RETURN VALUE 💫

The resulting value — that is, the result of applying the corresponding binary operator to the value immediately preceding the effects of the corresponding member function in the modification order of *this. ✨

---

🌈 NOTES 🌈

Unlike most compound assignment operators, the compound assignment operators for atomic types do not return a reference to their left-hand arguments. They return a copy of the stored value instead. Iconic behavior, honestly. 👑

💅 DEFECT REPORTS 💅

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. History really said "let's fix it later" 😭

• P0558R1 — applied to C++11.
  • Behavior as published: arithmetic permitted on pointers to (possibly cv-qualified) void or function.
  • Correct behavior: made ill-formed.

---

🔥 SEE ALSO 🔥

• fetch_add — atomically adds the argument to the value stored in the atomic object and obtains the value held previously (public member function).
• fetch_sub — atomically subtracts the argument from the value stored in the atomic object and obtains the value held previously (public member function).
• operator++, operator++(int), operator--, operator--(int) — increments or decrements the atomic value by one (public member function).
• operator&=, operator|=, operator^= — performs bitwise AND, OR, XOR with the atomic value (public member function).

---

Source/version: http://cppreference.com • date: 2024.06.10 • page: std::atomic::operator+=,-=(3). Go atomically slay, bestie 💅💖