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 #include "qatomic.h"

    43 #include "qmutexpool_p.h"

    44 

    45 #ifndef QT_NO_THREAD

    46 

    47 QT_BEGIN_NAMESPACE

    48 

    49 // qt_global_mutexpool is here for backwards compatability only,

    50 // use QMutexpool::instance() in new clode.

    51 Q_CORE_EXPORT QMutexPool *qt_global_mutexpool = 0;

    52 Q_GLOBAL_STATIC_WITH_ARGS(QMutexPool, globalMutexPool, (QMutex::Recursive))

    53 

    54 /*!

    55     \class QMutexPool

    56     \brief The QMutexPool class provides a pool of QMutex objects.

    57 

    58     \internal

    59 

    60     \ingroup thread

    61 

    62     QMutexPool is a convenience class that provides access to a fixed

    63     number of QMutex objects.

    64 

    65     Typical use of a QMutexPool is in situations where it is not

    66     possible or feasible to use one QMutex for every protected object.

    67     The mutex pool will return a mutex based on the address of the

    68     object that needs protection.

    69 

    70     For example, consider this simple class:

    71 

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

    73 

    74     Adding a QMutex member to the Number class does not make sense,

    75     because it is so small. However, in order to ensure that access to

    76     each Number is protected, you need to use a mutex. In this case, a

    77     QMutexPool would be ideal.

    78 

    79     Code to calculate the square of a number would then look something

    80     like this:

    81 

    82     \snippet doc/src/snippets/code/src_corelib_thread_qmutexpool.cpp 1

    83 

    84     This function will safely calculate the square of a number, since

    85     it uses a mutex from a QMutexPool. The mutex is locked and

    86     unlocked automatically by the QMutexLocker class. See the

    87     QMutexLocker documentation for more details.

    88 */

    89 

    90 /*!

    91     Constructs  a QMutexPool, reserving space for \a size QMutexes. All

    92     mutexes in the pool are created with \a recursionMode. By default,

    93     all mutexes are non-recursive.

    94 

    95     The QMutexes are created when needed, and deleted when the

    96     QMutexPool is destructed.

    97 */

    98 QMutexPool::QMutexPool(QMutex::RecursionMode recursionMode, int size)

    99     : mutexes(size), recursionMode(recursionMode)

   100 {

   101     for (int index = 0; index < mutexes.count(); ++index) {

   102         mutexes[index] = 0;

   103     }

   104 }

   105 

   106 /*!

   107     Destructs a QMutexPool. All QMutexes that were created by the pool

   108     are deleted.

   109 */

   110 QMutexPool::~QMutexPool()

   111 {

   112     for (int index = 0; index < mutexes.count(); ++index) {

   113         delete mutexes[index];

   114         mutexes[index] = 0;

   115     }

   116 }

   117 

   118 /*!

   119     Returns the global QMutexPool instance.

   120 */

   121 QMutexPool *QMutexPool::instance()

   122 {

   123     return globalMutexPool();

   124 }

   125 

   126 /*!

   127     Returns a QMutex from the pool. QMutexPool uses the value \a address

   128     to determine which mutex is returned from the pool.

   129 */

   130 QMutex *QMutexPool::get(const void *address)

   131 {

   132     Q_ASSERT_X(address != 0, "QMutexPool::get()", "'address' argument cannot be zero");

   133     int index = int((quintptr(address) >> (sizeof(address) >> 1)) % mutexes.count());

   134 

   135     if (!mutexes[index]) {

   136         // mutex not created, create one

   137         QMutex *newMutex = new QMutex(recursionMode);

   138         if (!mutexes[index].testAndSetOrdered(0, newMutex))

   139             delete newMutex;

   140     }

   141 

   142     return mutexes[index];

   143 }

   144 

   145 /*!

   146     Returns a QMutex from the global mutex pool.

   147 */

   148 QMutex *QMutexPool::globalInstanceGet(const void *address)

   149 {

   150     QMutexPool * const globalInstance = globalMutexPool();

   151     if (globalInstance == 0)

   152         return 0;

   153     return globalInstance->get(address);

   154 }

   155 

   156 QT_END_NAMESPACE

   157 

   158 #endif // QT_NO_THREAD