1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtCore module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    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 complex operation that completes without interruption is said

    52     to be \e atomic. The QAtomicInt class provides atomic reference

    53     counting, test-and-set, fetch-and-store, and fetch-and-add for

    54     integers.

    55 

    56     \section1 Non-atomic convenience operators

    57 

    58     For convenience, QAtomicInt provides integer comparison, cast, and

    59     assignment operators. Note that a combination of these operators

    60     is \e not an atomic operation.

    61 

    62     \section1 The Atomic API

    63 

    64     \section2 Reference counting

    65 

    66     The ref() and deref() functions provide an efficient reference

    67     counting API. The return value of these functions are used to

    68     indicate when the last reference has been released. These

    69     functions allow you to implement your own implicitly shared

    70     classes.

    71 

    72     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 0

    73 

    74     \section2 Memory ordering

    75 

    76     QAtomicInt provides several implementations of the atomic

    77     test-and-set, fetch-and-store, and fetch-and-add functions. Each

    78     implementation defines a memory ordering semantic that describes

    79     how memory accesses surrounding the atomic instruction are

    80     executed by the processor. Since many modern architectures allow

    81     out-of-order execution and memory ordering, using the correct

    82     semantic is necessary to ensure that your application functions

    83     properly on all processors.

    84 

    85     \list

    86 

    87     \o Relaxed - memory ordering is unspecified, leaving the compiler

    88     and processor to freely reorder memory accesses.

    89 

    90     \o Acquire - memory access following the atomic operation (in

    91     program order) may not be re-ordered before the atomic operation.

    92 

    93     \o Release - memory access before the atomic operation (in program

    94     order) may not be re-ordered after the atomic operation.

    95 

    96     \o Ordered - the same Acquire and Release semantics combined.

    97 

    98     \endlist

    99 

   100     \section2 Test-and-set

   101 

   102     If the current value of the QAtomicInt is an expected value, the

   103     test-and-set functions assign a new value to the QAtomicInt and

   104     return true. If values are \a not the same, these functions do

   105     nothing and return false. This operation equates to the following

   106     code:

   107 

   108     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 1

   109 

   110     There are 4 test-and-set functions: testAndSetRelaxed(),

   111     testAndSetAcquire(), testAndSetRelease(), and

   112     testAndSetOrdered(). See above for an explanation of the different

   113     memory ordering semantics.

   114 

   115     \section2 Fetch-and-store

   116 

   117     The atomic fetch-and-store functions read the current value of the

   118     QAtomicInt and then assign a new value, returning the original

   119     value. This operation equates to the following code:

   120 

   121     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 2

   122 

   123     There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),

   124     fetchAndStoreAcquire(), fetchAndStoreRelease(), and

   125     fetchAndStoreOrdered(). See above for an explanation of the

   126     different memory ordering semantics.

   127 

   128     \section2 Fetch-and-add

   129 

   130     The atomic fetch-and-add functions read the current value of the

   131     QAtomicInt and then add the given value to the current value,

   132     returning the original value. This operation equates to the

   133     following code:

   134 

   135     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 3

   136 

   137     There are 4 fetch-and-add functions: fetchAndAddRelaxed(),

   138     fetchAndAddAcquire(), fetchAndAddRelease(), and

   139     fetchAndAddOrdered(). See above for an explanation of the

   140     different memory ordering semantics.

   141 

   142     \section1 Feature Tests for the Atomic API

   143 

   144     Providing a platform-independent atomic API that works on all

   145     processors is challenging. The API provided by QAtomicInt is

   146     guaranteed to work atomically on all processors. However, since

   147     not all processors implement support for every operation provided

   148     by QAtomicInt, it is necessary to expose information about the

   149     processor.

   150 

   151     You can check at compile time which features are supported on your

   152     hardware using various macros. These will tell you if your

   153     hardware always, sometimes, or does not support a particular

   154     operation. The macros have the form

   155     Q_ATOMIC_INT_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{OPERATION}

   156     is one of REFERENCE_COUNTING, TEST_AND_SET,

   157     FETCH_AND_STORE, or FETCH_AND_ADD, and \e{HOW} is one of

   158     ALWAYS, SOMETIMES, or NOT. There will always be exactly one

   159     defined macro per operation. For example, if

   160     Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE is defined,

   161     neither Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE nor

   162     Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE will be defined.

   163 

   164     An operation that completes in constant time is said to be

   165     wait-free. Such operations are not implemented using locks or

   166     loops of any kind. For atomic operations that are always

   167     supported, and that are wait-free, Qt defines the

   168     Q_ATOMIC_INT_\e{OPERATION}_IS_WAIT_FREE in addition to the

   169     Q_ATOMIC_INT_\e{OPERATION}_IS_ALWAYS_NATIVE.

   170 

   171     In cases where an atomic operation is only supported in newer

   172     generations of the processor, QAtomicInt also provides a way to

   173     check at runtime what your hardware supports with the

   174     isReferenceCountingNative(), isTestAndSetNative(),

   175     isFetchAndStoreNative(), and isFetchAndAddNative()

   176     functions. Wait-free implementations can be detected using the

   177     isReferenceCountingWaitFree(), isTestAndSetWaitFree(),

   178     isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.

   179 

   180     Below is a complete list of all feature macros for QAtomicInt:

   181 

   182     \list

   183 

   184     \o Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE

   185     \o Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE

   186     \o Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE

   187     \o Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE

   188 

   189     \o Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE

   190     \o Q_ATOMIC_INT_TEST_AND_SET_IS_SOMETIMES_NATIVE

   191     \o Q_ATOMIC_INT_TEST_AND_SET_IS_NOT_NATIVE

   192     \o Q_ATOMIC_INT_TEST_AND_SET_IS_WAIT_FREE

   193 

   194     \o Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE

   195     \o Q_ATOMIC_INT_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

   196     \o Q_ATOMIC_INT_FETCH_AND_STORE_IS_NOT_NATIVE

   197     \o Q_ATOMIC_INT_FETCH_AND_STORE_IS_WAIT_FREE

   198 

   199     \o Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE

   200     \o Q_ATOMIC_INT_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

   201     \o Q_ATOMIC_INT_FETCH_AND_ADD_IS_NOT_NATIVE

   202     \o Q_ATOMIC_INT_FETCH_AND_ADD_IS_WAIT_FREE

   203 

   204     \endlist

   205 

   206     \sa QAtomicPointer

   207 */

   208 

   209 /*! \fn QAtomicInt::QAtomicInt(int value)

   210 

   211     Constructs a QAtomicInt with the given \a value.

   212 */

   213 

   214 /*! \fn QAtomicInt::QAtomicInt(const QAtomicInt &other)

   215 

   216     Constructs a copy of \a other.

   217 */

   218 

   219 /*! \fn QAtomicInt &QAtomicInt::operator=(int value)

   220 

   221     Assigns the \a value to this QAtomicInt and returns a reference to

   222     this QAtomicInt.

   223 */

   224 

   225 /*! \fn QAtomicInt &QAtomicInt::operator=(const QAtomicInt &other)

   226 

   227     Assigns \a other to this QAtomicInt and returns a reference to

   228     this QAtomicInt.

   229 */

   230 

   231 /*! \fn bool QAtomicInt::operator==(int value) const

   232 

   233     Returns true if the \a value is equal to the value in this

   234     QAtomicInt; otherwise returns false.

   235 */

   236 

   237 /*! \fn bool QAtomicInt::operator!=(int value) const

   238 

   239     Returns true if the value of this QAtomicInt is not equal to \a

   240     value; otherwise returns false.

   241 */

   242 

   243 /*! \fn bool QAtomicInt::operator!() const

   244 

   245     Returns true is the value of this QAtomicInt is zero; otherwise

   246     returns false.

   247 */

   248 

   249 /*! \fn QAtomicInt::operator int() const

   250 

   251     Returns the value stored by the QAtomicInt object as an integer.

   252 */

   253 

   254 /*! \fn bool QAtomicInt::isReferenceCountingNative()

   255 

   256     Returns true if reference counting is implemented using atomic

   257     processor instructions, false otherwise.

   258 */

   259 

   260 /*! \fn bool QAtomicInt::isReferenceCountingWaitFree()

   261 

   262     Returns true if atomic reference counting is wait-free, false

   263     otherwise.

   264 */

   265 

   266 /*! \fn bool QAtomicInt::ref()

   267     Atomically increments the value of this QAtomicInt. Returns true

   268     if the new value is non-zero, false otherwise.

   269 

   270     This function uses \e ordered \l {QAtomicInt#Memory

   271     ordering}{memory ordering} semantics, which ensures that memory

   272     access before and after the atomic operation (in program order)

   273     may not be re-ordered.

   274 

   275     \sa deref()

   276 */

   277 

   278 /*! \fn bool QAtomicInt::deref()

   279     Atomically decrements the value of this QAtomicInt. Returns true

   280     if the new value is non-zero, false otherwise.

   281 

   282     This function uses \e ordered \l {QAtomicInt#Memory

   283     ordering}{memory ordering} semantics, which ensures that memory

   284     access before and after the atomic operation (in program order)

   285     may not be re-ordered.

   286 

   287     \sa ref()

   288 */

   289 

   290 /*! \fn bool QAtomicInt::isTestAndSetNative()

   291 

   292     Returns true if test-and-set is implemented using atomic processor

   293     instructions, false otherwise.

   294 */

   295 

   296 /*! \fn bool QAtomicInt::isTestAndSetWaitFree()

   297 

   298     Returns true if atomic test-and-set is wait-free, false otherwise.

   299 */

   300 

   301 /*! \fn bool QAtomicInt::testAndSetRelaxed(int expectedValue, int newValue)

   302 

   303     Atomic test-and-set.

   304 

   305     If the current value of this QAtomicInt is the \a expectedValue,

   306     the test-and-set functions assign the \a newValue to this

   307     QAtomicInt and return true. If the values are \e not the same,

   308     this function does nothing and returns false.

   309 

   310     This function uses \e relaxed \l {QAtomicInt#Memory

   311     ordering}{memory ordering} semantics, leaving the compiler and

   312     processor to freely reorder memory accesses.

   313 */

   314 

   315 /*! \fn bool QAtomicInt::testAndSetAcquire(int expectedValue, int newValue)

   316 

   317     Atomic test-and-set.

   318 

   319     If the current value of this QAtomicInt is the \a expectedValue,

   320     the test-and-set functions assign the \a newValue to this

   321     QAtomicInt and return true. If the values are \e not the same,

   322     this function does nothing and returns false.

   323 

   324     This function uses \e acquire \l {QAtomicInt#Memory

   325     ordering}{memory ordering} semantics, which ensures that memory

   326     access following the atomic operation (in program order) may not

   327     be re-ordered before the atomic operation.

   328 */

   329 

   330 /*! \fn bool QAtomicInt::testAndSetRelease(int expectedValue, int newValue)

   331 

   332     Atomic test-and-set.

   333 

   334     If the current value of this QAtomicInt is the \a expectedValue,

   335     the test-and-set functions assign the \a newValue to this

   336     QAtomicInt and return true. If the values are \e not the same,

   337     this function does nothing and returns false.

   338 

   339     This function uses \e release \l {QAtomicInt#Memory

   340     ordering}{memory ordering} semantics, which ensures that memory

   341     access before the atomic operation (in program order) may not be

   342     re-ordered after the atomic operation.

   343 */

   344 

   345 /*! \fn bool QAtomicInt::testAndSetOrdered(int expectedValue, int newValue)

   346 

   347     Atomic test-and-set.

   348 

   349     If the current value of this QAtomicInt is the \a expectedValue,

   350     the test-and-set functions assign the \a newValue to this

   351     QAtomicInt and return true. If the values are \e not the same,

   352     this function does nothing and returns false.

   353 

   354     This function uses \e ordered \l {QAtomicInt#Memory

   355     ordering}{memory ordering} semantics, which ensures that memory

   356     access before and after the atomic operation (in program order)

   357     may not be re-ordered.

   358 */

   359 

   360 /*! \fn bool QAtomicInt::isFetchAndStoreNative()

   361 

   362     Returns true if fetch-and-store is implemented using atomic

   363     processor instructions, false otherwise.

   364 */

   365 

   366 /*! \fn bool QAtomicInt::isFetchAndStoreWaitFree()

   367 

   368     Returns true if atomic fetch-and-store is wait-free, false

   369     otherwise.

   370 */

   371 

   372 /*! \fn int QAtomicInt::fetchAndStoreRelaxed(int newValue)

   373 

   374     Atomic fetch-and-store.

   375 

   376     Reads the current value of this QAtomicInt and then assigns it the

   377     \a newValue, returning the original value.

   378 

   379     This function uses \e relaxed \l {QAtomicInt#Memory

   380     ordering}{memory ordering} semantics, leaving the compiler and

   381     processor to freely reorder memory accesses.

   382 */

   383 

   384 /*! \fn int QAtomicInt::fetchAndStoreAcquire(int newValue)

   385 

   386     Atomic fetch-and-store.

   387 

   388     Reads the current value of this QAtomicInt and then assigns it the

   389     \a newValue, returning the original value.

   390 

   391     This function uses \e acquire \l {QAtomicInt#Memory

   392     ordering}{memory ordering} semantics, which ensures that memory

   393     access following the atomic operation (in program order) may not

   394     be re-ordered before the atomic operation.

   395 */

   396 

   397 /*! \fn int QAtomicInt::fetchAndStoreRelease(int newValue)

   398 

   399     Atomic fetch-and-store.

   400 

   401     Reads the current value of this QAtomicInt and then assigns it the

   402     \a newValue, returning the original value.

   403 

   404     This function uses \e release \l {QAtomicInt#Memory

   405     ordering}{memory ordering} semantics, which ensures that memory

   406     access before the atomic operation (in program order) may not be

   407     re-ordered after the atomic operation.

   408 */

   409 

   410 /*! \fn int QAtomicInt::fetchAndStoreOrdered(int newValue)

   411 

   412     Atomic fetch-and-store.

   413 

   414     Reads the current value of this QAtomicInt and then assigns it the

   415     \a newValue, returning the original value.

   416 

   417     This function uses \e ordered \l {QAtomicInt#Memory

   418     ordering}{memory ordering} semantics, which ensures that memory

   419     access before and after the atomic operation (in program order)

   420     may not be re-ordered.

   421 */

   422 

   423 /*! \fn bool QAtomicInt::isFetchAndAddNative()

   424 

   425     Returns true if fetch-and-add is implemented using atomic

   426     processor instructions, false otherwise.

   427 */

   428 

   429 /*! \fn bool QAtomicInt::isFetchAndAddWaitFree()

   430 

   431     Returns true if atomic fetch-and-add is wait-free, false

   432     otherwise.

   433 */

   434 

   435 /*! \fn int QAtomicInt::fetchAndAddRelaxed(int valueToAdd)

   436 

   437     Atomic fetch-and-add.

   438 

   439     Reads the current value of this QAtomicInt and then adds

   440     \a valueToAdd to the current value, returning the original value.

   441 

   442     This function uses \e relaxed \l {QAtomicInt#Memory

   443     ordering}{memory ordering} semantics, leaving the compiler and

   444     processor to freely reorder memory accesses.

   445 */

   446 

   447 /*! \fn int QAtomicInt::fetchAndAddAcquire(int valueToAdd)

   448 

   449     Atomic fetch-and-add.

   450 

   451     Reads the current value of this QAtomicInt and then adds

   452     \a valueToAdd to the current value, returning the original value.

   453 

   454     This function uses \e acquire \l {QAtomicInt#Memory

   455     ordering}{memory ordering} semantics, which ensures that memory

   456     access following the atomic operation (in program order) may not

   457     be re-ordered before the atomic operation.

   458 */

   459 

   460 /*! \fn int QAtomicInt::fetchAndAddRelease(int valueToAdd)

   461 

   462     Atomic fetch-and-add.

   463 

   464     Reads the current value of this QAtomicInt and then adds

   465     \a valueToAdd to the current value, returning the original value.

   466 

   467     This function uses \e release \l {QAtomicInt#Memory

   468     ordering}{memory ordering} semantics, which ensures that memory

   469     access before the atomic operation (in program order) may not be

   470     re-ordered after the atomic operation.

   471 */

   472 

   473 /*! \fn int QAtomicInt::fetchAndAddOrdered(int valueToAdd)

   474 

   475     Atomic fetch-and-add.

   476 

   477     Reads the current value of this QAtomicInt and then adds

   478     \a valueToAdd to the current value, returning the original value.

   479 

   480     This function uses \e ordered \l {QAtomicInt#Memory

   481     ordering}{memory ordering} semantics, which ensures that memory

   482     access before and after the atomic operation (in program order)

   483     may not be re-ordered.

   484 */

   485 

   486 /*!

   487     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE

   488     \relates QAtomicInt

   489 

   490     This macro is defined if and only if all generations of your

   491     processor support atomic reference counting.

   492 */

   493 

   494 /*!

   495     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE

   496     \relates QAtomicInt

   497 

   498     This macro is defined when only certain generations of the

   499     processor support atomic reference counting. Use the

   500     QAtomicInt::isReferenceCountingNative() function to check what

   501     your processor supports.

   502 */

   503 

   504 /*!

   505     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE

   506     \relates QAtomicInt

   507 

   508     This macro is defined when the hardware does not support atomic

   509     reference counting.

   510 */

   511 

   512 /*!

   513     \macro Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE

   514     \relates QAtomicInt

   515 

   516     This macro is defined together with

   517     Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE to indicate that

   518     the reference counting is wait-free.

   519 */

   520 

   521 /*!

   522     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE

   523     \relates QAtomicInt

   524 

   525     This macro is defined if and only if your processor supports

   526     atomic test-and-set on integers.

   527 */

   528 

   529 /*!

   530     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_SOMETIMES_NATIVE

   531     \relates QAtomicInt

   532 

   533     This macro is defined when only certain generations of the

   534     processor support atomic test-and-set on integers. Use the

   535     QAtomicInt::isTestAndSetNative() function to check what your

   536     processor supports.

   537 */

   538 

   539 /*!

   540     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_NOT_NATIVE

   541     \relates QAtomicInt

   542 

   543     This macro is defined when the hardware does not support atomic

   544     test-and-set on integers.

   545 */

   546 

   547 /*!

   548     \macro Q_ATOMIC_INT_TEST_AND_SET_IS_WAIT_FREE

   549     \relates QAtomicInt

   550 

   551     This macro is defined together with

   552     Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that the

   553     atomic test-and-set on integers is wait-free.

   554 */

   555 

   556 /*!

   557     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE

   558     \relates QAtomicInt

   559 

   560     This macro is defined if and only if your processor supports

   561     atomic fetch-and-store on integers.

   562 */

   563 

   564 /*!

   565     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

   566     \relates QAtomicInt

   567 

   568     This macro is defined when only certain generations of the

   569     processor support atomic fetch-and-store on integers. Use the

   570     QAtomicInt::isFetchAndStoreNative() function to check what your

   571     processor supports.

   572 */

   573 

   574 /*!

   575     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_NOT_NATIVE

   576     \relates QAtomicInt

   577 

   578     This macro is defined when the hardware does not support atomic

   579     fetch-and-store on integers.

   580 */

   581 

   582 /*!

   583     \macro Q_ATOMIC_INT_FETCH_AND_STORE_IS_WAIT_FREE

   584     \relates QAtomicInt

   585 

   586     This macro is defined together with

   587     Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that the

   588     atomic fetch-and-store on integers is wait-free.

   589 */

   590 

   591 /*!

   592     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE

   593     \relates QAtomicInt

   594 

   595     This macro is defined if and only if your processor supports

   596     atomic fetch-and-add on integers.

   597 */

   598 

   599 /*!

   600     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

   601     \relates QAtomicInt

   602 

   603     This macro is defined when only certain generations of the

   604     processor support atomic fetch-and-add on integers. Use the

   605     QAtomicInt::isFetchAndAddNative() function to check what your

   606     processor supports.

   607 */

   608 

   609 /*!

   610     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_NOT_NATIVE

   611     \relates QAtomicInt

   612 

   613     This macro is defined when the hardware does not support atomic

   614     fetch-and-add on integers.

   615 */

   616 

   617 /*!

   618     \macro Q_ATOMIC_INT_FETCH_AND_ADD_IS_WAIT_FREE

   619     \relates QAtomicInt

   620 

   621     This macro is defined together with

   622     Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that the

   623     atomic fetch-and-add on integers is wait-free.

   624 */

   625 

   626 

   627 

   628 

   629 /*!

   630     \class QAtomicPointer

   631     \brief The QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers.

   632     \since 4.4

   633 

   634     \ingroup thread

   635 

   636     For atomic operations on integers, see the QAtomicInt class.

   637 

   638     An complex operation that completes without interruption is said

   639     to be \e atomic. The QAtomicPointer class provides atomic

   640     test-and-set, fetch-and-store, and fetch-and-add for pointers.

   641 

   642     \section1 Non-atomic convenience operators

   643 

   644     For convenience, QAtomicPointer provides pointer comparison, cast,

   645     dereference, and assignment operators. Note that these operators

   646     are \e not atomic.

   647 

   648     \section1 The Atomic API

   649 

   650     \section2 Memory ordering

   651 

   652     QAtomicPointer provides several implementations of the atomic

   653     test-and-set, fetch-and-store, and fetch-and-add functions. Each

   654     implementation defines a memory ordering semantic that describes

   655     how memory accesses surrounding the atomic instruction are

   656     executed by the processor. Since many modern architectures allow

   657     out-of-order execution and memory ordering, using the correct

   658     semantic is necessary to ensure that your application functions

   659     properly on all processors.

   660 

   661     \list

   662 

   663     \o Relaxed - memory ordering is unspecified, leaving the compiler

   664     and processor to freely reorder memory accesses.

   665 

   666     \o Acquire - memory access following the atomic operation (in

   667     program order) may not be re-ordered before the atomic operation.

   668 

   669     \o Release - memory access before the atomic operation (in program

   670     order) may not be re-ordered after the atomic operation.

   671 

   672     \o Ordered - the same Acquire and Release semantics combined.

   673 

   674     \endlist

   675 

   676     \section2 Test-and-set

   677 

   678     If the current value of the QAtomicPointer is an expected value,

   679     the test-and-set functions assign a new value to the

   680     QAtomicPointer and return true. If values are \a not the same,

   681     these functions do nothing and return false. This operation

   682     equates to the following code:

   683 

   684     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 4

   685 

   686     There are 4 test-and-set functions: testAndSetRelaxed(),

   687     testAndSetAcquire(), testAndSetRelease(), and

   688     testAndSetOrdered(). See above for an explanation of the different

   689     memory ordering semantics.

   690 

   691     \section2 Fetch-and-store

   692 

   693     The atomic fetch-and-store functions read the current value of the

   694     QAtomicPointer and then assign a new value, returning the original

   695     value. This operation equates to the following code:

   696 

   697     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 5

   698 

   699     There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),

   700     fetchAndStoreAcquire(), fetchAndStoreRelease(), and

   701     fetchAndStoreOrdered(). See above for an explanation of the

   702     different memory ordering semantics.

   703 

   704     \section2 Fetch-and-add

   705 

   706     The atomic fetch-and-add functions read the current value of the

   707     QAtomicPointer and then add the given value to the current value,

   708     returning the original value. This operation equates to the

   709     following code:

   710 

   711     \snippet doc/src/snippets/code/src_corelib_thread_qatomic.cpp 6

   712 

   713     There are 4 fetch-and-add functions: fetchAndAddRelaxed(),

   714     fetchAndAddAcquire(), fetchAndAddRelease(), and

   715     fetchAndAddOrdered(). See above for an explanation of the

   716     different memory ordering semantics.

   717 

   718     \section1 Feature Tests for the Atomic API

   719 

   720     Providing a platform-independent atomic API that works on all

   721     processors is challenging. The API provided by QAtomicPointer is

   722     guaranteed to work atomically on all processors. However, since

   723     not all processors implement support for every operation provided

   724     by QAtomicPointer, it is necessary to expose information about the

   725     processor.

   726 

   727     You can check at compile time which features are supported on your

   728     hardware using various macros. These will tell you if your

   729     hardware always, sometimes, or does not support a particular

   730     operation. The macros have the form

   731     Q_ATOMIC_POINTER_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{OPERATION} is

   732     one of TEST_AND_SET, FETCH_AND_STORE, or FETCH_AND_ADD, and

   733     \e{HOW} is one of ALWAYS, SOMETIMES, or NOT. There will always be

   734     exactly one defined macro per operation. For example, if

   735     Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE is defined, neither

   736     Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE nor

   737     Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE will be defined.

   738 

   739     An operation that completes in constant time is said to be

   740     wait-free. Such operations are not implemented using locks or

   741     loops of any kind. For atomic operations that are always

   742     supported, and that are wait-free, Qt defines the

   743     Q_ATOMIC_POINTER_\e{OPERATION}_IS_WAIT_FREE in addition to the

   744     Q_ATOMIC_POINTER_\e{OPERATION}_IS_ALWAYS_NATIVE.

   745 

   746     In cases where an atomic operation is only supported in newer

   747     generations of the processor, QAtomicPointer also provides a way

   748     to check at runtime what your hardware supports with the

   749     isTestAndSetNative(), isFetchAndStoreNative(), and

   750     isFetchAndAddNative() functions. Wait-free implementations can be

   751     detected using the isTestAndSetWaitFree(),

   752     isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.

   753 

   754     Below is a complete list of all feature macros for QAtomicPointer:

   755 

   756     \list

   757 

   758     \o Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE

   759     \o Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE

   760     \o Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE

   761     \o Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

   762 

   763     \o Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

   764     \o Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

   765     \o Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

   766     \o Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE

   767 

   768     \o Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

   769     \o Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

   770     \o Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

   771     \o Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

   772 

   773     \endlist

   774 

   775     \sa QAtomicInt

   776 */

   777 

   778 /*! \fn QAtomicPointer::QAtomicPointer(T *value)

   779 

   780     Constructs a QAtomicPointer with the given \a value.

   781 */

   782 

   783 /*! \fn QAtomicPointer::QAtomicPointer(const QAtomicPointer<T> &other)

   784 

   785     Constructs a copy of \a other.

   786 */

   787 

   788 /*! \fn QAtomicPointer<T> &QAtomicPointer::operator=(T *value)

   789 

   790     Assigns the \a value to this QAtomicPointer and returns a

   791     reference to this QAtomicPointer.

   792 */

   793 

   794 /*! \fn QAtomicPointer<T> &QAtomicPointer::operator=(const QAtomicPointer<T> &other)

   795 

   796     Assigns \a other to this QAtomicPointer and returns a reference to

   797     this QAtomicPointer.

   798 */

   799 

   800 /*! \fn bool QAtomicPointer::operator==(T *value) const

   801 

   802     Returns true if the \a value is equal to the value in this

   803     QAtomicPointer; otherwise returns false.

   804 */

   805 

   806 /*! \fn bool QAtomicPointer::operator!=(T *value) const

   807 

   808     Returns true if the value of this QAtomicPointer is not equal to

   809     \a value; otherwise returns false.

   810 */

   811 

   812 /*! \fn bool QAtomicPointer::operator!() const

   813 

   814     Returns true is the current value of this QAtomicPointer is zero;

   815     otherwise returns false.

   816 */

   817 

   818 /*! \fn QAtomicPointer::operator T *() const

   819 

   820     Returns the current pointer value stored by this QAtomicPointer

   821     object.

   822 */

   823 

   824 /*! \fn T *QAtomicPointer::operator->() const

   825 

   826 */

   827 

   828 /*! \fn bool QAtomicPointer::isTestAndSetNative()

   829 

   830     Returns true if test-and-set is implemented using atomic processor

   831     instructions, false otherwise.

   832 */

   833 

   834 /*! \fn bool QAtomicPointer::isTestAndSetWaitFree()

   835 

   836     Returns true if atomic test-and-set is wait-free, false otherwise.

   837 */

   838 

   839 /*! \fn bool QAtomicPointer::testAndSetRelaxed(T *expectedValue, T *newValue)

   840 

   841     Atomic test-and-set.

   842 

   843     If the current value of this QAtomicPointer is the \a expectedValue,

   844     the test-and-set functions assign the \a newValue to this

   845     QAtomicPointer and return true. If the values are \e not the same,

   846     this function does nothing and returns false.

   847 

   848     This function uses \e relaxed \l {QAtomicPointer#Memory

   849     ordering}{memory ordering} semantics, leaving the compiler and

   850     processor to freely reorder memory accesses.

   851 */

   852 

   853 /*! \fn bool QAtomicPointer::testAndSetAcquire(T *expectedValue, T *newValue)

   854 

   855     Atomic test-and-set.

   856 

   857     If the current value of this QAtomicPointer is the \a expectedValue,

   858     the test-and-set functions assign the \a newValue to this

   859     QAtomicPointer and return true. If the values are \e not the same,

   860     this function does nothing and returns false.

   861 

   862     This function uses \e acquire \l {QAtomicPointer#Memory

   863     ordering}{memory ordering} semantics, which ensures that memory

   864     access following the atomic operation (in program order) may not

   865     be re-ordered before the atomic operation.

   866 */

   867 

   868 /*! \fn bool QAtomicPointer::testAndSetRelease(T *expectedValue, T *newValue)

   869 

   870     Atomic test-and-set.

   871 

   872     If the current value of this QAtomicPointer is the \a expectedValue,

   873     the test-and-set functions assign the \a newValue to this

   874     QAtomicPointer and return true. If the values are \e not the same,

   875     this function does nothing and returns false.

   876 

   877     This function uses \e release \l {QAtomicPointer#Memory

   878     ordering}{memory ordering} semantics, which ensures that memory

   879     access before the atomic operation (in program order) may not be

   880     re-ordered after the atomic operation.

   881 */

   882 

   883 /*! \fn bool QAtomicPointer::testAndSetOrdered(T *expectedValue, T *newValue)

   884 

   885     Atomic test-and-set.

   886 

   887     If the current value of this QAtomicPointer is the \a expectedValue,

   888     the test-and-set functions assign the \a newValue to this

   889     QAtomicPointer and return true. If the values are \e not the same,

   890     this function does nothing and returns false.

   891 

   892     This function uses \e ordered \l {QAtomicPointer#Memory

   893     ordering}{memory ordering} semantics, which ensures that memory

   894     access before and after the atomic operation (in program order)

   895     may not be re-ordered.

   896 */

   897 

   898 /*! \fn bool QAtomicPointer::isFetchAndStoreNative()

   899 

   900     Returns true if fetch-and-store is implemented using atomic

   901     processor instructions, false otherwise.

   902 */

   903 

   904 /*! \fn bool QAtomicPointer::isFetchAndStoreWaitFree()

   905 

   906     Returns true if atomic fetch-and-store is wait-free, false

   907     otherwise.

   908 */

   909 

   910 /*! \fn T *QAtomicPointer::fetchAndStoreRelaxed(T *newValue)

   911 

   912     Atomic fetch-and-store.

   913 

   914     Reads the current value of this QAtomicPointer and then assigns it the

   915     \a newValue, returning the original value.

   916 

   917     This function uses \e relaxed \l {QAtomicPointer#Memory

   918     ordering}{memory ordering} semantics, leaving the compiler and

   919     processor to freely reorder memory accesses.

   920 */

   921 

   922 /*! \fn T *QAtomicPointer::fetchAndStoreAcquire(T *newValue)

   923 

   924     Atomic fetch-and-store.

   925 

   926     Reads the current value of this QAtomicPointer and then assigns it the

   927     \a newValue, returning the original value.

   928 

   929     This function uses \e acquire \l {QAtomicPointer#Memory

   930     ordering}{memory ordering} semantics, which ensures that memory

   931     access following the atomic operation (in program order) may not

   932     be re-ordered before the atomic operation.

   933 */

   934 

   935 /*! \fn T *QAtomicPointer::fetchAndStoreRelease(T *newValue)

   936 

   937     Atomic fetch-and-store.

   938 

   939     Reads the current value of this QAtomicPointer and then assigns it the

   940     \a newValue, returning the original value.

   941 

   942     This function uses \e release \l {QAtomicPointer#Memory

   943     ordering}{memory ordering} semantics, which ensures that memory

   944     access before the atomic operation (in program order) may not be

   945     re-ordered after the atomic operation.

   946 */

   947 

   948 /*! \fn T *QAtomicPointer::fetchAndStoreOrdered(T *newValue)

   949 

   950     Atomic fetch-and-store.

   951 

   952     Reads the current value of this QAtomicPointer and then assigns it the

   953     \a newValue, returning the original value.

   954 

   955     This function uses \e ordered \l {QAtomicPointer#Memory

   956     ordering}{memory ordering} semantics, which ensures that memory

   957     access before and after the atomic operation (in program order)

   958     may not be re-ordered.

   959 */

   960 

   961 /*! \fn bool QAtomicPointer::isFetchAndAddNative()

   962 

   963     Returns true if fetch-and-add is implemented using atomic

   964     processor instructions, false otherwise.

   965 */

   966 

   967 /*! \fn bool QAtomicPointer::isFetchAndAddWaitFree()

   968 

   969     Returns true if atomic fetch-and-add is wait-free, false

   970     otherwise.

   971 */

   972 

   973 /*! \fn T *QAtomicPointer::fetchAndAddRelaxed(qptrdiff valueToAdd)

   974 

   975     Atomic fetch-and-add.

   976 

   977     Reads the current value of this QAtomicPointer and then adds

   978     \a valueToAdd to the current value, returning the original value.

   979 

   980     This function uses \e relaxed \l {QAtomicPointer#Memory

   981     ordering}{memory ordering} semantics, leaving the compiler and

   982     processor to freely reorder memory accesses.

   983 */

   984 

   985 /*! \fn T *QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

   986 

   987     Atomic fetch-and-add.

   988 

   989     Reads the current value of this QAtomicPointer and then adds

   990     \a valueToAdd to the current value, returning the original value.

   991 

   992     This function uses \e acquire \l {QAtomicPointer#Memory

   993     ordering}{memory ordering} semantics, which ensures that memory

   994     access following the atomic operation (in program order) may not

   995     be re-ordered before the atomic operation.

   996 */

   997 

   998 /*! \fn T *QAtomicPointer::fetchAndAddRelease(qptrdiff valueToAdd)

   999 

  1000     Atomic fetch-and-add.

  1001 

  1002     Reads the current value of this QAtomicPointer and then adds

  1003     \a valueToAdd to the current value, returning the original value.

  1004 

  1005     This function uses \e release \l {QAtomicPointer#Memory

  1006     ordering}{memory ordering} semantics, which ensures that memory

  1007     access before the atomic operation (in program order) may not be

  1008     re-ordered after the atomic operation.

  1009 */

  1010 

  1011 /*! \fn T *QAtomicPointer::fetchAndAddOrdered(qptrdiff valueToAdd)

  1012 

  1013     Atomic fetch-and-add.

  1014 

  1015     Reads the current value of this QAtomicPointer and then adds

  1016     \a valueToAdd to the current value, returning the original value.

  1017 

  1018     This function uses \e ordered \l {QAtomicPointer#Memory

  1019     ordering}{memory ordering} semantics, which ensures that memory

  1020     access before and after the atomic operation (in program order)

  1021     may not be re-ordered.

  1022 */

  1023 

  1024 /*!

  1025     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE

  1026     \relates QAtomicPointer

  1027 

  1028     This macro is defined if and only if your processor supports

  1029     atomic test-and-set on pointers.

  1030 */

  1031 

  1032 /*!

  1033     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE

  1034     \relates QAtomicPointer

  1035 

  1036     This macro is defined when only certain generations of the

  1037     processor support atomic test-and-set on pointers. Use the

  1038     QAtomicPointer::isTestAndSetNative() function to check what your

  1039     processor supports.

  1040 */

  1041 

  1042 /*!

  1043     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE

  1044     \relates QAtomicPointer

  1045 

  1046     This macro is defined when the hardware does not support atomic

  1047     test-and-set on pointers.

  1048 */

  1049 

  1050 /*!

  1051     \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

  1052     \relates QAtomicPointer

  1053 

  1054     This macro is defined together with

  1055     Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that

  1056     the atomic test-and-set on pointers is wait-free.

  1057 */

  1058 

  1059 /*!

  1060     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE

  1061     \relates QAtomicPointer

  1062 

  1063     This macro is defined if and only if your processor supports

  1064     atomic fetch-and-store on pointers.

  1065 */

  1066 

  1067 /*!

  1068     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

  1069     \relates QAtomicPointer

  1070 

  1071     This macro is defined when only certain generations of the

  1072     processor support atomic fetch-and-store on pointers. Use the

  1073     QAtomicPointer::isFetchAndStoreNative() function to check what

  1074     your processor supports.

  1075 */

  1076 

  1077 /*!

  1078     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE

  1079     \relates QAtomicPointer

  1080 

  1081     This macro is defined when the hardware does not support atomic

  1082     fetch-and-store on pointers.

  1083 */

  1084 

  1085 /*!

  1086     \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE

  1087     \relates QAtomicPointer

  1088 

  1089     This macro is defined together with

  1090     Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that

  1091     the atomic fetch-and-store on pointers is wait-free.

  1092 */

  1093 

  1094 /*!

  1095     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE

  1096     \relates QAtomicPointer

  1097 

  1098     This macro is defined if and only if your processor supports

  1099     atomic fetch-and-add on pointers.

  1100 */

  1101 

  1102 /*!

  1103     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

  1104     \relates QAtomicPointer

  1105 

  1106     This macro is defined when only certain generations of the

  1107     processor support atomic fetch-and-add on pointers. Use the

  1108     QAtomicPointer::isFetchAndAddNative() function to check what your

  1109     processor supports.

  1110 */

  1111 

  1112 /*!

  1113     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE

  1114     \relates QAtomicPointer

  1115 

  1116     This macro is defined when the hardware does not support atomic

  1117     fetch-and-add on pointers.

  1118 */

  1119 

  1120 /*!

  1121     \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

  1122     \relates QAtomicPointer

  1123 

  1124     This macro is defined together with

  1125     Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that

  1126     the atomic fetch-and-add on pointers is wait-free.

  1127 */