src/corelib/concurrent/qtconcurrentthreadengine.h

   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 #ifndef QTCONCURRENT_THREADENGINE_H
  43 #define QTCONCURRENT_THREADENGINE_H
  44
  45 #include <QtCore/qglobal.h>
  46
  47 #ifndef QT_NO_CONCURRENT
  48
  49 #include <QtCore/qthreadpool.h>
  50 #include <QtCore/qfuture.h>
  51 #include <QtCore/qdebug.h>
  52 #include <QtCore/qtconcurrentexception.h>
  53 #include <QtCore/qwaitcondition.h>
  54 #include <QtCore/qatomic.h>
  55 #include <QtCore/qsemaphore.h>
  56
  57 QT_BEGIN_HEADER
  58 QT_BEGIN_NAMESPACE
  59
  60 QT_MODULE(Core)
  61
  62 #ifndef qdoc
  63
  64 namespace QtConcurrent {
  65
  66 // The ThreadEngineBarrier counts worker threads, and allows one
  67 // thread to wait for all others to finish. Tested for its use in
  68 // QtConcurrent, requires more testing for use as a general class.
  69 class ThreadEngineBarrier
  70 {
  71 private:
  72     // The thread count is maintained as an integer in the count atomic
  73     // variable. The count can be either positive or negative - a negative
  74     // count signals that a thread is waiting on the barrier.
  75
  76     // BC note: inlined code from Qt < 4.6 will expect to find the QMutex
  77     // and QAtomicInt here. ### Qt 5: remove.
  78     QMutex mutex;
  79     QAtomicInt count;
  80
  81     QSemaphore semaphore;
  82 public:
  83     ThreadEngineBarrier();
  84     void acquire();
  85     int release();
  86     void wait();
  87     int currentCount();
  88     bool releaseUnlessLast();
  89 };
  90
  91 enum ThreadFunctionResult { ThrottleThread, ThreadFinished };
  92
  93 // The ThreadEngine controls the threads used in the computation.
  94 // Can be run in three modes: single threaded, multi-threaded blocking
  95 // and multi-threaded asynchronous.
  96 // The code for the single threaded mode is
  97 class Q_CORE_EXPORT ThreadEngineBase: public QRunnable
  98 {
  99 public:
 100     // Public API:
 101     ThreadEngineBase();
 102     virtual ~ThreadEngineBase();
 103     void startSingleThreaded();
 104     void startBlocking();
 105     void startThread();
 106     bool isCanceled();
 107     void waitForResume();
 108     bool isProgressReportingEnabled();
 109     void setProgressValue(int progress);
 110     void setProgressRange(int minimum, int maximum);
 111     void acquireBarrierSemaphore();
 112
 113 protected: // The user overrides these:
 114     virtual void start() {}
 115     virtual void finish() {}
 116     virtual ThreadFunctionResult threadFunction() { return ThreadFinished; }
 117     virtual bool shouldStartThread() { return futureInterface ? !futureInterface->isPaused() : true; }
 118     virtual bool shouldThrottleThread() { return futureInterface ? futureInterface->isPaused() : false; }
 119 private:
 120     bool startThreadInternal();
 121     void startThreads();
 122     void threadExit();
 123     bool threadThrottleExit();
 124     void run();
 125     virtual void asynchronousFinish() = 0;
 126 #ifndef QT_NO_EXCEPTIONS
 127     void handleException(const QtConcurrent::Exception &exception);
 128 #endif
 129 protected:
 130     QFutureInterfaceBase *futureInterface;
 131     QThreadPool *threadPool;
 132     ThreadEngineBarrier barrier;
 133     QtConcurrent::internal::ExceptionStore exceptionStore;
 134 };
 135
 136
 137 template <typename T>
 138 class ThreadEngine : public virtual ThreadEngineBase
 139 {
 140 public:
 141     typedef T ResultType;
 142
 143     virtual T *result() { return 0; }
 144
 145     QFutureInterface<T> *futureInterfaceTyped()
 146     {
 147         return static_cast<QFutureInterface<T> *>(futureInterface);
 148     }
 149
 150     // Runs the user algorithm using a single thread.
 151     T *startSingleThreaded()
 152     {
 153         ThreadEngineBase::startSingleThreaded();
 154         return result();
 155     }
 156
 157     // Runs the user algorithm using multiple threads.
 158     // This function blocks until the algorithm is finished,
 159     // and then returns the result.
 160     T *startBlocking()
 161     {
 162         ThreadEngineBase::startBlocking();
 163         return result();
 164     }
 165
 166     // Runs the user algorithm using multiple threads.
 167     // Does not block, returns a future.
 168     QFuture<T> startAsynchronously()
 169     {
 170         futureInterface = new QFutureInterface<T>();
 171
 172         // reportStart() must be called before starting threads, otherwise the
 173         // user algorithm might finish while reportStart() is running, which
 174         // is very bad.
 175         futureInterface->reportStarted();
 176         QFuture<T> future = QFuture<T>(futureInterfaceTyped());
 177         start();
 178
 179         acquireBarrierSemaphore();
 180         threadPool->start(this);
 181         return future;
 182     }
 183
 184     void asynchronousFinish()
 185     {
 186         finish();
 187         futureInterfaceTyped()->reportFinished(result());
 188         delete futureInterfaceTyped();
 189         delete this;
 190     }
 191
 192
 193     void reportResult(const T *_result, int index = -1)
 194     {
 195         if (futureInterface)
 196             futureInterfaceTyped()->reportResult(_result, index);
 197     }
 198
 199     void reportResults(const QVector<T> &_result, int index = -1, int count = -1)
 200     {
 201         if (futureInterface)
 202             futureInterfaceTyped()->reportResults(_result, index, count);
 203     }
 204 };
 205
 206 // The ThreadEngineStarter class ecapsulates the return type
 207 // from the thread engine.
 208 // Depending on how the it is used, it will run
 209 // the engine in either blocking mode or asynchronous mode.
 210 template <typename T>
 211 class ThreadEngineStarterBase
 212 {
 213 public:
 214     ThreadEngineStarterBase(ThreadEngine<T> *_threadEngine)
 215     : threadEngine(_threadEngine) { }
 216
 217     inline ThreadEngineStarterBase(const ThreadEngineStarterBase &other)
 218     : threadEngine(other.threadEngine) { }
 219
 220     QFuture<T> startAsynchronously()
 221     {
 222         return threadEngine->startAsynchronously();
 223     }
 224
 225     operator QFuture<T>()
 226     {
 227         return startAsynchronously();
 228     }
 229
 230 protected:
 231     ThreadEngine<T> *threadEngine;
 232 };
 233
 234
 235 // We need to factor out the code that dereferences the T pointer,
 236 // with a specialization where T is void. (code that dereferences a void *
 237 // won't compile)
 238 template <typename T>
 239 class ThreadEngineStarter : public ThreadEngineStarterBase<T>
 240 {
 241     typedef ThreadEngineStarterBase<T> Base;
 242     typedef ThreadEngine<T> TypedThreadEngine;
 243 public:
 244     ThreadEngineStarter(TypedThreadEngine *eng)
 245         : Base(eng) { }
 246
 247     T startBlocking()
 248     {
 249         T t = *this->threadEngine->startBlocking();
 250         delete this->threadEngine;
 251         return t;
 252     }
 253 };
 254
 255 // Full template specialization where T is void.
 256 template <>
 257 class ThreadEngineStarter<void> : public ThreadEngineStarterBase<void>
 258 {
 259 public:
 260     ThreadEngineStarter<void>(ThreadEngine<void> *_threadEngine)
 261     :ThreadEngineStarterBase<void>(_threadEngine) {}
 262
 263     void startBlocking()
 264     {
 265         this->threadEngine->startBlocking();
 266         delete this->threadEngine;
 267     }
 268 };
 269
 270 template <typename ThreadEngine>
 271 inline ThreadEngineStarter<typename ThreadEngine::ResultType> startThreadEngine(ThreadEngine *threadEngine)
 272 {
 273     return ThreadEngineStarter<typename ThreadEngine::ResultType>(threadEngine);
 274 }
 275
 276 } // namespace QtConcurrent
 277
 278 #endif //qdoc
 279
 280 QT_END_NAMESPACE
 281 QT_END_HEADER
 282
 283 #endif // QT_NO_CONCURRENT
 284
 285 #endif