src/corelib/thread/qatomic.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtCore module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \class QAtomicInt
  44     \brief The QAtomicInt class provides platform-independent atomic operations on integers.
  45     \since 4.4
  46
  47     \ingroup thread
  48
  49     For atomic operations on pointers, see the QAtomicPointer class.
  50
  51     An \e atomic operation is a complex operation that completes without interruption.
  52     The QAtomicInt class provides atomic reference counting, test-and-set, fetch-and-store,
  53     and fetch-and-add for integers.
  54
  55     \section1 Non-atomic convenience operators
  56
  57     For convenience, QAtomicInt provides integer comparison, cast, and
  58     assignment operators. Note that a combination of these operators
  59     is \e not an atomic operation.
  60
  61     \section1 The Atomic API
  62
  63     \section2 Reference counting
  64
  65     The ref() and deref() functions provide an efficient reference
  66     counting API. The return value of these functions are used to
  67     indicate when the last reference has been released. These
  68     functions allow you to implement your own implicitly shared
  69     classes.
  70
  71     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 0
  72
  73     \section2 Memory ordering
  74
  75     QAtomicInt provides several implementations of the atomic
  76     test-and-set, fetch-and-store, and fetch-and-add functions. Each
  77     implementation defines a memory ordering semantic that describes
  78     how memory accesses surrounding the atomic instruction are
  79     executed by the processor. Since many modern architectures allow
  80     out-of-order execution and memory ordering, using the correct
  81     semantic is necessary to ensure that your application functions
  82     properly on all processors.
  83
  84     \list
  85
  86     \li Relaxed - memory ordering is unspecified, leaving the compiler
  87     and processor to freely reorder memory accesses.
  88
  89     \li Acquire - memory access following the atomic operation (in
  90     program order) may not be re-ordered before the atomic operation.
  91
  92     \li Release - memory access before the atomic operation (in program
  93     order) may not be re-ordered after the atomic operation.
  94
  95     \li Ordered - the same Acquire and Release semantics combined.
  96
  97     \endlist
  98
  99     \section2 Test-and-set
 100
 101     If the current value of the QAtomicInt is an expected value, the
 102     test-and-set functions assign a new value to the QAtomicInt and
 103     return true. If values are \a not the same, these functions do
 104     nothing and return false. This operation equates to the following
 105     code:
 106
 107     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 1
 108
 109     There are 4 test-and-set functions: testAndSetRelaxed(),
 110     testAndSetAcquire(), testAndSetRelease(), and
 111     testAndSetOrdered(). See above for an explanation of the different
 112     memory ordering semantics.
 113
 114     \section2 Fetch-and-store
 115
 116     The atomic fetch-and-store functions read the current value of the
 117     QAtomicInt and then assign a new value, returning the original
 118     value. This operation equates to the following code:
 119
 120     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 2
 121
 122     There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),
 123     fetchAndStoreAcquire(), fetchAndStoreRelease(), and
 124     fetchAndStoreOrdered(). See above for an explanation of the
 125     different memory ordering semantics.
 126
 127     \section2 Fetch-and-add
 128
 129     The atomic fetch-and-add functions read the current value of the
 130     QAtomicInt and then add the given value to the current value,
 131     returning the original value. This operation equates to the
 132     following code:
 133
 134     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 3
 135
 136     There are 4 fetch-and-add functions: fetchAndAddRelaxed(),
 137     fetchAndAddAcquire(), fetchAndAddRelease(), and
 138     fetchAndAddOrdered(). See above for an explanation of the
 139     different memory ordering semantics.
 140
 141     \section1 Feature Tests for the Atomic API
 142
 143     Providing a platform-independent atomic API that works on all
 144     processors is challenging. The API provided by QAtomicInt is
 145     guaranteed to work atomically on all processors. However, since
 146     not all processors implement support for every operation provided
 147     by QAtomicInt, it is necessary to expose information about the
 148     processor.
 149
 150     You can check at compile time which features are supported on your
 151     hardware using various macros. These will tell you if your
 152     hardware always, sometimes, or does not support a particular
 153     operation. The macros have the form
 154     Q_ATOMIC_INT_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{OPERATION}
 155     is one of REFERENCE_COUNTING, TEST_AND_SET,
 156     FETCH_AND_STORE, or FETCH_AND_ADD, and \e{HOW} is one of
 157     ALWAYS, SOMETIMES, or NOT. There will always be exactly one
 158     defined macro per operation. For example, if
 159     Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE is defined,
 160     neither Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE nor
 161     Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE will be defined.
 162
 163     An operation that completes in constant time is said to be
 164     wait-free. Such operations are not implemented using locks or
 165     loops of any kind. For atomic operations that are always
 166     supported, and that are wait-free, Qt defines the
 167     Q_ATOMIC_INT_\e{OPERATION}_IS_WAIT_FREE in addition to the
 168     Q_ATOMIC_INT_\e{OPERATION}_IS_ALWAYS_NATIVE.
 169
 170     In cases where an atomic operation is only supported in newer
 171     generations of the processor, QAtomicInt also provides a way to
 172     check at runtime what your hardware supports with the
 173     isReferenceCountingNative(), isTestAndSetNative(),
 174     isFetchAndStoreNative(), and isFetchAndAddNative()
 175     functions. Wait-free implementations can be detected using the
 176     isReferenceCountingWaitFree(), isTestAndSetWaitFree(),
 177     isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.
 178
 179     Below is a complete list of all feature macros for QAtomicInt:
 180
 181     \list
 182
 183     \li Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
 184     \li Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
 185     \li Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE
 186     \li Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE
 187
 188     \li Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE
 189     \li Q_ATOMIC_INT_TEST_AND_SET_IS_SOMETIMES_NATIVE
 190     \li Q_ATOMIC_INT_TEST_AND_SET_IS_NOT_NATIVE
 191     \li Q_ATOMIC_INT_TEST_AND_SET_IS_WAIT_FREE
 192
 193     \li Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE
 194     \li Q_ATOMIC_INT_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
 195     \li Q_ATOMIC_INT_FETCH_AND_STORE_IS_NOT_NATIVE
 196     \li Q_ATOMIC_INT_FETCH_AND_STORE_IS_WAIT_FREE
 197
 198     \li Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE
 199     \li Q_ATOMIC_INT_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
 200     \li Q_ATOMIC_INT_FETCH_AND_ADD_IS_NOT_NATIVE
 201     \li Q_ATOMIC_INT_FETCH_AND_ADD_IS_WAIT_FREE
 202
 203     \endlist
 204
 205     \sa QAtomicPointer
 206 */
 207
 208 /*! \fn QAtomicInt::QAtomicInt(int value)
 209
 210     Constructs a QAtomicInt with the given \a value.
 211 */
 212
 213 /*! \fn QAtomicInt::QAtomicInt(const QAtomicInt &other)
 214
 215     Constructs a copy of \a other.
 216 */
 217
 218 /*! \fn QAtomicInt &QAtomicInt::operator=(int value)
 219
 220     Assigns the \a value to this QAtomicInt and returns a reference to
 221     this QAtomicInt.
 222 */
 223
 224 /*! \fn QAtomicInt &QAtomicInt::operator=(const QAtomicInt &other)
 225
 226     Assigns \a other to this QAtomicInt and returns a reference to
 227     this QAtomicInt.
 228 */
 229
 230 /*! \fn bool QAtomicInt::operator==(int value) const
 231
 232     Returns true if the \a value is equal to the value in this
 233     QAtomicInt; otherwise returns false.
 234 */
 235
 236 /*! \fn bool QAtomicInt::operator!=(int value) const
 237
 238     Returns true if the value of this QAtomicInt is not equal to \a
 239     value; otherwise returns false.
 240 */
 241
 242 /*! \fn bool QAtomicInt::operator!() const
 243
 244     Returns true is the value of this QAtomicInt is zero; otherwise
 245     returns false.
 246 */
 247
 248 /*! \fn QAtomicInt::operator int() const
 249
 250     Returns the value stored by the QAtomicInt object as an integer.
 251 */
 252
 253 /*! \fn bool QAtomicInt::isReferenceCountingNative()
 254
 255     Returns true if reference counting is implemented using atomic
 256     processor instructions, false otherwise.
 257 */
 258
 259 /*! \fn bool QAtomicInt::isReferenceCountingWaitFree()
 260
 261     Returns true if atomic reference counting is wait-free, false
 262     otherwise.
 263 */
 264
 265 /*! \fn bool QAtomicInt::ref()
 266     Atomically increments the value of this QAtomicInt. Returns true
 267     if the new value is non-zero, false otherwise.
 268
 269     This function uses \e ordered \l {QAtomicInt#Memory
 270     ordering}{memory ordering} semantics, which ensures that memory
 271     access before and after the atomic operation (in program order)
 272     may not be re-ordered.
 273
 274     \sa deref()
 275 */
 276
 277 /*! \fn bool QAtomicInt::deref()
 278     Atomically decrements the value of this QAtomicInt. Returns true
 279     if the new value is non-zero, false otherwise.
 280
 281     This function uses \e ordered \l {QAtomicInt#Memory
 282     ordering}{memory ordering} semantics, which ensures that memory
 283     access before and after the atomic operation (in program order)
 284     may not be re-ordered.
 285
 286     \sa ref()
 287 */
 288
 289 /*! \fn bool QAtomicInt::isTestAndSetNative()
 290
 291     Returns true if test-and-set is implemented using atomic processor
 292     instructions, false otherwise.
 293 */
 294
 295 /*! \fn bool QAtomicInt::isTestAndSetWaitFree()
 296
 297     Returns true if atomic test-and-set is wait-free, false otherwise.
 298 */
 299
 300 /*! \fn bool QAtomicInt::testAndSetRelaxed(int expectedValue, int newValue)
 301
 302     Atomic test-and-set.
 303
 304     If the current value of this QAtomicInt is the \a expectedValue,
 305     the test-and-set functions assign the \a newValue to this
 306     QAtomicInt and return true. If the values are \e not the same,
 307     this function does nothing and returns false.
 308
 309     This function uses \e relaxed \l {QAtomicInt#Memory
 310     ordering}{memory ordering} semantics, leaving the compiler and
 311     processor to freely reorder memory accesses.
 312 */
 313
 314 /*! \fn bool QAtomicInt::testAndSetAcquire(int expectedValue, int newValue)
 315
 316     Atomic test-and-set.
 317
 318     If the current value of this QAtomicInt is the \a expectedValue,
 319     the test-and-set functions assign the \a newValue to this
 320     QAtomicInt and return true. If the values are \e not the same,
 321     this function does nothing and returns false.
 322
 323     This function uses \e acquire \l {QAtomicInt#Memory
 324     ordering}{memory ordering} semantics, which ensures that memory
 325     access following the atomic operation (in program order) may not
 326     be re-ordered before the atomic operation.
 327 */
 328
 329 /*! \fn bool QAtomicInt::testAndSetRelease(int expectedValue, int newValue)
 330
 331     Atomic test-and-set.
 332
 333     If the current value of this QAtomicInt is the \a expectedValue,
 334     the test-and-set functions assign the \a newValue to this
 335     QAtomicInt and return true. If the values are \e not the same,
 336     this function does nothing and returns false.
 337
 338     This function uses \e release \l {QAtomicInt#Memory
 339     ordering}{memory ordering} semantics, which ensures that memory
 340     access before the atomic operation (in program order) may not be
 341     re-ordered after the atomic operation.
 342 */
 343
 344 /*! \fn bool QAtomicInt::testAndSetOrdered(int expectedValue, int newValue)
 345
 346     Atomic test-and-set.
 347
 348     If the current value of this QAtomicInt is the \a expectedValue,
 349     the test-and-set functions assign the \a newValue to this
 350     QAtomicInt and return true. If the values are \e not the same,
 351     this function does nothing and returns false.
 352
 353     This function uses \e ordered \l {QAtomicInt#Memory
 354     ordering}{memory ordering} semantics, which ensures that memory
 355     access before and after the atomic operation (in program order)
 356     may not be re-ordered.
 357 */
 358
 359 /*! \fn bool QAtomicInt::isFetchAndStoreNative()
 360
 361     Returns true if fetch-and-store is implemented using atomic
 362     processor instructions, false otherwise.
 363 */
 364
 365 /*! \fn bool QAtomicInt::isFetchAndStoreWaitFree()
 366
 367     Returns true if atomic fetch-and-store is wait-free, false
 368     otherwise.
 369 */
 370
 371 /*! \fn int QAtomicInt::fetchAndStoreRelaxed(int newValue)
 372
 373     Atomic fetch-and-store.
 374
 375     Reads the current value of this QAtomicInt and then assigns it the
 376     \a newValue, returning the original value.
 377
 378     This function uses \e relaxed \l {QAtomicInt#Memory
 379     ordering}{memory ordering} semantics, leaving the compiler and
 380     processor to freely reorder memory accesses.
 381 */
 382
 383 /*! \fn int QAtomicInt::fetchAndStoreAcquire(int newValue)
 384
 385     Atomic fetch-and-store.
 386
 387     Reads the current value of this QAtomicInt and then assigns it the
 388     \a newValue, returning the original value.
 389
 390     This function uses \e acquire \l {QAtomicInt#Memory
 391     ordering}{memory ordering} semantics, which ensures that memory
 392     access following the atomic operation (in program order) may not
 393     be re-ordered before the atomic operation.
 394 */
 395
 396 /*! \fn int QAtomicInt::fetchAndStoreRelease(int newValue)
 397
 398     Atomic fetch-and-store.
 399
 400     Reads the current value of this QAtomicInt and then assigns it the
 401     \a newValue, returning the original value.
 402
 403     This function uses \e release \l {QAtomicInt#Memory
 404     ordering}{memory ordering} semantics, which ensures that memory
 405     access before the atomic operation (in program order) may not be
 406     re-ordered after the atomic operation.
 407 */
 408
 409 /*! \fn int QAtomicInt::fetchAndStoreOrdered(int newValue)
 410
 411     Atomic fetch-and-store.
 412
 413     Reads the current value of this QAtomicInt and then assigns it the
 414     \a newValue, returning the original value.
 415
 416     This function uses \e ordered \l {QAtomicInt#Memory
 417     ordering}{memory ordering} semantics, which ensures that memory
 418     access before and after the atomic operation (in program order)
 419     may not be re-ordered.
 420 */
 421
 422 /*! \fn bool QAtomicInt::isFetchAndAddNative()
 423
 424     Returns true if fetch-and-add is implemented using atomic
 425     processor instructions, false otherwise.
 426 */
 427
 428 /*! \fn bool QAtomicInt::isFetchAndAddWaitFree()
 429
 430     Returns true if atomic fetch-and-add is wait-free, false
 431     otherwise.
 432 */
 433
 434 /*! \fn int QAtomicInt::fetchAndAddRelaxed(int valueToAdd)
 435
 436     Atomic fetch-and-add.
 437
 438     Reads the current value of this QAtomicInt and then adds
 439     \a valueToAdd to the current value, returning the original value.
 440
 441     This function uses \e relaxed \l {QAtomicInt#Memory
 442     ordering}{memory ordering} semantics, leaving the compiler and
 443     processor to freely reorder memory accesses.
 444 */
 445
 446 /*! \fn int QAtomicInt::fetchAndAddAcquire(int valueToAdd)
 447
 448     Atomic fetch-and-add.
 449
 450     Reads the current value of this QAtomicInt and then adds
 451     \a valueToAdd to the current value, returning the original value.
 452
 453     This function uses \e acquire \l {QAtomicInt#Memory
 454     ordering}{memory ordering} semantics, which ensures that memory
 455     access following the atomic operation (in program order) may not
 456     be re-ordered before the atomic operation.
 457 */
 458
 459 /*! \fn int QAtomicInt::fetchAndAddRelease(int valueToAdd)
 460
 461     Atomic fetch-and-add.
 462
 463     Reads the current value of this QAtomicInt and then adds
 464     \a valueToAdd to the current value, returning the original value.
 465
 466     This function uses \e release \l {QAtomicInt#Memory
 467     ordering}{memory ordering} semantics, which ensures that memory
 468     access before the atomic operation (in program order) may not be
 469     re-ordered after the atomic operation.
 470 */
 471
 472 /*! \fn int QAtomicInt::fetchAndAddOrdered(int valueToAdd)
 473
 474     Atomic fetch-and-add.
 475
 476     Reads the current value of this QAtomicInt and then adds
 477     \a valueToAdd to the current value, returning the original value.
 478
 479     This function uses \e ordered \l {QAtomicInt#Memory
 480     ordering}{memory ordering} semantics, which ensures that memory
 481     access before and after the atomic operation (in program order)
 482     may not be re-ordered.
 483 */
 484
 485 /*!
 486     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
 487     \relates QAtomicInt
 488
 489     This macro is defined if and only if all generations of your
 490     processor support atomic reference counting.
 491 */
 492
 493 /*!
 494     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
 495     \relates QAtomicInt
 496
 497     This macro is defined when only certain generations of the
 498     processor support atomic reference counting. Use the
 499     QAtomicInt::isReferenceCountingNative() function to check what
 500     your processor supports.
 501 */
 502
 503 /*!
 504     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE
 505     \relates QAtomicInt
 506
 507     This macro is defined when the hardware does not support atomic
 508     reference counting.
 509 */
 510
 511 /*!
 512     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE
 513     \relates QAtomicInt
 514
 515     This macro is defined together with
 516     Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE to indicate that
 517     the reference counting is wait-free.
 518 */
 519
 520 /*!
 521     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE
 522     \relates QAtomicInt
 523
 524     This macro is defined if and only if your processor supports
 525     atomic test-and-set on integers.
 526 */
 527
 528 /*!
 529     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_SOMETIMES_NATIVE
 530     \relates QAtomicInt
 531
 532     This macro is defined when only certain generations of the
 533     processor support atomic test-and-set on integers. Use the
 534     QAtomicInt::isTestAndSetNative() function to check what your
 535     processor supports.
 536 */
 537
 538 /*!
 539     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_NOT_NATIVE
 540     \relates QAtomicInt
 541
 542     This macro is defined when the hardware does not support atomic
 543     test-and-set on integers.
 544 */
 545
 546 /*!
 547     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_WAIT_FREE
 548     \relates QAtomicInt
 549
 550     This macro is defined together with
 551     Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that the
 552     atomic test-and-set on integers is wait-free.
 553 */
 554
 555 /*!
 556     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE
 557     \relates QAtomicInt
 558
 559     This macro is defined if and only if your processor supports
 560     atomic fetch-and-store on integers.
 561 */
 562
 563 /*!
 564     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
 565     \relates QAtomicInt
 566
 567     This macro is defined when only certain generations of the
 568     processor support atomic fetch-and-store on integers. Use the
 569     QAtomicInt::isFetchAndStoreNative() function to check what your
 570     processor supports.
 571 */
 572
 573 /*!
 574     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_NOT_NATIVE
 575     \relates QAtomicInt
 576
 577     This macro is defined when the hardware does not support atomic
 578     fetch-and-store on integers.
 579 */
 580
 581 /*!
 582     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_WAIT_FREE
 583     \relates QAtomicInt
 584
 585     This macro is defined together with
 586     Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that the
 587     atomic fetch-and-store on integers is wait-free.
 588 */
 589
 590 /*!
 591     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE
 592     \relates QAtomicInt
 593
 594     This macro is defined if and only if your processor supports
 595     atomic fetch-and-add on integers.
 596 */
 597
 598 /*!
 599     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
 600     \relates QAtomicInt
 601
 602     This macro is defined when only certain generations of the
 603     processor support atomic fetch-and-add on integers. Use the
 604     QAtomicInt::isFetchAndAddNative() function to check what your
 605     processor supports.
 606 */
 607
 608 /*!
 609     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_NOT_NATIVE
 610     \relates QAtomicInt
 611
 612     This macro is defined when the hardware does not support atomic
 613     fetch-and-add on integers.
 614 */
 615
 616 /*!
 617     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_WAIT_FREE
 618     \relates QAtomicInt
 619
 620     This macro is defined together with
 621     Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that the
 622     atomic fetch-and-add on integers is wait-free.
 623 */
 624
 625
 626
 627
 628 /*!
 629     \class QAtomicPointer
 630     \brief The QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers.
 631     \since 4.4
 632
 633     \ingroup thread
 634
 635     For atomic operations on integers, see the QAtomicInt class.
 636
 637     An \e atomic operation is a complex operation that completes without interruption.
 638     The QAtomicPointer class provides atomic test-and-set, fetch-and-store, and fetch-and-add for pointers.
 639
 640     \section1 Non-atomic convenience operators
 641
 642     For convenience, QAtomicPointer provides pointer comparison, cast,
 643     dereference, and assignment operators. Note that these operators
 644     are \e not atomic.
 645
 646     \section1 The Atomic API
 647
 648     \section2 Memory ordering
 649
 650     QAtomicPointer provides several implementations of the atomic
 651     test-and-set, fetch-and-store, and fetch-and-add functions. Each
 652     implementation defines a memory ordering semantic that describes
 653     how memory accesses surrounding the atomic instruction are
 654     executed by the processor. Since many modern architectures allow
 655     out-of-order execution and memory ordering, using the correct
 656     semantic is necessary to ensure that your application functions
 657     properly on all processors.
 658
 659     \list
 660
 661     \li Relaxed - memory ordering is unspecified, leaving the compiler
 662     and processor to freely reorder memory accesses.
 663
 664     \li Acquire - memory access following the atomic operation (in
 665     program order) may not be re-ordered before the atomic operation.
 666
 667     \li Release - memory access before the atomic operation (in program
 668     order) may not be re-ordered after the atomic operation.
 669
 670     \li Ordered - the same Acquire and Release semantics combined.
 671
 672     \endlist
 673
 674     \section2 Test-and-set
 675
 676     If the current value of the QAtomicPointer is an expected value,
 677     the test-and-set functions assign a new value to the
 678     QAtomicPointer and return true. If values are \a not the same,
 679     these functions do nothing and return false. This operation
 680     equates to the following code:
 681
 682     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 4
 683
 684     There are 4 test-and-set functions: testAndSetRelaxed(),
 685     testAndSetAcquire(), testAndSetRelease(), and
 686     testAndSetOrdered(). See above for an explanation of the different
 687     memory ordering semantics.
 688
 689     \section2 Fetch-and-store
 690
 691     The atomic fetch-and-store functions read the current value of the
 692     QAtomicPointer and then assign a new value, returning the original
 693     value. This operation equates to the following code:
 694
 695     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 5
 696
 697     There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),
 698     fetchAndStoreAcquire(), fetchAndStoreRelease(), and
 699     fetchAndStoreOrdered(). See above for an explanation of the
 700     different memory ordering semantics.
 701
 702     \section2 Fetch-and-add
 703
 704     The atomic fetch-and-add functions read the current value of the
 705     QAtomicPointer and then add the given value to the current value,
 706     returning the original value. This operation equates to the
 707     following code:
 708
 709     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 6
 710
 711     There are 4 fetch-and-add functions: fetchAndAddRelaxed(),
 712     fetchAndAddAcquire(), fetchAndAddRelease(), and
 713     fetchAndAddOrdered(). See above for an explanation of the
 714     different memory ordering semantics.
 715
 716     \section1 Feature Tests for the Atomic API
 717
 718     Providing a platform-independent atomic API that works on all
 719     processors is challenging. The API provided by QAtomicPointer is
 720     guaranteed to work atomically on all processors. However, since
 721     not all processors implement support for every operation provided
 722     by QAtomicPointer, it is necessary to expose information about the
 723     processor.
 724
 725     You can check at compile time which features are supported on your
 726     hardware using various macros. These will tell you if your
 727     hardware always, sometimes, or does not support a particular
 728     operation. The macros have the form
 729     Q_ATOMIC_POINTER_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{OPERATION} is
 730     one of TEST_AND_SET, FETCH_AND_STORE, or FETCH_AND_ADD, and
 731     \e{HOW} is one of ALWAYS, SOMETIMES, or NOT. There will always be
 732     exactly one defined macro per operation. For example, if
 733     Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE is defined, neither
 734     Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE nor
 735     Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE will be defined.
 736
 737     An operation that completes in constant time is said to be
 738     wait-free. Such operations are not implemented using locks or
 739     loops of any kind. For atomic operations that are always
 740     supported, and that are wait-free, Qt defines the
 741     Q_ATOMIC_POINTER_\e{OPERATION}_IS_WAIT_FREE in addition to the
 742     Q_ATOMIC_POINTER_\e{OPERATION}_IS_ALWAYS_NATIVE.
 743
 744     In cases where an atomic operation is only supported in newer
 745     generations of the processor, QAtomicPointer also provides a way
 746     to check at runtime what your hardware supports with the
 747     isTestAndSetNative(), isFetchAndStoreNative(), and
 748     isFetchAndAddNative() functions. Wait-free implementations can be
 749     detected using the isTestAndSetWaitFree(),
 750     isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.
 751
 752     Below is a complete list of all feature macros for QAtomicPointer:
 753
 754     \list
 755
 756     \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
 757     \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
 758     \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
 759     \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
 760
 761     \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
 762     \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
 763     \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
 764     \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
 765
 766     \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
 767     \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
 768     \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
 769     \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
 770
 771     \endlist
 772
 773     \sa QAtomicInt
 774 */
 775
 776 /*! \fn QAtomicPointer::QAtomicPointer(T *value)
 777
 778     Constructs a QAtomicPointer with the given \a value.
 779 */
 780
 781 /*! \fn QAtomicPointer::QAtomicPointer(const QAtomicPointer<T> &other)
 782
 783     Constructs a copy of \a other.
 784 */
 785
 786 /*! \fn QAtomicPointer<T> &QAtomicPointer::operator=(T *value)
 787
 788     Assigns the \a value to this QAtomicPointer and returns a
 789     reference to this QAtomicPointer.
 790 */
 791
 792 /*! \fn QAtomicPointer<T> &QAtomicPointer::operator=(const QAtomicPointer<T> &other)
 793
 794     Assigns \a other to this QAtomicPointer and returns a reference to
 795     this QAtomicPointer.
 796 */
 797
 798 /*! \fn bool QAtomicPointer::operator==(T *value) const
 799
 800     Returns true if the \a value is equal to the value in this
 801     QAtomicPointer; otherwise returns false.
 802 */
 803
 804 /*! \fn bool QAtomicPointer::operator!=(T *value) const
 805
 806     Returns true if the value of this QAtomicPointer is not equal to
 807     \a value; otherwise returns false.
 808 */
 809
 810 /*! \fn bool QAtomicPointer::operator!() const
 811
 812     Returns true is the current value of this QAtomicPointer is zero;
 813     otherwise returns false.
 814 */
 815
 816 /*! \fn QAtomicPointer::operator T *() const
 817
 818     Returns the current pointer value stored by this QAtomicPointer
 819     object.
 820 */
 821
 822 /*! \fn T *QAtomicPointer::operator->() const
 823
 824 */
 825
 826 /*! \fn bool QAtomicPointer::isTestAndSetNative()
 827
 828     Returns true if test-and-set is implemented using atomic processor
 829     instructions, false otherwise.
 830 */
 831
 832 /*! \fn bool QAtomicPointer::isTestAndSetWaitFree()
 833
 834     Returns true if atomic test-and-set is wait-free, false otherwise.
 835 */
 836
 837 /*! \fn bool QAtomicPointer::testAndSetRelaxed(T *expectedValue, T *newValue)
 838
 839     Atomic test-and-set.
 840
 841     If the current value of this QAtomicPointer is the \a expectedValue,
 842     the test-and-set functions assign the \a newValue to this
 843     QAtomicPointer and return true. If the values are \e not the same,
 844     this function does nothing and returns false.
 845
 846     This function uses \e relaxed \l {QAtomicPointer#Memory
 847     ordering}{memory ordering} semantics, leaving the compiler and
 848     processor to freely reorder memory accesses.
 849 */
 850
 851 /*! \fn bool QAtomicPointer::testAndSetAcquire(T *expectedValue, T *newValue)
 852
 853     Atomic test-and-set.
 854
 855     If the current value of this QAtomicPointer is the \a expectedValue,
 856     the test-and-set functions assign the \a newValue to this
 857     QAtomicPointer and return true. If the values are \e not the same,
 858     this function does nothing and returns false.
 859
 860     This function uses \e acquire \l {QAtomicPointer#Memory
 861     ordering}{memory ordering} semantics, which ensures that memory
 862     access following the atomic operation (in program order) may not
 863     be re-ordered before the atomic operation.
 864 */
 865
 866 /*! \fn bool QAtomicPointer::testAndSetRelease(T *expectedValue, T *newValue)
 867
 868     Atomic test-and-set.
 869
 870     If the current value of this QAtomicPointer is the \a expectedValue,
 871     the test-and-set functions assign the \a newValue to this
 872     QAtomicPointer and return true. If the values are \e not the same,
 873     this function does nothing and returns false.
 874
 875     This function uses \e release \l {QAtomicPointer#Memory
 876     ordering}{memory ordering} semantics, which ensures that memory
 877     access before the atomic operation (in program order) may not be
 878     re-ordered after the atomic operation.
 879 */
 880
 881 /*! \fn bool QAtomicPointer::testAndSetOrdered(T *expectedValue, T *newValue)
 882
 883     Atomic test-and-set.
 884
 885     If the current value of this QAtomicPointer is the \a expectedValue,
 886     the test-and-set functions assign the \a newValue to this
 887     QAtomicPointer and return true. If the values are \e not the same,
 888     this function does nothing and returns false.
 889
 890     This function uses \e ordered \l {QAtomicPointer#Memory
 891     ordering}{memory ordering} semantics, which ensures that memory
 892     access before and after the atomic operation (in program order)
 893     may not be re-ordered.
 894 */
 895
 896 /*! \fn bool QAtomicPointer::isFetchAndStoreNative()
 897
 898     Returns true if fetch-and-store is implemented using atomic
 899     processor instructions, false otherwise.
 900 */
 901
 902 /*! \fn bool QAtomicPointer::isFetchAndStoreWaitFree()
 903
 904     Returns true if atomic fetch-and-store is wait-free, false
 905     otherwise.
 906 */
 907
 908 /*! \fn T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)
 909
 910     Atomic fetch-and-store.
 911
 912     Reads the current value of this QAtomicPointer and then assigns it the
 913     \a newValue, returning the original value.
 914
 915     This function uses \e relaxed \l {QAtomicPointer#Memory
 916     ordering}{memory ordering} semantics, leaving the compiler and
 917     processor to freely reorder memory accesses.
 918 */
 919
 920 /*! \fn T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)
 921
 922     Atomic fetch-and-store.
 923
 924     Reads the current value of this QAtomicPointer and then assigns it the
 925     \a newValue, returning the original value.
 926
 927     This function uses \e acquire \l {QAtomicPointer#Memory
 928     ordering}{memory ordering} semantics, which ensures that memory
 929     access following the atomic operation (in program order) may not
 930     be re-ordered before the atomic operation.
 931 */
 932
 933 /*! \fn T *QAtomicPointer::fetchAndStoreRelease(T *newValue)
 934
 935     Atomic fetch-and-store.
 936
 937     Reads the current value of this QAtomicPointer and then assigns it the
 938     \a newValue, returning the original value.
 939
 940     This function uses \e release \l {QAtomicPointer#Memory
 941     ordering}{memory ordering} semantics, which ensures that memory
 942     access before the atomic operation (in program order) may not be
 943     re-ordered after the atomic operation.
 944 */
 945
 946 /*! \fn T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)
 947
 948     Atomic fetch-and-store.
 949
 950     Reads the current value of this QAtomicPointer and then assigns it the
 951     \a newValue, returning the original value.
 952
 953     This function uses \e ordered \l {QAtomicPointer#Memory
 954     ordering}{memory ordering} semantics, which ensures that memory
 955     access before and after the atomic operation (in program order)
 956     may not be re-ordered.
 957 */
 958
 959 /*! \fn bool QAtomicPointer::isFetchAndAddNative()
 960
 961     Returns true if fetch-and-add is implemented using atomic
 962     processor instructions, false otherwise.
 963 */
 964
 965 /*! \fn bool QAtomicPointer::isFetchAndAddWaitFree()
 966
 967     Returns true if atomic fetch-and-add is wait-free, false
 968     otherwise.
 969 */
 970
 971 /*! \fn T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)
 972
 973     Atomic fetch-and-add.
 974
 975     Reads the current value of this QAtomicPointer and then adds
 976     \a valueToAdd to the current value, returning the original value.
 977
 978     This function uses \e relaxed \l {QAtomicPointer#Memory
 979     ordering}{memory ordering} semantics, leaving the compiler and
 980     processor to freely reorder memory accesses.
 981 */
 982
 983 /*! \fn T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)
 984
 985     Atomic fetch-and-add.
 986
 987     Reads the current value of this QAtomicPointer and then adds
 988     \a valueToAdd to the current value, returning the original value.
 989
 990     This function uses \e acquire \l {QAtomicPointer#Memory
 991     ordering}{memory ordering} semantics, which ensures that memory
 992     access following the atomic operation (in program order) may not
 993     be re-ordered before the atomic operation.
 994 */
 995
 996 /*! \fn T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)
 997
 998     Atomic fetch-and-add.
 999
1000     Reads the current value of this QAtomicPointer and then adds
1001     \a valueToAdd to the current value, returning the original value.
1002
1003     This function uses \e release \l {QAtomicPointer#Memory
1004     ordering}{memory ordering} semantics, which ensures that memory
1005     access before the atomic operation (in program order) may not be
1006     re-ordered after the atomic operation.
1007 */
1008
1009 /*! \fn T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)
1010
1011     Atomic fetch-and-add.
1012
1013     Reads the current value of this QAtomicPointer and then adds
1014     \a valueToAdd to the current value, returning the original value.
1015
1016     This function uses \e ordered \l {QAtomicPointer#Memory
1017     ordering}{memory ordering} semantics, which ensures that memory
1018     access before and after the atomic operation (in program order)
1019     may not be re-ordered.
1020 */
1021
1022 /*!
1023     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
1024     \relates QAtomicPointer
1025
1026     This macro is defined if and only if your processor supports
1027     atomic test-and-set on pointers.
1028 */
1029
1030 /*!
1031     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
1032     \relates QAtomicPointer
1033
1034     This macro is defined when only certain generations of the
1035     processor support atomic test-and-set on pointers. Use the
1036     QAtomicPointer::isTestAndSetNative() function to check what your
1037     processor supports.
1038 */
1039
1040 /*!
1041     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
1042     \relates QAtomicPointer
1043
1044     This macro is defined when the hardware does not support atomic
1045     test-and-set on pointers.
1046 */
1047
1048 /*!
1049     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
1050     \relates QAtomicPointer
1051
1052     This macro is defined together with
1053     Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that
1054     the atomic test-and-set on pointers is wait-free.
1055 */
1056
1057 /*!
1058     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
1059     \relates QAtomicPointer
1060
1061     This macro is defined if and only if your processor supports
1062     atomic fetch-and-store on pointers.
1063 */
1064
1065 /*!
1066     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
1067     \relates QAtomicPointer
1068
1069     This macro is defined when only certain generations of the
1070     processor support atomic fetch-and-store on pointers. Use the
1071     QAtomicPointer::isFetchAndStoreNative() function to check what
1072     your processor supports.
1073 */
1074
1075 /*!
1076     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
1077     \relates QAtomicPointer
1078
1079     This macro is defined when the hardware does not support atomic
1080     fetch-and-store on pointers.
1081 */
1082
1083 /*!
1084     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
1085     \relates QAtomicPointer
1086
1087     This macro is defined together with
1088     Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that
1089     the atomic fetch-and-store on pointers is wait-free.
1090 */
1091
1092 /*!
1093     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
1094     \relates QAtomicPointer
1095
1096     This macro is defined if and only if your processor supports
1097     atomic fetch-and-add on pointers.
1098 */
1099
1100 /*!
1101     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
1102     \relates QAtomicPointer
1103
1104     This macro is defined when only certain generations of the
1105     processor support atomic fetch-and-add on pointers. Use the
1106     QAtomicPointer::isFetchAndAddNative() function to check what your
1107     processor supports.
1108 */
1109
1110 /*!
1111     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
1112     \relates QAtomicPointer
1113
1114     This macro is defined when the hardware does not support atomic
1115     fetch-and-add on pointers.
1116 */
1117
1118 /*!
1119     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
1120     \relates QAtomicPointer
1121
1122     This macro is defined together with
1123     Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that
1124     the atomic fetch-and-add on pointers is wait-free.
1125 */