std::atomic::fetch_sub(3)

✨ NAME ✨

okay bestie, welcome to std::atomic::fetch_sub from the C++ Standard Library manual 💅 this is the std::atomic::fetch_sub(3) page, and the NAME is std::atomic::fetch_sub — std::atomic::fetch_sub (yes, the name is the name, we love a self-titled icon) ✨

🌸 Synopsis 🌸

Overloads (1) and (2) are member only of atomic<Integral > specializations and atomic<Floating > specializations (since C++20). Both are since C++11.

• (1) — non-volatile:

T fetch_sub( T arg, std::memory_order order = std::memory_order_seq_cst ) noexcept;

• (2) — volatile:

T fetch_sub( T arg, std::memory_order order = std::memory_order_seq_cst ) volatile noexcept;

Overloads (3) and (4) are member only of the atomic<T*> partial specialization. Both are since C++11.

• (3) — non-volatile pointer:

T* fetch_sub( std::ptrdiff_t arg, std::memory_order order = std::memory_order_seq_cst ) noexcept;

• (4) — volatile pointer:

T* fetch_sub( std::ptrdiff_t arg, std::memory_order order = std::memory_order_seq_cst ) volatile noexcept;

Atomically replaces the current value with the result of arithmetic subtraction of the value and arg. That is, it performs atomic post-decrement. The operation is read-modify-write operation. Memory is affected according to the value of order.

For overloads (1) and (2):

• 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 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.

For overloads (3) and (4):

• The result may be an undefined address, but the operation otherwise has no undefined behavior.
• If T is not a complete object type, the program is ill-formed.

⚠️ deprecated-core: it is deprecated if std::atomic<T>::is_always_lock_free is false and (since C++20) overload (2) or (4) participates in overload resolution. Not me delivering bad news 😭

🎀 Parameters 🎀

• arg — the other argument of arithmetic subtraction.
• order — memory order constraints to enforce.

💖 Return value 💖

The value immediately preceding the effects of this function in the modification order of *this. 🫶

🦋 Defect reports 🦋

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR: 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 🌈

• atomic_fetch_sub, atomic_fetch_sub_explicit (C++11) — function template; subtracts a non-atomic value from an atomic object and obtains the previous value of the atomic.
• operator++, operator++(int), operator--, operator--(int) — public member function; increments or decrements the atomic value by one.

---

💖 source: http://cppreference.com · version/date: 2024.06.10 · page: std::atomic::fetch_sub(3) — ok bye bestie, go decrement atomically and slay ✨