1// Copyright (C) 2016 The Qt Company Ltd.
2// Copyright (C) 2016 Intel Corporation.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
4
5#include "qatomic.h"
6
7/*!
8 \class QAtomicInt
9 \inmodule QtCore
10 \brief The QAtomicInt class provides platform-independent atomic operations on int.
11 \since 4.4
12
13 This class is a equivalent to \c{QAtomicInteger<int>}. All other
14 functionality is equivalent. Please see that class for more information.
15
16 \sa QAtomicInteger, QAtomicPointer
17*/
18
19/*!
20 \class QAtomicInteger
21 \inmodule QtCore
22 \brief The QAtomicInteger class provides platform-independent atomic operations on integers.
23 \ingroup thread
24 \since 5.3
25
26 For atomic operations on pointers, see the QAtomicPointer class.
27
28 An \e atomic operation is a complex operation that completes without interruption.
29 The QAtomicInteger class provides atomic reference counting, test-and-set, fetch-and-store,
30 and fetch-and-add for integers.
31
32 The template parameter \c T must be a C++ integer type:
33 \list
34 \li 8-bit: bool, char, signed char, unsigned char, qint8, quint8, char8_t (C++20)
35 \li 16-bit: short, unsigned short, qint16, quint16, char16_t
36 \li 32-bit: int, unsigned int, qint32, quint32, char32_t
37 \li 64-bit: long long, unsigned long long, qint64, quint64
38 \li platform-specific size: long, unsigned long
39 \li pointer size: qintptr, quintptr, qptrdiff
40 \endlist
41
42 Of the list above, only the 8-bit, 16-bit, 32-bit- and pointer-sized
43 instantiations are guaranteed to work on all platforms. Support for other
44 sizes depends on the compiler and processor architecture the code is being
45 compiled for. To test whether the 64-bit types are supported on 32-bit
46 platforms, check the macro \c Q_ATOMIC_INT64_IS_SUPPORTED.
47
48 \section1 The Atomic API
49
50 \section2 Reference counting
51
52 The ref() and deref() functions provide an efficient reference
53 counting API. The return value of these functions are used to
54 indicate when the last reference has been released. These
55 functions allow you to implement your own implicitly shared
56 classes.
57
58 \snippet code/src_corelib_thread_qatomic.cpp 0
59
60 \section2 Memory ordering
61
62 QAtomicInteger provides several implementations of the atomic
63 test-and-set, fetch-and-store, and fetch-and-add functions. Each
64 implementation defines a memory ordering semantic that describes
65 how memory accesses surrounding the atomic instruction are
66 executed by the processor. Since many modern architectures allow
67 out-of-order execution and memory ordering, using the correct
68 semantic is necessary to ensure that your application functions
69 properly on all processors.
70
71 \list
72
73 \li Relaxed - memory ordering is unspecified, leaving the compiler
74 and processor to freely reorder memory accesses.
75
76 \li Acquire - memory access following the atomic operation (in
77 program order) may not be re-ordered before the atomic operation.
78
79 \li Release - memory access before the atomic operation (in program
80 order) may not be re-ordered after the atomic operation.
81
82 \li Ordered - the same Acquire and Release semantics combined.
83
84 \endlist
85
86 \section2 Test-and-set
87
88 If the current value of the QAtomicInteger is an expected value, the
89 test-and-set functions assign a new value to the QAtomicInteger and
90 return true. If values are \a not the same, these functions do
91 nothing and return false. This operation equates to the following
92 code:
93
94 \snippet code/src_corelib_thread_qatomic.cpp 1
95
96 There are 4 test-and-set functions: testAndSetRelaxed(),
97 testAndSetAcquire(), testAndSetRelease(), and
98 testAndSetOrdered(). See above for an explanation of the different
99 memory ordering semantics.
100
101 \section2 Fetch-and-store
102
103 The atomic fetch-and-store functions read the current value of the
104 QAtomicInteger and then assign a new value, returning the original
105 value. This operation equates to the following code:
106
107 \snippet code/src_corelib_thread_qatomic.cpp 2
108
109 There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),
110 fetchAndStoreAcquire(), fetchAndStoreRelease(), and
111 fetchAndStoreOrdered(). See above for an explanation of the
112 different memory ordering semantics.
113
114 \section2 Fetch-and-add
115
116 The atomic fetch-and-add functions read the current value of the
117 QAtomicInteger and then add the given value to the current value,
118 returning the original value. This operation equates to the
119 following code:
120
121 \snippet code/src_corelib_thread_qatomic.cpp 3
122
123 There are 4 fetch-and-add functions: fetchAndAddRelaxed(),
124 fetchAndAddAcquire(), fetchAndAddRelease(), and
125 fetchAndAddOrdered(). See above for an explanation of the
126 different memory ordering semantics.
127
128 \section1 Feature Tests for the Atomic API
129
130 Providing a platform-independent atomic API that works on all
131 processors is challenging. The API provided by QAtomicInteger is
132 guaranteed to work atomically on all processors. However, since
133 not all processors implement support for every operation provided
134 by QAtomicInteger, it is necessary to expose information about the
135 processor.
136
137 You can check at compile time which features are supported on your
138 hardware using various macros. These will tell you if your
139 hardware always, sometimes, or does not support a particular
140 operation. The macros have the form
141 Q_ATOMIC_INT\e{nn}_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{nn} is the
142 size of the integer (in bits), \e{OPERATION}
143 is one of REFERENCE_COUNTING, TEST_AND_SET,
144 FETCH_AND_STORE, or FETCH_AND_ADD, and \e{HOW} is one of
145 ALWAYS, SOMETIMES, or NOT. There will always be exactly one
146 defined macro per operation. For example, if
147 Q_ATOMIC_INT32_REFERENCE_COUNTING_IS_ALWAYS_NATIVE is defined,
148 neither Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE nor
149 Q_ATOMIC_INT32_REFERENCE_COUNTING_IS_NOT_NATIVE will be defined.
150
151 An operation that completes in constant time is said to be
152 wait-free. Such operations are not implemented using locks or
153 loops of any kind. For atomic operations that are always
154 supported, and that are wait-free, Qt defines the
155 Q_ATOMIC_INT\e{nn}_\e{OPERATION}_IS_WAIT_FREE in addition to the
156 Q_ATOMIC_INT\e{nn}_\e{OPERATION}_IS_ALWAYS_NATIVE.
157
158 In cases where an atomic operation is only supported in newer
159 generations of the processor, QAtomicInteger also provides a way to
160 check at runtime what your hardware supports with the
161 isReferenceCountingNative(), isTestAndSetNative(),
162 isFetchAndStoreNative(), and isFetchAndAddNative()
163 functions. Wait-free implementations can be detected using the
164 isReferenceCountingWaitFree(), isTestAndSetWaitFree(),
165 isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.
166
167 Below is a complete list of all feature macros for QAtomicInteger:
168
169 \list
170
171 \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
172 \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
173 \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_NOT_NATIVE
174 \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_WAIT_FREE
175
176 \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_ALWAYS_NATIVE
177 \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_SOMETIMES_NATIVE
178 \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_NOT_NATIVE
179 \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_WAIT_FREE
180
181 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_ALWAYS_NATIVE
182 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
183 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_NOT_NATIVE
184 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_WAIT_FREE
185
186 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_ALWAYS_NATIVE
187 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
188 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_NOT_NATIVE
189 \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_WAIT_FREE
190
191 \endlist
192
193 For compatibility with previous versions of Qt, macros with an empty \e{nn}
194 are equivalent to the 32-bit macros. For example,
195 Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE is the same as
196 Q_ATOMIC_INT32_REFERENCE_COUNTING_IS_WAIT_FREE.
197
198 \sa QAtomicPointer
199*/
200
201/*!
202 \fn QAtomicInt::QAtomicInt(int value)
203
204 Constructs a QAtomicInt with the given \a value.
205*/
206
207/*!
208 \fn template <typename T> QAtomicInteger<T>::QAtomicInteger(T value)
209
210 Constructs a QAtomicInteger with the given \a value.
211*/
212
213/*!
214 \fn template <typename T> QAtomicInteger<T>::QAtomicInteger(const QAtomicInteger &other)
215
216 Constructs a copy of \a other.
217*/
218
219/*!
220 \fn template <typename T> QAtomicInteger &QAtomicInteger<T>::operator=(const QAtomicInteger &other)
221
222 Assigns \a other to this QAtomicInteger and returns a reference to
223 this QAtomicInteger.
224*/
225
226
227/*!
228 \fn template <typename T> T QAtomicInteger<T>::loadRelaxed() const
229 \since 5.14
230
231 Atomically loads the value of this QAtomicInteger using relaxed memory
232 ordering. The value is not modified in any way, but note that there's no
233 guarantee that it remains so.
234
235 \sa storeRelaxed(), loadAcquire()
236*/
237
238/*!
239 \fn template <typename T> T QAtomicInteger<T>::loadAcquire() const
240
241 Atomically loads the value of this QAtomicInteger using the "Acquire" memory
242 ordering. The value is not modified in any way, but note that there's no
243 guarantee that it remains so.
244
245 \sa storeRelaxed(), loadRelaxed()
246*/
247
248/*!
249 \fn template <typename T> void QAtomicInteger<T>::storeRelaxed(T newValue)
250 \since 5.14
251
252 Atomically stores the \a newValue value into this atomic type, using
253 relaxed memory ordering.
254
255 \sa storeRelease(), loadRelaxed()
256*/
257
258/*!
259 \fn template <typename T> void QAtomicInteger<T>::storeRelease(T newValue)
260
261 Atomically stores the \a newValue value into this atomic type, using
262 the "Release" memory ordering.
263
264 \sa storeRelaxed(), loadAcquire()
265*/
266
267/*!
268 \fn template <typename T> QAtomicInteger<T>::operator T() const
269 \since 5.3
270
271 Atomically loads the value of this QAtomicInteger using a sequentially
272 consistent memory ordering if possible; or "Acquire" ordering if not. The
273 value is not modified in any way, but note that there's no guarantee that
274 it remains so.
275
276 \sa loadRelaxed(), loadAcquire()
277*/
278
279/*!
280 \fn template <typename T> QAtomicInteger &QAtomicInteger<T>::operator=(T)
281 \since 5.3
282
283 Atomically stores the other value into this atomic type using a
284 sequentially consistent memory ordering if possible; or "Release" ordering
285 if not. This function returns a reference to this object.
286
287 \sa storeRelaxed(), storeRelease()
288*/
289
290/*!
291 \fn template <typename T> bool QAtomicInteger<T>::isReferenceCountingNative()
292
293 Returns \c true if reference counting is implemented using atomic
294 processor instructions, false otherwise.
295*/
296
297/*!
298 \fn template <typename T> bool QAtomicInteger<T>::isReferenceCountingWaitFree()
299
300 Returns \c true if atomic reference counting is wait-free, false
301 otherwise.
302*/
303
304/*!
305 \fn template <typename T> bool QAtomicInteger<T>::ref()
306 Atomically increments the value of this QAtomicInteger. Returns \c true
307 if the new value is non-zero, false otherwise.
308
309 This function uses \e ordered \l {QAtomicInteger#Memory
310 ordering}{memory ordering} semantics, which ensures that memory
311 access before and after the atomic operation (in program order)
312 may not be re-ordered.
313
314 \sa deref(), operator++()
315*/
316
317/*!
318 \fn template <typename T> T QAtomicInteger<T>::operator++()
319 \since 5.3
320
321 Atomically pre-increments the value of this QAtomicInteger. Returns the new
322 value of this atomic.
323
324 This function uses a sequentially consistent memory ordering if possible;
325 or "Ordered" ordering if not.
326
327 \sa ref(), operator++(int), operator--()
328*/
329
330/*!
331 \fn template <typename T> T QAtomicInteger<T>::operator++(int)
332 \since 5.3
333
334 Atomically post-increments the value of this QAtomicInteger. Returns the old
335 value of this atomic.
336
337 This function uses a sequentially consistent memory ordering if possible;
338 or "Ordered" ordering if not.
339
340 \sa ref(), operator++(), operator--(int)
341*/
342
343/*!
344 \fn template <typename T> bool QAtomicInteger<T>::deref()
345 Atomically decrements the value of this QAtomicInteger. Returns \c true
346 if the new value is non-zero, false otherwise.
347
348 This function uses \e ordered \l {QAtomicInteger#Memory
349 ordering}{memory ordering} semantics, which ensures that memory
350 access before and after the atomic operation (in program order)
351 may not be re-ordered.
352
353 \sa ref(), operator--()
354*/
355
356/*!
357 \fn template <typename T> T QAtomicInteger<T>::operator--()
358 \since 5.3
359
360 Atomically pre-decrements the value of this QAtomicInteger. Returns the new
361 value of this atomic.
362
363 This function uses a sequentially consistent memory ordering if possible;
364 or "Ordered" ordering if not.
365
366 \sa deref(), operator--(int), operator++()
367*/
368
369/*!
370 \fn template <typename T> T QAtomicInteger<T>::operator--(int)
371 \since 5.3
372
373 Atomically post-decrements the value of this QAtomicInteger. Returns the old
374 value of this atomic.
375
376 This function uses a sequentially consistent memory ordering if possible;
377 or "Ordered" ordering if not.
378
379 \sa deref(), operator--(), operator++(int)
380*/
381
382/*!
383 \fn template <typename T> bool QAtomicInteger<T>::isTestAndSetNative()
384
385 Returns \c true if test-and-set is implemented using atomic processor
386 instructions, false otherwise.
387*/
388
389/*!
390 \fn template <typename T> bool QAtomicInteger<T>::isTestAndSetWaitFree()
391
392 Returns \c true if atomic test-and-set is wait-free, false otherwise.
393*/
394
395/*!
396 \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelaxed(T expectedValue, T newValue)
397
398 Atomic test-and-set.
399
400 \note If you use this function in a loop, consider using the overload with the
401 additional \c{T &currentValue} argument instead, which avoids the extra loadRelaxed() on
402 failure.
403
404 If the current value of this QAtomicInteger is the \a expectedValue,
405 the test-and-set functions assign the \a newValue to this
406 QAtomicInteger and return true. If the values are \e not the same,
407 this function does nothing and returns \c false.
408
409//![memory-order-relaxed]
410 This function uses \e relaxed \l {QAtomicInteger#Memory
411 ordering}{memory ordering} semantics, leaving the compiler and
412 processor to freely reorder memory accesses.
413//![memory-order-relaxed]
414
415*/
416
417/*!
418 \fn template <typename T> bool QAtomicInteger<T>::testAndSetAcquire(T expectedValue, T newValue)
419
420 Atomic test-and-set.
421
422 \note If you use this function in a loop, consider using the overload with the
423 additional \c{T &currentValue} argument instead, which avoids the extra loadAcquire() on
424 failure.
425
426 If the current value of this QAtomicInteger is the \a expectedValue,
427 the test-and-set functions assign the \a newValue to this
428 QAtomicInteger and return true. If the values are \e not the same,
429 this function does nothing and returns \c false.
430
431//![memory-order-acquire]
432 This function uses \e acquire \l {QAtomicInteger#Memory
433 ordering}{memory ordering} semantics, which ensures that memory
434 access following the atomic operation (in program order) may not
435 be re-ordered before the atomic operation.
436//![memory-order-acquire]
437*/
438
439/*!
440 \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelease(T expectedValue, T newValue)
441
442 Atomic test-and-set.
443
444 \note If you use this function in a loop, consider using the overload with the
445 additional \c{T &currentValue} argument instead, which avoids the extra loadRelaxed() on
446 failure.
447
448 If the current value of this QAtomicInteger is the \a expectedValue,
449 the test-and-set functions assign the \a newValue to this
450 QAtomicInteger and return true. If the values are \e not the same,
451 this function does nothing and returns \c false.
452
453//![memory-order-release]
454 This function uses \e release \l {QAtomicInteger#Memory
455 ordering}{memory ordering} semantics, which ensures that memory
456 access before the atomic operation (in program order) may not be
457 re-ordered after the atomic operation.
458//![memory-order-release]
459*/
460
461/*!
462 \fn template <typename T> bool QAtomicInteger<T>::testAndSetOrdered(T expectedValue, T newValue)
463
464 Atomic test-and-set.
465
466 \note If you use this function in a loop, consider using the overload with the
467 additional \c{T &currentValue} argument instead, which avoids the extra loadAcquire() on
468 failure.
469
470 If the current value of this QAtomicInteger is the \a expectedValue,
471 the test-and-set functions assign the \a newValue to this
472 QAtomicInteger and return true. If the values are \e not the same,
473 this function does nothing and returns \c false.
474
475//![memory-order-ordered]
476 This function uses \e ordered \l {QAtomicInteger#Memory
477 ordering}{memory ordering} semantics, which ensures that memory
478 access before and after the atomic operation (in program order)
479 may not be re-ordered.
480//![memory-order-ordered]
481
482*/
483
484/*!
485 \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelaxed(T expectedValue, T newValue, T &currentValue)
486 \since 5.3
487
488 Atomic test-and-set.
489
490 If the current value of this QAtomicInteger is the \a expectedValue, the
491 test-and-set functions assign the \a newValue to this QAtomicInteger and
492 return \c true. If the values are \e not the same, the functions load the
493 current value of this QAtomicInteger into \a currentValue and return \c false.
494
495 \include qatomic.cpp memory-order-relaxed
496*/
497
498/*!
499 \fn template <typename T> bool QAtomicInteger<T>::testAndSetAcquire(T expectedValue, T newValue, T &currentValue)
500 \since 5.3
501
502 Atomic test-and-set.
503
504 If the current value of this QAtomicInteger is the \a expectedValue, the
505 test-and-set functions assign the \a newValue to this QAtomicInteger and
506 return \c true. If the values are \e not the same, the functions load the
507 current value of this QAtomicInteger into \a currentValue and return \c false.
508
509 \include qatomic.cpp memory-order-acquire
510*/
511
512/*!
513 \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelease(T expectedValue, T newValue, T &currentValue)
514 \since 5.3
515
516 Atomic test-and-set.
517
518 If the current value of this QAtomicInteger is the \a expectedValue, the
519 test-and-set functions assign the \a newValue to this QAtomicInteger and
520 return \c true. If the values are \e not the same, the functions loads the
521 current value of this QAtomicInteger into \a currentValue and return \c false.
522
523 \include qatomic.cpp memory-order-release
524*/
525
526/*!
527 \fn template <typename T> bool QAtomicInteger<T>::testAndSetOrdered(T expectedValue, T newValue, T &currentValue)
528 \since 5.3
529
530 Atomic test-and-set.
531
532 If the current value of this QAtomicInteger is the \a expectedValue, the
533 test-and-set functions assign the \a newValue to this QAtomicInteger and
534 return \c true. If the values are \e not the same, it loads the current
535 value of this QAtomicInteger into \a currentValue and return \c false.
536
537 \include qatomic.cpp memory-order-ordered
538*/
539
540/*!
541 \fn template <typename T> bool QAtomicInteger<T>::isFetchAndStoreNative()
542
543 Returns \c true if fetch-and-store is implemented using atomic
544 processor instructions, false otherwise.
545*/
546
547/*!
548 \fn template <typename T> bool QAtomicInteger<T>::isFetchAndStoreWaitFree()
549
550 Returns \c true if atomic fetch-and-store is wait-free, false
551 otherwise.
552*/
553
554/*!
555 \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreRelaxed(T newValue)
556
557 Atomic fetch-and-store.
558
559 Reads the current value of this QAtomicInteger and then assigns it the
560 \a newValue, returning the original value.
561
562 This function uses \e relaxed \l {QAtomicInteger#Memory
563 ordering}{memory ordering} semantics, leaving the compiler and
564 processor to freely reorder memory accesses.
565*/
566
567/*!
568 \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreAcquire(T newValue)
569
570 Atomic fetch-and-store.
571
572 Reads the current value of this QAtomicInteger and then assigns it the
573 \a newValue, returning the original value.
574
575 This function uses \e acquire \l {QAtomicInteger#Memory
576 ordering}{memory ordering} semantics, which ensures that memory
577 access following the atomic operation (in program order) may not
578 be re-ordered before the atomic operation.
579*/
580
581/*!
582 \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreRelease(T newValue)
583
584 Atomic fetch-and-store.
585
586 Reads the current value of this QAtomicInteger and then assigns it the
587 \a newValue, returning the original value.
588
589 This function uses \e release \l {QAtomicInteger#Memory
590 ordering}{memory ordering} semantics, which ensures that memory
591 access before the atomic operation (in program order) may not be
592 re-ordered after the atomic operation.
593*/
594
595/*!
596 \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreOrdered(T newValue)
597
598 Atomic fetch-and-store.
599
600 Reads the current value of this QAtomicInteger and then assigns it the
601 \a newValue, returning the original value.
602
603 This function uses \e ordered \l {QAtomicInteger#Memory
604 ordering}{memory ordering} semantics, which ensures that memory
605 access before and after the atomic operation (in program order)
606 may not be re-ordered.
607*/
608
609/*!
610 \fn template <typename T> bool QAtomicInteger<T>::isFetchAndAddNative()
611
612 Returns \c true if fetch-and-add is implemented using atomic
613 processor instructions, false otherwise.
614*/
615
616/*!
617 \fn template <typename T> bool QAtomicInteger<T>::isFetchAndAddWaitFree()
618
619 Returns \c true if atomic fetch-and-add is wait-free, false
620 otherwise.
621*/
622
623/*!
624 \fn template <typename T> T QAtomicInteger<T>::fetchAndAddRelaxed(T valueToAdd)
625
626 Atomic fetch-and-add.
627
628 Reads the current value of this QAtomicInteger and then adds
629 \a valueToAdd to the current value, returning the original value.
630
631 This function uses \e relaxed \l {QAtomicInteger#Memory
632 ordering}{memory ordering} semantics, leaving the compiler and
633 processor to freely reorder memory accesses.
634
635 \sa operator+=(), fetchAndSubRelaxed()
636*/
637
638/*!
639 \fn template <typename T> T QAtomicInteger<T>::fetchAndAddAcquire(T valueToAdd)
640
641 Atomic fetch-and-add.
642
643 Reads the current value of this QAtomicInteger and then adds
644 \a valueToAdd to the current value, returning the original value.
645
646 This function uses \e acquire \l {QAtomicInteger#Memory
647 ordering}{memory ordering} semantics, which ensures that memory
648 access following the atomic operation (in program order) may not
649 be re-ordered before the atomic operation.
650
651 \sa operator+=(), fetchAndSubAcquire()
652*/
653
654/*!
655 \fn template <typename T> T QAtomicInteger<T>::fetchAndAddRelease(T valueToAdd)
656
657 Atomic fetch-and-add.
658
659 Reads the current value of this QAtomicInteger and then adds
660 \a valueToAdd to the current value, returning the original value.
661
662 This function uses \e release \l {QAtomicInteger#Memory
663 ordering}{memory ordering} semantics, which ensures that memory
664 access before the atomic operation (in program order) may not be
665 re-ordered after the atomic operation.
666
667 \sa operator+=(), fetchAndSubRelease()
668*/
669
670/*!
671 \fn template <typename T> T QAtomicInteger<T>::fetchAndAddOrdered(T valueToAdd)
672
673 Atomic fetch-and-add.
674
675 Reads the current value of this QAtomicInteger and then adds
676 \a valueToAdd to the current value, returning the original value.
677
678 This function uses \e ordered \l {QAtomicInteger#Memory
679 ordering}{memory ordering} semantics, which ensures that memory
680 access before and after the atomic operation (in program order)
681 may not be re-ordered.
682
683 \sa operator+=(), fetchAndSubOrdered()
684*/
685
686/*!
687 \fn template <typename T> T QAtomicInteger<T>::operator+=(T value)
688 \since 5.3
689
690 Atomic add-and-fetch.
691
692 Reads the current value of this QAtomicInteger and then adds
693 \a value to the current value, returning the new value.
694
695 This function uses a sequentially consistent memory ordering if possible;
696 or "Ordered" ordering if not.
697
698 \sa fetchAndAddOrdered(), operator-=()
699*/
700
701/*!
702 \fn template <typename T> T QAtomicInteger<T>::fetchAndSubRelaxed(T valueToSub)
703 \since 5.3
704
705 Atomic fetch-and-sub.
706
707 Reads the current value of this QAtomicInteger and then subtracts
708 \a valueToSub to the current value, returning the original value.
709
710 This function uses \e relaxed \l {QAtomicInteger#Memory
711 ordering}{memory ordering} semantics, leaving the compiler and
712 processor to freely reorder memory accesses.
713
714 \sa operator-=(), fetchAndAddRelaxed()
715*/
716
717/*!
718 \fn template <typename T> T QAtomicInteger<T>::fetchAndSubAcquire(T valueToSub)
719 \since 5.3
720
721 Atomic fetch-and-sub.
722
723 Reads the current value of this QAtomicInteger and then subtracts
724 \a valueToSub to the current value, returning the original value.
725
726 This function uses \e acquire \l {QAtomicInteger#Memory
727 ordering}{memory ordering} semantics, which ensures that memory
728 access following the atomic operation (in program order) may not
729 be re-ordered before the atomic operation.
730
731 \sa operator-=(), fetchAndAddAcquire()
732*/
733
734/*!
735 \fn template <typename T> T QAtomicInteger<T>::fetchAndSubRelease(T valueToSub)
736 \since 5.3
737
738 Atomic fetch-and-sub.
739
740 Reads the current value of this QAtomicInteger and then subtracts
741 \a valueToSub to the current value, returning the original value.
742
743 This function uses \e release \l {QAtomicInteger#Memory
744 ordering}{memory ordering} semantics, which ensures that memory
745 access before the atomic operation (in program order) may not be
746 re-ordered after the atomic operation.
747
748 \sa operator-=(), fetchAndAddRelease()
749*/
750
751/*!
752 \fn template <typename T> T QAtomicInteger<T>::fetchAndSubOrdered(T valueToSub)
753 \since 5.3
754
755 Atomic fetch-and-sub.
756
757 Reads the current value of this QAtomicInteger and then subtracts
758 \a valueToSub to the current value, returning the original value.
759
760 This function uses \e ordered \l {QAtomicInteger#Memory
761 ordering}{memory ordering} semantics, which ensures that memory
762 access before and after the atomic operation (in program order)
763 may not be re-ordered.
764
765 \sa operator-=(), fetchAndAddOrdered()
766*/
767
768/*!
769 \fn template <typename T> T QAtomicInteger<T>::operator-=(T value)
770 \since 5.3
771
772 Atomic sub-and-fetch.
773
774 Reads the current value of this QAtomicInteger and then subtracts
775 \a value to the current value, returning the new value.
776
777 This function uses a sequentially consistent memory ordering if possible;
778 or "Ordered" ordering if not.
779
780 \sa fetchAndSubOrdered(), operator+=()
781*/
782
783/*!
784 \fn template <typename T> T QAtomicInteger<T>::fetchAndOrRelaxed(T valueToOr)
785 \since 5.3
786
787 Atomic fetch-and-or.
788
789 Reads the current value of this QAtomicInteger and then bitwise-ORs
790 \a valueToOr to the current value, returning the original value.
791
792 This function uses \e relaxed \l {QAtomicInteger#Memory
793 ordering}{memory ordering} semantics, leaving the compiler and
794 processor to freely reorder memory accesses.
795
796 \sa operator|=()
797*/
798
799/*!
800 \fn template <typename T> T QAtomicInteger<T>::fetchAndOrAcquire(T valueToOr)
801 \since 5.3
802
803 Atomic fetch-and-or.
804
805 Reads the current value of this QAtomicInteger and then bitwise-ORs
806 \a valueToOr to the current value, returning the original value.
807
808 This function uses \e acquire \l {QAtomicInteger#Memory
809 ordering}{memory ordering} semantics, which ensures that memory
810 access following the atomic operation (in program order) may not
811 be re-ordered before the atomic operation.
812
813 \sa operator|=()
814*/
815
816/*!
817 \fn template <typename T> T QAtomicInteger<T>::fetchAndOrRelease(T valueToOr)
818 \since 5.3
819
820 Atomic fetch-and-or.
821
822 Reads the current value of this QAtomicInteger and then bitwise-ORs
823 \a valueToOr to the current value, returning the original value.
824
825 This function uses \e release \l {QAtomicInteger#Memory
826 ordering}{memory ordering} semantics, which ensures that memory
827 access before the atomic operation (in program order) may not be
828 re-ordered after the atomic operation.
829
830 \sa operator|=()
831*/
832
833/*!
834 \fn template <typename T> T QAtomicInteger<T>::fetchAndOrOrdered(T valueToOr)
835 \since 5.3
836
837 Atomic fetch-and-or.
838
839 Reads the current value of this QAtomicInteger and then bitwise-ORs
840 \a valueToOr to the current value, returning the original value.
841
842 This function uses \e ordered \l {QAtomicInteger#Memory
843 ordering}{memory ordering} semantics, which ensures that memory
844 access before and after the atomic operation (in program order)
845 may not be re-ordered.
846
847 \sa operator|=()
848*/
849
850/*!
851 \fn template <typename T> T QAtomicInteger<T>::operator|=(T value)
852 \since 5.3
853
854 Atomic or-and-fetch.
855
856 Reads the current value of this QAtomicInteger and then bitwise-ORs
857 \a value to the current value, returning the new value.
858
859 This function uses a sequentially consistent memory ordering if possible;
860 or "Ordered" ordering if not.
861
862 \sa fetchAndOrOrdered()
863*/
864
865/*!
866 \fn template <typename T> T QAtomicInteger<T>::fetchAndXorRelaxed(T valueToXor)
867 \since 5.3
868
869 Atomic fetch-and-xor.
870
871 Reads the current value of this QAtomicInteger and then bitwise-XORs
872 \a valueToXor to the current value, returning the original value.
873
874 This function uses \e relaxed \l {QAtomicInteger#Memory
875 ordering}{memory ordering} semantics, leaving the compiler and
876 processor to freely reorder memory accesses.
877
878 \sa operator^=()
879*/
880
881/*!
882 \fn template <typename T> T QAtomicInteger<T>::fetchAndXorAcquire(T valueToXor)
883 \since 5.3
884
885 Atomic fetch-and-xor.
886
887 Reads the current value of this QAtomicInteger and then bitwise-XORs
888 \a valueToXor to the current value, returning the original value.
889
890 This function uses \e acquire \l {QAtomicInteger#Memory
891 ordering}{memory ordering} semantics, which ensures that memory
892 access following the atomic operation (in program order) may not
893 be re-ordered before the atomic operation.
894
895 \sa operator^=()
896*/
897
898/*!
899 \fn template <typename T> T QAtomicInteger<T>::fetchAndXorRelease(T valueToXor)
900 \since 5.3
901
902 Atomic fetch-and-xor.
903
904 Reads the current value of this QAtomicInteger and then bitwise-XORs
905 \a valueToXor to the current value, returning the original value.
906
907 This function uses \e release \l {QAtomicInteger#Memory
908 ordering}{memory ordering} semantics, which ensures that memory
909 access before the atomic operation (in program order) may not be
910 re-ordered after the atomic operation.
911
912 \sa operator^=()
913*/
914
915/*!
916 \fn template <typename T> T QAtomicInteger<T>::fetchAndXorOrdered(T valueToXor)
917 \since 5.3
918
919 Atomic fetch-and-xor.
920
921 Reads the current value of this QAtomicInteger and then bitwise-XORs
922 \a valueToXor to the current value, returning the original value.
923
924 This function uses \e ordered \l {QAtomicInteger#Memory
925 ordering}{memory ordering} semantics, which ensures that memory
926 access before and after the atomic operation (in program order)
927 may not be re-ordered.
928
929 \sa operator^=()
930*/
931
932/*!
933 \fn template <typename T> T QAtomicInteger<T>::operator^=(T value)
934 \since 5.3
935
936 Atomic xor-and-fetch.
937
938 Reads the current value of this QAtomicInteger and then bitwise-XORs
939 \a value to the current value, returning the new value.
940
941 This function uses a sequentially consistent memory ordering if possible;
942 or "Ordered" ordering if not.
943
944 \sa fetchAndXorOrdered()
945*/
946
947/*!
948 \fn template <typename T> T QAtomicInteger<T>::fetchAndAndRelaxed(T valueToAnd)
949 \since 5.3
950
951 Atomic fetch-and-and.
952
953 Reads the current value of this QAtomicInteger and then bitwise-ANDs
954 \a valueToAnd to the current value, returning the original value.
955
956 This function uses \e relaxed \l {QAtomicInteger#Memory
957 ordering}{memory ordering} semantics, leaving the compiler and
958 processor to freely reorder memory accesses.
959
960 \sa operator&=()
961*/
962
963/*!
964 \fn template <typename T> T QAtomicInteger<T>::fetchAndAndAcquire(T valueToAnd)
965 \since 5.3
966
967 Atomic fetch-and-and.
968
969 Reads the current value of this QAtomicInteger and then bitwise-ANDs
970 \a valueToAnd to the current value, returning the original value.
971
972 This function uses \e acquire \l {QAtomicInteger#Memory
973 ordering}{memory ordering} semantics, which ensures that memory
974 access following the atomic operation (in program order) may not
975 be re-ordered before the atomic operation.
976
977 \sa operator&=()
978*/
979
980/*!
981 \fn template <typename T> T QAtomicInteger<T>::fetchAndAndRelease(T valueToAnd)
982 \since 5.3
983
984 Atomic fetch-and-and.
985
986 Reads the current value of this QAtomicInteger and then bitwise-ANDs
987 \a valueToAnd to the current value, returning the original value.
988
989 This function uses \e release \l {QAtomicInteger#Memory
990 ordering}{memory ordering} semantics, which ensures that memory
991 access before the atomic operation (in program order) may not be
992 re-ordered after the atomic operation.
993
994 \sa operator&=()
995*/
996
997/*!
998 \fn template <typename T> T QAtomicInteger<T>::fetchAndAndOrdered(T valueToAnd)
999 \since 5.3
1000
1001 Atomic fetch-and-and.
1002
1003 Reads the current value of this QAtomicInteger and then bitwise-ANDs
1004 \a valueToAnd to the current value, returning the original value.
1005
1006 This function uses \e ordered \l {QAtomicInteger#Memory
1007 ordering}{memory ordering} semantics, which ensures that memory
1008 access before and after the atomic operation (in program order)
1009 may not be re-ordered.
1010
1011 \sa operator&=()
1012*/
1013
1014/*!
1015 \fn template <typename T> T QAtomicInteger<T>::operator&=(T value)
1016 \since 5.3
1017
1018 Atomic add-and-fetch.
1019
1020 Reads the current value of this QAtomicInteger and then bitwise-ANDs
1021 \a value to the current value, returning the new value.
1022
1023 This function uses a sequentially consistent memory ordering if possible;
1024 or "Ordered" ordering if not.
1025
1026 \sa fetchAndAndOrdered()
1027*/
1028
1029/*!
1030 \macro Q_ATOMIC_INTnn_IS_SUPPORTED
1031 \relates QAtomicInteger
1032
1033 This macro is defined if atomic integers of size \e{nn} (in bits) are
1034 supported in this compiler / architecture combination.
1035
1036 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1037
1038 The following macros always defined:
1039
1040 \list
1041 \li Q_ATOMIC_INT8_IS_SUPPORTED
1042 \li Q_ATOMIC_INT16_IS_SUPPORTED
1043 \li Q_ATOMIC_INT32_IS_SUPPORTED
1044 \endlist
1045*/
1046
1047/*!
1048 \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
1049 \relates QAtomicInteger
1050
1051 This macro is defined if and only if all generations of your
1052 processor support atomic reference counting.
1053
1054 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1055*/
1056
1057/*!
1058 \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
1059 \relates QAtomicInteger
1060
1061 This macro is defined when only certain generations of the
1062 processor support atomic reference counting. Use the
1063 QAtomicInteger::isReferenceCountingNative() function to check what
1064 your processor supports.
1065
1066 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1067*/
1068
1069/*!
1070 \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_NOT_NATIVE
1071 \relates QAtomicInteger
1072
1073 This macro is defined when the hardware does not support atomic
1074 reference counting.
1075
1076 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1077*/
1078
1079/*!
1080 \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_WAIT_FREE
1081 \relates QAtomicInteger
1082
1083 This macro is defined together with
1084 Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE to indicate that
1085 the reference counting is wait-free.
1086
1087 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1088*/
1089
1090/*!
1091 \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_ALWAYS_NATIVE
1092 \relates QAtomicInteger
1093
1094 This macro is defined if and only if your processor supports
1095 atomic test-and-set on integers.
1096
1097 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1098*/
1099
1100/*!
1101 \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_SOMETIMES_NATIVE
1102 \relates QAtomicInteger
1103
1104 This macro is defined when only certain generations of the
1105 processor support atomic test-and-set on integers. Use the
1106 QAtomicInteger::isTestAndSetNative() function to check what your
1107 processor supports.
1108
1109 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1110*/
1111
1112/*!
1113 \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_NOT_NATIVE
1114 \relates QAtomicInteger
1115
1116 This macro is defined when the hardware does not support atomic
1117 test-and-set on integers.
1118
1119 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1120*/
1121
1122/*!
1123 \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_WAIT_FREE
1124 \relates QAtomicInteger
1125
1126 This macro is defined together with
1127 Q_ATOMIC_INTnn_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that the
1128 atomic test-and-set on integers is wait-free.
1129
1130 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1131*/
1132
1133/*!
1134 \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_ALWAYS_NATIVE
1135 \relates QAtomicInteger
1136
1137 This macro is defined if and only if your processor supports
1138 atomic fetch-and-store on integers.
1139
1140 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1141*/
1142
1143/*!
1144 \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
1145 \relates QAtomicInteger
1146
1147 This macro is defined when only certain generations of the
1148 processor support atomic fetch-and-store on integers. Use the
1149 QAtomicInteger::isFetchAndStoreNative() function to check what your
1150 processor supports.
1151
1152 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1153*/
1154
1155/*!
1156 \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_NOT_NATIVE
1157 \relates QAtomicInteger
1158
1159 This macro is defined when the hardware does not support atomic
1160 fetch-and-store on integers.
1161
1162 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1163*/
1164
1165/*!
1166 \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_WAIT_FREE
1167 \relates QAtomicInteger
1168
1169 This macro is defined together with
1170 Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that the
1171 atomic fetch-and-store on integers is wait-free.
1172
1173 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1174*/
1175
1176/*!
1177 \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_ALWAYS_NATIVE
1178 \relates QAtomicInteger
1179
1180 This macro is defined if and only if your processor supports
1181 atomic fetch-and-add on integers.
1182
1183 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1184*/
1185
1186/*!
1187 \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
1188 \relates QAtomicInteger
1189
1190 This macro is defined when only certain generations of the
1191 processor support atomic fetch-and-add on integers. Use the
1192 QAtomicInteger::isFetchAndAddNative() function to check what your
1193 processor supports.
1194
1195 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1196*/
1197
1198/*!
1199 \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_NOT_NATIVE
1200 \relates QAtomicInteger
1201
1202 This macro is defined when the hardware does not support atomic
1203 fetch-and-add on integers.
1204
1205 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1206*/
1207
1208/*!
1209 \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_WAIT_FREE
1210 \relates QAtomicInteger
1211
1212 This macro is defined together with
1213 Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that the
1214 atomic fetch-and-add on integers is wait-free.
1215
1216 \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
1217*/
1218
1219
1220
1221
1222/*!
1223 \class QAtomicPointer
1224 \inmodule QtCore
1225 \brief The QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers.
1226 \since 4.4
1227
1228 \ingroup thread
1229
1230 For atomic operations on integers, see the QAtomicInteger class.
1231
1232 An \e atomic operation is a complex operation that completes without interruption.
1233 The QAtomicPointer class provides atomic test-and-set, fetch-and-store, and fetch-and-add for pointers.
1234
1235 \section1 The Atomic API
1236
1237 \section2 Memory ordering
1238
1239 QAtomicPointer provides several implementations of the atomic
1240 test-and-set, fetch-and-store, and fetch-and-add functions. Each
1241 implementation defines a memory ordering semantic that describes
1242 how memory accesses surrounding the atomic instruction are
1243 executed by the processor. Since many modern architectures allow
1244 out-of-order execution and memory ordering, using the correct
1245 semantic is necessary to ensure that your application functions
1246 properly on all processors.
1247
1248 \list
1249
1250 \li Relaxed - memory ordering is unspecified, leaving the compiler
1251 and processor to freely reorder memory accesses.
1252
1253 \li Acquire - memory access following the atomic operation (in
1254 program order) may not be re-ordered before the atomic operation.
1255
1256 \li Release - memory access before the atomic operation (in program
1257 order) may not be re-ordered after the atomic operation.
1258
1259 \li Ordered - the same Acquire and Release semantics combined.
1260
1261 \endlist
1262
1263 \section2 Test-and-set
1264
1265 If the current value of the QAtomicPointer is an expected value,
1266 the test-and-set functions assign a new value to the
1267 QAtomicPointer and return true. If values are \a not the same,
1268 these functions do nothing and return false. This operation
1269 equates to the following code:
1270
1271 \snippet code/src_corelib_thread_qatomic.cpp 4
1272
1273 There are 4 test-and-set functions: testAndSetRelaxed(),
1274 testAndSetAcquire(), testAndSetRelease(), and
1275 testAndSetOrdered(). See above for an explanation of the different
1276 memory ordering semantics.
1277
1278 \section2 Fetch-and-store
1279
1280 The atomic fetch-and-store functions read the current value of the
1281 QAtomicPointer and then assign a new value, returning the original
1282 value. This operation equates to the following code:
1283
1284 \snippet code/src_corelib_thread_qatomic.cpp 5
1285
1286 There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),
1287 fetchAndStoreAcquire(), fetchAndStoreRelease(), and
1288 fetchAndStoreOrdered(). See above for an explanation of the
1289 different memory ordering semantics.
1290
1291 \section2 Fetch-and-add
1292
1293 The atomic fetch-and-add functions read the current value of the
1294 QAtomicPointer and then add the given value to the current value,
1295 returning the original value. This operation equates to the
1296 following code:
1297
1298 \snippet code/src_corelib_thread_qatomic.cpp 6
1299
1300 There are 4 fetch-and-add functions: fetchAndAddRelaxed(),
1301 fetchAndAddAcquire(), fetchAndAddRelease(), and
1302 fetchAndAddOrdered(). See above for an explanation of the
1303 different memory ordering semantics.
1304
1305 \section1 Feature Tests for the Atomic API
1306
1307 Providing a platform-independent atomic API that works on all
1308 processors is challenging. The API provided by QAtomicPointer is
1309 guaranteed to work atomically on all processors. However, since
1310 not all processors implement support for every operation provided
1311 by QAtomicPointer, it is necessary to expose information about the
1312 processor.
1313
1314 You can check at compile time which features are supported on your
1315 hardware using various macros. These will tell you if your
1316 hardware always, sometimes, or does not support a particular
1317 operation. The macros have the form
1318 Q_ATOMIC_POINTER_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{OPERATION} is
1319 one of TEST_AND_SET, FETCH_AND_STORE, or FETCH_AND_ADD, and
1320 \e{HOW} is one of ALWAYS, SOMETIMES, or NOT. There will always be
1321 exactly one defined macro per operation. For example, if
1322 Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE is defined, neither
1323 Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE nor
1324 Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE will be defined.
1325
1326 An operation that completes in constant time is said to be
1327 wait-free. Such operations are not implemented using locks or
1328 loops of any kind. For atomic operations that are always
1329 supported, and that are wait-free, Qt defines the
1330 Q_ATOMIC_POINTER_\e{OPERATION}_IS_WAIT_FREE in addition to the
1331 Q_ATOMIC_POINTER_\e{OPERATION}_IS_ALWAYS_NATIVE.
1332
1333 In cases where an atomic operation is only supported in newer
1334 generations of the processor, QAtomicPointer also provides a way
1335 to check at runtime what your hardware supports with the
1336 isTestAndSetNative(), isFetchAndStoreNative(), and
1337 isFetchAndAddNative() functions. Wait-free implementations can be
1338 detected using the isTestAndSetWaitFree(),
1339 isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.
1340
1341 Below is a complete list of all feature macros for QAtomicPointer:
1342
1343 \list
1344
1345 \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
1346 \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
1347 \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
1348 \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
1349
1350 \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
1351 \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
1352 \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
1353 \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
1354
1355 \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
1356 \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
1357 \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
1358 \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
1359
1360 \endlist
1361
1362 \sa QAtomicInteger, qYieldCpu()
1363*/
1364
1365/*!
1366 \fn template <typename T> QAtomicPointer<T>::QAtomicPointer(T *value)
1367
1368 Constructs a QAtomicPointer with the given \a value.
1369*/
1370
1371/*!
1372 \fn template <typename T> QAtomicPointer<T>::QAtomicPointer(const QAtomicPointer<T> &other)
1373
1374 Constructs a copy of \a other.
1375*/
1376
1377/*!
1378 \fn template <typename T> QAtomicPointer &QAtomicPointer<T>::operator=(const QAtomicPointer &other)
1379
1380 Assigns \a other to this QAtomicPointer and returns a reference to
1381 this QAtomicPointer.
1382*/
1383
1384/*!
1385 \fn template <typename T> T *QAtomicPointer<T>::loadRelaxed() const
1386 \since 5.14
1387
1388 Atomically loads the value of this QAtomicPointer using relaxed memory
1389 ordering. The value is not modified in any way, but note that there's no
1390 guarantee that it remains so.
1391
1392 \sa storeRelaxed(), loadAcquire()
1393*/
1394
1395
1396/*!
1397 \fn template <typename T> T *QAtomicPointer<T>::loadAcquire() const
1398
1399 Atomically loads the value of this QAtomicPointer using the "Acquire" memory
1400 ordering. The value is not modified in any way, but note that there's no
1401 guarantee that it remains so.
1402
1403 \sa storeRelease(), loadRelaxed()
1404*/
1405
1406/*!
1407 \fn template <typename T> void QAtomicPointer<T>::storeRelaxed(T *newValue)
1408 \since 5.14
1409
1410 Atomically stores the \a newValue value into this atomic type, using
1411 relaxed memory ordering.
1412
1413 \sa storeRelease(), loadRelaxed()
1414*/
1415
1416/*!
1417 \fn template <typename T> void QAtomicPointer<T>::storeRelease(T *newValue)
1418
1419 Atomically stores the \a newValue value into this atomic type, using
1420 the "Release" memory ordering.
1421
1422 \sa storeRelaxed(), loadRelaxed()
1423*/
1424
1425/*!
1426 \fn template <typename T> bool QAtomicPointer<T>::isTestAndSetNative()
1427
1428 Returns \c true if test-and-set is implemented using atomic processor
1429 instructions, false otherwise.
1430*/
1431
1432/*!
1433 \fn template <typename T> bool QAtomicPointer<T>::isTestAndSetWaitFree()
1434
1435 Returns \c true if atomic test-and-set is wait-free, false otherwise.
1436*/
1437
1438/*!
1439 \fn template <typename T> bool QAtomicPointer<T>::testAndSetRelaxed(T *expectedValue, T *newValue)
1440
1441 Atomic test-and-set.
1442
1443 If the current value of this QAtomicPointer is the \a expectedValue,
1444 the test-and-set functions assign the \a newValue to this
1445 QAtomicPointer and return true. If the values are \e not the same,
1446 this function does nothing and returns \c false.
1447
1448 This function uses \e relaxed \l {QAtomicPointer#Memory
1449 ordering}{memory ordering} semantics, leaving the compiler and
1450 processor to freely reorder memory accesses.
1451*/
1452
1453/*!
1454 \fn template <typename T> bool QAtomicPointer<T>::testAndSetAcquire(T *expectedValue, T *newValue)
1455
1456 Atomic test-and-set.
1457
1458 If the current value of this QAtomicPointer is the \a expectedValue,
1459 the test-and-set functions assign the \a newValue to this
1460 QAtomicPointer and return true. If the values are \e not the same,
1461 this function does nothing and returns \c false.
1462
1463 This function uses \e acquire \l {QAtomicPointer#Memory
1464 ordering}{memory ordering} semantics, which ensures that memory
1465 access following the atomic operation (in program order) may not
1466 be re-ordered before the atomic operation.
1467*/
1468
1469/*!
1470 \fn template <typename T> bool QAtomicPointer<T>::testAndSetRelease(T *expectedValue, T *newValue)
1471
1472 Atomic test-and-set.
1473
1474 If the current value of this QAtomicPointer is the \a expectedValue,
1475 the test-and-set functions assign the \a newValue to this
1476 QAtomicPointer and return true. If the values are \e not the same,
1477 this function does nothing and returns \c false.
1478
1479 This function uses \e release \l {QAtomicPointer#Memory
1480 ordering}{memory ordering} semantics, which ensures that memory
1481 access before the atomic operation (in program order) may not be
1482 re-ordered after the atomic operation.
1483*/
1484
1485/*!
1486 \fn template <typename T> bool QAtomicPointer<T>::testAndSetOrdered(T *expectedValue, T *newValue)
1487
1488 Atomic test-and-set.
1489
1490 If the current value of this QAtomicPointer is the \a expectedValue,
1491 the test-and-set functions assign the \a newValue to this
1492 QAtomicPointer and return true. If the values are \e not the same,
1493 this function does nothing and returns \c false.
1494
1495 This function uses \e ordered \l {QAtomicPointer#Memory
1496 ordering}{memory ordering} semantics, which ensures that memory
1497 access before and after the atomic operation (in program order)
1498 may not be re-ordered.
1499*/
1500
1501/*!
1502 \fn template <typename T> bool QAtomicPointer<T>::isFetchAndStoreNative()
1503
1504 Returns \c true if fetch-and-store is implemented using atomic
1505 processor instructions, false otherwise.
1506*/
1507
1508/*!
1509 \fn template <typename T> bool QAtomicPointer<T>::isFetchAndStoreWaitFree()
1510
1511 Returns \c true if atomic fetch-and-store is wait-free, false
1512 otherwise.
1513*/
1514
1515/*!
1516 \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreRelaxed(T *newValue)
1517
1518 Atomic fetch-and-store.
1519
1520 Reads the current value of this QAtomicPointer and then assigns it the
1521 \a newValue, returning the original value.
1522
1523 This function uses \e relaxed \l {QAtomicPointer#Memory
1524 ordering}{memory ordering} semantics, leaving the compiler and
1525 processor to freely reorder memory accesses.
1526*/
1527
1528/*!
1529 \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreAcquire(T *newValue)
1530
1531 Atomic fetch-and-store.
1532
1533 Reads the current value of this QAtomicPointer and then assigns it the
1534 \a newValue, returning the original value.
1535
1536 This function uses \e acquire \l {QAtomicPointer#Memory
1537 ordering}{memory ordering} semantics, which ensures that memory
1538 access following the atomic operation (in program order) may not
1539 be re-ordered before the atomic operation.
1540*/
1541
1542/*!
1543 \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreRelease(T *newValue)
1544
1545 Atomic fetch-and-store.
1546
1547 Reads the current value of this QAtomicPointer and then assigns it the
1548 \a newValue, returning the original value.
1549
1550 This function uses \e release \l {QAtomicPointer#Memory
1551 ordering}{memory ordering} semantics, which ensures that memory
1552 access before the atomic operation (in program order) may not be
1553 re-ordered after the atomic operation.
1554*/
1555
1556/*!
1557 \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreOrdered(T *newValue)
1558
1559 Atomic fetch-and-store.
1560
1561 Reads the current value of this QAtomicPointer and then assigns it the
1562 \a newValue, returning the original value.
1563
1564 This function uses \e ordered \l {QAtomicPointer#Memory
1565 ordering}{memory ordering} semantics, which ensures that memory
1566 access before and after the atomic operation (in program order)
1567 may not be re-ordered.
1568*/
1569
1570/*!
1571 \fn template <typename T> bool QAtomicPointer<T>::isFetchAndAddNative()
1572
1573 Returns \c true if fetch-and-add is implemented using atomic
1574 processor instructions, false otherwise.
1575*/
1576
1577/*!
1578 \fn template <typename T> bool QAtomicPointer<T>::isFetchAndAddWaitFree()
1579
1580 Returns \c true if atomic fetch-and-add is wait-free, false
1581 otherwise.
1582*/
1583
1584/*!
1585 \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddRelaxed(qptrdiff valueToAdd)
1586
1587 Atomic fetch-and-add.
1588
1589 Reads the current value of this QAtomicPointer and then adds
1590 \a valueToAdd to the current value, returning the original value.
1591
1592 This function uses \e relaxed \l {QAtomicPointer#Memory
1593 ordering}{memory ordering} semantics, leaving the compiler and
1594 processor to freely reorder memory accesses.
1595*/
1596
1597/*!
1598 \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddAcquire(qptrdiff valueToAdd)
1599
1600 Atomic fetch-and-add.
1601
1602 Reads the current value of this QAtomicPointer and then adds
1603 \a valueToAdd to the current value, returning the original value.
1604
1605 This function uses \e acquire \l {QAtomicPointer#Memory
1606 ordering}{memory ordering} semantics, which ensures that memory
1607 access following the atomic operation (in program order) may not
1608 be re-ordered before the atomic operation.
1609*/
1610
1611/*!
1612 \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddRelease(qptrdiff valueToAdd)
1613
1614 Atomic fetch-and-add.
1615
1616 Reads the current value of this QAtomicPointer and then adds
1617 \a valueToAdd to the current value, returning the original value.
1618
1619 This function uses \e release \l {QAtomicPointer#Memory
1620 ordering}{memory ordering} semantics, which ensures that memory
1621 access before the atomic operation (in program order) may not be
1622 re-ordered after the atomic operation.
1623*/
1624
1625/*!
1626 \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddOrdered(qptrdiff valueToAdd)
1627
1628 Atomic fetch-and-add.
1629
1630 Reads the current value of this QAtomicPointer and then adds
1631 \a valueToAdd to the current value, returning the original value.
1632
1633 This function uses \e ordered \l {QAtomicPointer#Memory
1634 ordering}{memory ordering} semantics, which ensures that memory
1635 access before and after the atomic operation (in program order)
1636 may not be re-ordered.
1637*/
1638
1639/*!
1640 \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
1641 \relates QAtomicPointer
1642
1643 This macro is defined if and only if your processor supports
1644 atomic test-and-set on pointers.
1645*/
1646
1647/*!
1648 \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
1649 \relates QAtomicPointer
1650
1651 This macro is defined when only certain generations of the
1652 processor support atomic test-and-set on pointers. Use the
1653 QAtomicPointer::isTestAndSetNative() function to check what your
1654 processor supports.
1655*/
1656
1657/*!
1658 \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
1659 \relates QAtomicPointer
1660
1661 This macro is defined when the hardware does not support atomic
1662 test-and-set on pointers.
1663*/
1664
1665/*!
1666 \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
1667 \relates QAtomicPointer
1668
1669 This macro is defined together with
1670 Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that
1671 the atomic test-and-set on pointers is wait-free.
1672*/
1673
1674/*!
1675 \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
1676 \relates QAtomicPointer
1677
1678 This macro is defined if and only if your processor supports
1679 atomic fetch-and-store on pointers.
1680*/
1681
1682/*!
1683 \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
1684 \relates QAtomicPointer
1685
1686 This macro is defined when only certain generations of the
1687 processor support atomic fetch-and-store on pointers. Use the
1688 QAtomicPointer::isFetchAndStoreNative() function to check what
1689 your processor supports.
1690*/
1691
1692/*!
1693 \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
1694 \relates QAtomicPointer
1695
1696 This macro is defined when the hardware does not support atomic
1697 fetch-and-store on pointers.
1698*/
1699
1700/*!
1701 \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
1702 \relates QAtomicPointer
1703
1704 This macro is defined together with
1705 Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that
1706 the atomic fetch-and-store on pointers is wait-free.
1707*/
1708
1709/*!
1710 \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
1711 \relates QAtomicPointer
1712
1713 This macro is defined if and only if your processor supports
1714 atomic fetch-and-add on pointers.
1715*/
1716
1717/*!
1718 \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
1719 \relates QAtomicPointer
1720
1721 This macro is defined when only certain generations of the
1722 processor support atomic fetch-and-add on pointers. Use the
1723 QAtomicPointer::isFetchAndAddNative() function to check what your
1724 processor supports.
1725*/
1726
1727/*!
1728 \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
1729 \relates QAtomicPointer
1730
1731 This macro is defined when the hardware does not support atomic
1732 fetch-and-add on pointers.
1733*/
1734
1735/*!
1736 \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
1737 \relates QAtomicPointer
1738
1739 This macro is defined together with
1740 Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that
1741 the atomic fetch-and-add on pointers is wait-free.
1742*/
1743
1744// static checks
1745#ifndef Q_ATOMIC_INT8_IS_SUPPORTED
1746# error "Q_ATOMIC_INT8_IS_SUPPORTED must be defined"
1747#endif
1748#ifndef Q_ATOMIC_INT16_IS_SUPPORTED
1749# error "Q_ATOMIC_INT16_IS_SUPPORTED must be defined"
1750#endif
1751#ifndef Q_ATOMIC_INT32_IS_SUPPORTED
1752# error "Q_ATOMIC_INT32_IS_SUPPORTED must be defined"
1753#endif
1754#if !defined(Q_ATOMIC_INT64_IS_SUPPORTED) && QT_POINTER_SIZE == 8
1755// 64-bit platform
1756# error "Q_ATOMIC_INT64_IS_SUPPORTED must be defined on a 64-bit platform"
1757#endif
1758
1759QT_BEGIN_NAMESPACE
1760
1761// The following specializations must always be defined
1762static_assert(sizeof(QAtomicInteger<unsigned>));
1763static_assert(sizeof(QAtomicInteger<long>));
1764static_assert(sizeof(QAtomicInteger<unsigned long>));
1765static_assert(sizeof(QAtomicInteger<quintptr>));
1766static_assert(sizeof(QAtomicInteger<qptrdiff>));
1767static_assert(sizeof(QAtomicInteger<char32_t>));
1768
1769static_assert(sizeof(QAtomicInteger<short>));
1770static_assert(sizeof(QAtomicInteger<unsigned short>));
1771static_assert(sizeof(QAtomicInteger<wchar_t>));
1772static_assert(sizeof(QAtomicInteger<char16_t>));
1773
1774static_assert(sizeof(QAtomicInteger<char>));
1775static_assert(sizeof(QAtomicInteger<unsigned char>));
1776static_assert(sizeof(QAtomicInteger<signed char>));
1777static_assert(sizeof(QAtomicInteger<bool>));
1778
1779#ifdef Q_ATOMIC_INT64_IS_SUPPORTED
1780static_assert(sizeof(QAtomicInteger<qint64>));
1781static_assert(sizeof(QAtomicInteger<quint64>));
1782#endif
1783
1784QT_END_NAMESPACE
1785

source code of qtbase/src/corelib/thread/qatomic.cpp