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