StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
atomic.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This is the base for StormByte Suite libraries.
5 *
6 * StormByte original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte source in this repository.
20 * They do not cover other StormByte modules or any third-party material
21 * shipped with this repository (including everything under thirdparty/),
22 * which remains under its own license.
23 *
24 * Neither license grants any patent rights. Any patent licenses required
25 * to use this software or third-party components must be obtained separately
26 * from the patent holders.
27 *
28 * StormByte is distributed in the hope that it will be useful,
29 * but WITHOUT ANY WARRANTY; without even the implied warranty of
30 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 * GNU Lesser General Public License for more details.
32 *
33 * You should have received a copy of the GNU Lesser General Public License
34 * version 3 along with StormByte. If not, see
35 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
36 *
37 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
38 */
39
40#pragma once
41
45
46#include <cstddef>
47#include <cstdint>
48#include <type_traits>
49
54namespace StormByte {
59 namespace Safe {
64 namespace Detail {
71 STORMBYTE_PUBLIC void* WordCreate(std::size_t bytes);
72
77 STORMBYTE_PUBLIC void WordDestroy(void* word) noexcept;
78
86 STORMBYTE_PUBLIC void WordLoad(void* word, std::size_t bytes, void* out, MemoryOrder order) noexcept;
87
95 STORMBYTE_PUBLIC void WordStore(void* word, std::size_t bytes, const void* value, MemoryOrder order) noexcept;
96
105 STORMBYTE_PUBLIC void WordExchange(void* word, std::size_t bytes, const void* desired, void* previous, MemoryOrder order) noexcept;
106
118 STORMBYTE_PUBLIC bool WordCompareExchange(void* word, std::size_t bytes, void* expected, const void* desired, MemoryOrder success, MemoryOrder failure, bool weak) noexcept;
119
129 STORMBYTE_PUBLIC void WordFetchOp(void* word, std::size_t bytes, std::int64_t delta, void* previous, MemoryOrder order, int op) noexcept;
130
138 STORMBYTE_PUBLIC void WordWait(void* word, std::size_t bytes, const void* old, MemoryOrder order) noexcept;
139
144 STORMBYTE_PUBLIC void WordNotifyOne(void* word) noexcept;
145
150 STORMBYTE_PUBLIC void WordNotifyAll(void* word) noexcept;
151
157 STORMBYTE_PUBLIC bool WordLockFree(void* word) noexcept;
158 }
159
167 template <class T>
168 class Atomic {
169 static_assert(std::is_trivially_copyable_v<T>);
170 static_assert(sizeof(T) == 1 || sizeof(T) == 2 || sizeof(T) == 4 || sizeof(T) == 8);
171
172 public:
178 : m_word{Detail::WordCreate(sizeof(T))} {}
179
185 explicit Atomic(T desired)
186 : Atomic() {
187 store(desired, MemoryOrder::Relaxed);
188 }
189
190 Atomic(const Atomic&) = delete;
191
192 Atomic(Atomic&&) = delete;
193
197 ~Atomic() noexcept {
198 Detail::WordDestroy(m_word);
199 }
200
201 Atomic& operator=(const Atomic&) = delete;
202
203 Atomic& operator=(Atomic&&) = delete;
204
210 T operator=(T desired) noexcept {
211 store(desired);
212 return desired;
213 }
214
219 bool is_lock_free() const noexcept {
220 return Detail::WordLockFree(m_word);
221 }
222
228 T load(MemoryOrder order = MemoryOrder::SeqCst) const noexcept {
229 T out{};
230 Detail::WordLoad(m_word, sizeof(T), &out, order);
231 return out;
232 }
233
239 void store(T desired, MemoryOrder order = MemoryOrder::SeqCst) noexcept {
240 Detail::WordStore(m_word, sizeof(T), &desired, order);
241 }
242
249 T exchange(T desired, MemoryOrder order = MemoryOrder::SeqCst) noexcept {
250 T previous{};
251 Detail::WordExchange(m_word, sizeof(T), &desired, &previous, order);
252 return previous;
253 }
254
263 bool compare_exchange_weak(T& expected, T desired, MemoryOrder success, MemoryOrder failure) noexcept {
264 return Detail::WordCompareExchange(m_word, sizeof(T), &expected, &desired, success, failure, true);
265 }
266
274 bool compare_exchange_weak(T& expected, T desired, MemoryOrder order = MemoryOrder::SeqCst) noexcept {
275 return compare_exchange_weak(expected, desired, order, FailureOrder(order));
276 }
277
286 bool compare_exchange_strong(T& expected, T desired, MemoryOrder success, MemoryOrder failure) noexcept {
287 return Detail::WordCompareExchange(m_word, sizeof(T), &expected, &desired, success, failure, false);
288 }
289
297 bool compare_exchange_strong(T& expected, T desired, MemoryOrder order = MemoryOrder::SeqCst) noexcept {
298 return compare_exchange_strong(expected, desired, order, FailureOrder(order));
299 }
300
306 void wait(T old, MemoryOrder order = MemoryOrder::SeqCst) const noexcept {
307 Detail::WordWait(m_word, sizeof(T), &old, order);
308 }
309
313 void notify_one() noexcept {
314 Detail::WordNotifyOne(m_word);
315 }
316
320 void notify_all() noexcept {
321 Detail::WordNotifyAll(m_word);
322 }
323
333 template <class Delta>
334 T fetch_add(Delta delta, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires ((Type::Integral<T> && std::is_same_v<Delta, T>) || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0 && std::is_integral_v<Delta> && std::is_convertible_v<Delta, std::ptrdiff_t>)) {
335 if constexpr (Type::Pointer<T>)
336 return Fetch(static_cast<std::int64_t>(static_cast<std::ptrdiff_t>(delta)) * static_cast<std::int64_t>(sizeof(std::remove_pointer_t<T>)), order, 0);
337 else
338 return Fetch(static_cast<std::int64_t>(delta), order, 0);
339 }
340
348 template <class Delta>
349 T fetch_sub(Delta delta, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires ((Type::Integral<T> && std::is_same_v<Delta, T>) || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0 && std::is_integral_v<Delta> && std::is_convertible_v<Delta, std::ptrdiff_t>)) {
350 if constexpr (Type::Pointer<T>)
351 return Fetch(static_cast<std::int64_t>(static_cast<std::ptrdiff_t>(delta)) * static_cast<std::int64_t>(sizeof(std::remove_pointer_t<T>)), order, 1);
352 else
353 return Fetch(static_cast<std::int64_t>(delta), order, 1);
354 }
355
362 T fetch_and(T bits, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires Type::Integral<T> {
363 return Fetch(static_cast<std::int64_t>(bits), order, 2);
364 }
365
372 T fetch_or(T bits, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires Type::Integral<T> {
373 return Fetch(static_cast<std::int64_t>(bits), order, 3);
374 }
375
382 T fetch_xor(T bits, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires Type::Integral<T> {
383 return Fetch(static_cast<std::int64_t>(bits), order, 4);
384 }
385
394 T fetch_max(T value, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires (Type::Integral<T> || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0)) {
395 return Extremum(value, order);
396 }
397
404 T fetch_min(T value, MemoryOrder order = MemoryOrder::SeqCst) noexcept requires (Type::Integral<T> || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0)) {
405 return Extremum(value, order, false);
406 }
407
412 T operator++() noexcept requires Type::Integral<T> {
413 return static_cast<T>(fetch_add(T{1}) + T{1});
414 }
415
420 T operator++(int) noexcept requires Type::Integral<T> {
421 return fetch_add(T{1});
422 }
423
428 T operator--() noexcept requires Type::Integral<T> {
429 return static_cast<T>(fetch_sub(T{1}) - T{1});
430 }
431
436 T operator--(int) noexcept requires Type::Integral<T> {
437 return fetch_sub(T{1});
438 }
439
445 T operator+=(T delta) noexcept requires Type::Integral<T> {
446 return static_cast<T>(fetch_add(delta) + delta);
447 }
448
454 T operator-=(T delta) noexcept requires Type::Integral<T> {
455 return static_cast<T>(fetch_sub(delta) - delta);
456 }
457
463 T operator&=(T bits) noexcept requires Type::Integral<T> {
464 return static_cast<T>(fetch_and(bits) & bits);
465 }
466
472 T operator|=(T bits) noexcept requires Type::Integral<T> {
473 return static_cast<T>(fetch_or(bits) | bits);
474 }
475
481 T operator^=(T bits) noexcept requires Type::Integral<T> {
482 return static_cast<T>(fetch_xor(bits) ^ bits);
483 }
484
489 operator T() const noexcept {
490 return load();
491 }
492
493 private:
499 static MemoryOrder FailureOrder(MemoryOrder success) noexcept {
500 if (success == MemoryOrder::AcqRel || success == MemoryOrder::Release)
502 if (success == MemoryOrder::SeqCst)
503 return MemoryOrder::SeqCst;
505 }
506
514 T Fetch(std::int64_t delta, MemoryOrder order, int op) noexcept {
515 T previous{};
516 Detail::WordFetchOp(m_word, sizeof(T), delta, &previous, order, op);
517 return previous;
518 }
519
527 T Extremum(T value, MemoryOrder order, bool maximum = true) noexcept {
528 T current = load(MemoryOrder::Relaxed);
529 for (;;) {
530 const bool replace = maximum ? (current < value) : (value < current);
531 if (!replace)
532 return current;
533 if (compare_exchange_weak(current, value, order))
534 return current;
535 }
536 }
537
538 void* m_word;
539 };
540
542 extern template class STORMBYTE_PUBLIC Atomic<bool>;
543 extern template class STORMBYTE_PUBLIC Atomic<char>;
544 extern template class STORMBYTE_PUBLIC Atomic<signed char>;
545 extern template class STORMBYTE_PUBLIC Atomic<unsigned char>;
546 extern template class STORMBYTE_PUBLIC Atomic<char8_t>;
547 extern template class STORMBYTE_PUBLIC Atomic<wchar_t>;
548 extern template class STORMBYTE_PUBLIC Atomic<char16_t>;
549 extern template class STORMBYTE_PUBLIC Atomic<char32_t>;
550 extern template class STORMBYTE_PUBLIC Atomic<short>;
551 extern template class STORMBYTE_PUBLIC Atomic<unsigned short>;
552 extern template class STORMBYTE_PUBLIC Atomic<int>;
553 extern template class STORMBYTE_PUBLIC Atomic<unsigned int>;
554 extern template class STORMBYTE_PUBLIC Atomic<long>;
555 extern template class STORMBYTE_PUBLIC Atomic<unsigned long>;
556 extern template class STORMBYTE_PUBLIC Atomic<long long>;
557 extern template class STORMBYTE_PUBLIC Atomic<unsigned long long>;
559 }
560}
Atomic word of one, two, four or eight bytes.
Definition atomic.hxx:168
T operator--() noexcept
Pre-decrement.
Definition atomic.hxx:428
bool compare_exchange_weak(T &expected, T desired, MemoryOrder success, MemoryOrder failure) noexcept
Weak compare-exchange.
Definition atomic.hxx:263
~Atomic() noexcept
Destroys the word on Base's heap.
Definition atomic.hxx:197
T fetch_and(T bits, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Bitwise and, returning the previous value.
Definition atomic.hxx:362
void notify_all() noexcept
Wake every waiter.
Definition atomic.hxx:320
T operator++() noexcept
Pre-increment.
Definition atomic.hxx:412
bool compare_exchange_weak(T &expected, T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Weak compare-exchange with one order.
Definition atomic.hxx:274
T exchange(T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Replace the value.
Definition atomic.hxx:249
T operator^=(T bits) noexcept
Xor and return the new value.
Definition atomic.hxx:481
T load(MemoryOrder order=MemoryOrder::SeqCst) const noexcept
Load the value.
Definition atomic.hxx:228
T fetch_or(T bits, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Bitwise or, returning the previous value.
Definition atomic.hxx:372
T fetch_xor(T bits, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Bitwise xor, returning the previous value.
Definition atomic.hxx:382
T fetch_min(T value, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Replace the value with the lesser of it and value.
Definition atomic.hxx:404
T operator+=(T delta) noexcept
Add and return the new value.
Definition atomic.hxx:445
T fetch_max(T value, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Replace the value with the greater of it and value.
Definition atomic.hxx:394
Atomic(T desired)
Value-initialized word.
Definition atomic.hxx:185
void wait(T old, MemoryOrder order=MemoryOrder::SeqCst) const noexcept
Wait while the value is still old.
Definition atomic.hxx:306
void notify_one() noexcept
Wake one waiter.
Definition atomic.hxx:313
Atomic(const Atomic &)=delete
void store(T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Store a value.
Definition atomic.hxx:239
T operator-=(T delta) noexcept
Subtract and return the new value.
Definition atomic.hxx:454
T operator&=(T bits) noexcept
And and return the new value.
Definition atomic.hxx:463
bool compare_exchange_strong(T &expected, T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Strong compare-exchange with one order.
Definition atomic.hxx:297
T fetch_sub(Delta delta, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Subtract and return the previous value.
Definition atomic.hxx:349
T operator++(int) noexcept
Post-increment.
Definition atomic.hxx:420
T fetch_add(Delta delta, MemoryOrder order=MemoryOrder::SeqCst) noexcept
Add and return the previous value.
Definition atomic.hxx:334
Atomic(Atomic &&)=delete
bool is_lock_free() const noexcept
Whether Base's word is lock-free.
Definition atomic.hxx:219
Atomic & operator=(Atomic &&)=delete
Atomic()
Zero-initialized value.
Definition atomic.hxx:177
T operator--(int) noexcept
Post-decrement.
Definition atomic.hxx:436
bool compare_exchange_strong(T &expected, T desired, MemoryOrder success, MemoryOrder failure) noexcept
Strong compare-exchange.
Definition atomic.hxx:286
T operator|=(T bits) noexcept
Or and return the new value.
Definition atomic.hxx:472
Atomic & operator=(const Atomic &)=delete
T operator=(T desired) noexcept
Store a value.
Definition atomic.hxx:210
Integral type (bool, char, int, long, …), including cv.
Definition categories.hxx:185
Raw (possibly cv-qualified) pointer type.
Definition categories.hxx:131
Private helpers.
void WordLoad(void *word, std::size_t bytes, void *out, MemoryOrder order) noexcept
Load the low bytes of a word.
bool WordCompareExchange(void *word, std::size_t bytes, void *expected, const void *desired, MemoryOrder success, MemoryOrder failure, bool weak) noexcept
Compare-exchange the low bytes.
void * WordCreate(std::size_t bytes)
Allocate a zeroed word on Base's heap.
void WordStore(void *word, std::size_t bytes, const void *value, MemoryOrder order) noexcept
Store bytes into the low part of a word.
void WordExchange(void *word, std::size_t bytes, const void *desired, void *previous, MemoryOrder order) noexcept
Replace the value and return the previous one.
void WordWait(void *word, std::size_t bytes, const void *old, MemoryOrder order) noexcept
Wait while the low bytes still equal old.
void WordNotifyAll(void *word) noexcept
Wake every waiter on word.
bool WordLockFree(void *word) noexcept
Whether Base's word is lock-free.
void WordFetchOp(void *word, std::size_t bytes, std::int64_t delta, void *previous, MemoryOrder order, int op) noexcept
Integer operation on the low bytes.
void WordNotifyOne(void *word) noexcept
Wake one waiter on word.
void WordDestroy(void *word) noexcept
Destroy a word from WordCreate.
Owned values that cross a DLL without the caller's CRT.
MemoryOrder
Ordering for a Atomic operation.
Definition memory_order.hxx:60
@ AcqRel
Acquire plus release.
Definition memory_order.hxx:65
@ Relaxed
No inter-thread ordering.
Definition memory_order.hxx:61
@ Acquire
Acquire.
Definition memory_order.hxx:63
@ Release
Release.
Definition memory_order.hxx:64
@ SeqCst
Sequentially consistent.
Definition memory_order.hxx:66
Root namespace of the StormByte suite.
Octet count. Defined in byte_size.hxx. Forwarded so Type::Numeral can name it.
#define STORMBYTE_PUBLIC
Definition visibility.h:52