src/corelib/thread/qmutexpool.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 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