src/corelib/concurrent/qfuturewatcher.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 "qfuturewatcher.h"
  43
  44 #ifndef QT_NO_QFUTURE
  45
  46 #include <QtCore/qcoreevent.h>
  47 #include <QtCore/qcoreapplication.h>
  48 #include <QtCore/qthread.h>
  49
  50 #include "qfuturewatcher_p.h"
  51
  52 QT_BEGIN_NAMESPACE
  53
  54 /*! \class QFutureWatcher
  55     \reentrant
  56     \since 4.4
  57
  58     \ingroup thread
  59
  60     \brief The QFutureWatcher class allows monitoring a QFuture using signals
  61     and slots.
  62
  63     QFutureWatcher provides information and notifications about a QFuture. Use
  64     the setFuture() function to start watching a particular QFuture. The
  65     future() function returns the future set with setFuture().
  66
  67     For convenience, several of QFuture's functions are also available in
  68     QFutureWatcher: progressValue(), progressMinimum(), progressMaximum(),
  69     progressText(), isStarted(), isFinished(), isRunning(), isCanceled(),
  70     isPaused(), waitForFinished(), result(), and resultAt(). The cancel(),
  71     setPaused(), pause(), resume(), and togglePaused() functions are slots in
  72     QFutureWatcher.
  73
  74     Status changes are reported via the started(), finished(), canceled(),
  75     paused(), resumed(), resultReadyAt(), and resultsReadyAt() signals.
  76     Progress information is provided from the progressRangeChanged(),
  77     void progressValueChanged(), and progressTextChanged() signals.
  78
  79     Throttling control is provided by the setPendingResultsLimit() function.
  80     When the number of pending resultReadyAt() or resultsReadyAt() signals
  81     exceeds the limit, the computation represented by the future will be
  82     throttled automatically. The computation will resume once the number of
  83     pending signals drops below the limit.
  84
  85     Example: Starting a computation and getting a slot callback when it's
  86     finished:
  87
  88     \snippet doc/src/snippets/code/src_corelib_concurrent_qfuturewatcher.cpp 0
  89
  90     Be aware that not all asynchronous computations can be canceled or paused.
  91     For example, the future returned by QtConcurrent::run() cannot be
  92     canceled; but the future returned by QtConcurrent::mappedReduced() can.
  93
  94     QFutureWatcher<void> is specialized to not contain any of the result
  95     fetching functions. Any QFuture<T> can be watched by a
  96     QFutureWatcher<void> as well. This is useful if only status or progress
  97     information is needed; not the actual result data.
  98
  99     \sa QFuture, {Concurrent Programming}{Qt Concurrent}
 100 */
 101
 102 /*! \fn QFutureWatcher::QFutureWatcher(QObject *parent)
 103
 104     Constructs a new QFutureWatcher with the given \a parent.
 105 */
 106 QFutureWatcherBase::QFutureWatcherBase(QObject *parent)
 107     :QObject(*new QFutureWatcherBasePrivate, parent)
 108 { }
 109
 110 /*! \fn QFutureWatcher::~QFutureWatcher()
 111
 112     Destroys the QFutureWatcher.
 113 */
 114
 115 /*! \fn void QFutureWatcher::cancel()
 116
 117     Cancels the asynchronous computation represented by the future(). Note that
 118     the cancelation is asynchronous. Use waitForFinished() after calling
 119     cancel() when you need synchronous cancelation.
 120
 121     Currently available results may still be accessed on a canceled QFuture,
 122     but new results will \e not become available after calling this function.
 123     Also, this QFutureWatcher will not deliver progress and result ready
 124     signals once canceled. This includes the progressValueChanged(),
 125     progressRangeChanged(), progressTextChanged(), resultReadyAt(), and
 126     resultsReadyAt() signals.
 127
 128     Be aware that not all asynchronous computations can be canceled. For
 129     example, the QFuture returned by QtConcurrent::run() cannot be canceled;
 130     but the QFuture returned by QtConcurrent::mappedReduced() can.
 131 */
 132 void QFutureWatcherBase::cancel()
 133 {
 134     futureInterface().cancel();
 135 }
 136
 137 /*! \fn void QFutureWatcher::setPaused(bool paused)
 138
 139     If \a paused is true, this function pauses the asynchronous computation
 140     represented by the future(). If the computation is already paused, this
 141     function does nothing. This QFutureWatcher will stop delivering progress
 142     and result ready signals while the future is paused. Signal delivery will
 143     continue once the computation is resumed.
 144
 145     If \a paused is false, this function resumes the asynchronous computation.
 146     If the computation was not previously paused, this function does nothing.
 147
 148     Be aware that not all computations can be paused. For example, the
 149     QFuture returned by QtConcurrent::run() cannot be paused; but the QFuture
 150     returned by QtConcurrent::mappedReduced() can.
 151
 152     \sa pause(), resume(), togglePaused()
 153 */
 154 void QFutureWatcherBase::setPaused(bool paused)
 155 {
 156     futureInterface().setPaused(paused);
 157 }
 158
 159 /*! \fn void QFutureWatcher::pause()
 160
 161     Pauses the asynchronous computation represented by the future(). This is a
 162     convenience method that simply calls setPaused(true).
 163
 164     \sa resume()
 165 */
 166 void QFutureWatcherBase::pause()
 167 {
 168     futureInterface().setPaused(true);
 169 }
 170
 171 /*! \fn void QFutureWatcher::resume()
 172
 173     Resumes the asynchronous computation represented by the future(). This is
 174     a convenience method that simply calls setPaused(false).
 175
 176     \sa pause()
 177 */
 178 void QFutureWatcherBase::resume()
 179 {
 180     futureInterface().setPaused(false);
 181 }
 182
 183 /*! \fn void QFutureWatcher::togglePaused()
 184
 185     Toggles the paused state of the asynchronous computation. In other words,
 186     if the computation is currently paused, calling this function resumes it;
 187     if the computation is running, it becomes paused. This is a convenience
 188     method for calling setPaused(!isPaused()).
 189
 190     \sa setPaused(), pause(), resume()
 191 */
 192 void QFutureWatcherBase::togglePaused()
 193 {
 194     futureInterface().togglePaused();
 195 }
 196
 197 /*! \fn int QFutureWatcher::progressValue() const
 198
 199     Returns the current progress value, which is between the progressMinimum()
 200     and progressMaximum().
 201
 202     \sa progressMinimum(), progressMaximum()
 203 */
 204 int QFutureWatcherBase::progressValue() const
 205 {
 206     return futureInterface().progressValue();
 207 }
 208
 209 /*! \fn int QFutureWatcher::progressMinimum() const
 210
 211     Returns the minimum progressValue().
 212
 213     \sa progressValue(), progressMaximum()
 214 */
 215 int QFutureWatcherBase::progressMinimum() const
 216 {
 217     return futureInterface().progressMinimum();
 218 }
 219
 220 /*! \fn int QFutureWatcher::progressMaximum() const
 221
 222     Returns the maximum progressValue().
 223
 224     \sa progressValue(), progressMinimum()
 225 */
 226 int QFutureWatcherBase::progressMaximum() const
 227 {
 228     return futureInterface().progressMaximum();
 229 }
 230
 231 /*! \fn QString QFutureWatcher::progressText() const
 232
 233     Returns the (optional) textual representation of the progress as reported
 234     by the asynchronous computation.
 235
 236     Be aware that not all computations provide a textual representation of the
 237     progress, and as such, this function may return an empty string.
 238 */
 239 QString QFutureWatcherBase::progressText() const
 240 {
 241     return futureInterface().progressText();
 242 }
 243
 244 /*! \fn bool QFutureWatcher::isStarted() const
 245
 246     Returns true if the asynchronous computation represented by the future()
 247     has been started; otherwise returns false.
 248 */
 249 bool QFutureWatcherBase::isStarted() const
 250 {
 251     return futureInterface().queryState(QFutureInterfaceBase::Started);
 252 }
 253
 254 /*! \fn bool QFutureWatcher::isFinished() const
 255
 256     Returns true if the asynchronous computation represented by the future()
 257     has finished; otherwise returns false.
 258 */
 259 bool QFutureWatcherBase::isFinished() const
 260 {
 261     Q_D(const QFutureWatcherBase);
 262     return d->finished;
 263 }
 264
 265 /*! \fn bool QFutureWatcher::isRunning() const
 266
 267     Returns true if the asynchronous computation represented by the future()
 268     is currently running; otherwise returns false.
 269 */
 270 bool QFutureWatcherBase::isRunning() const
 271 {
 272     return futureInterface().queryState(QFutureInterfaceBase::Running);
 273 }
 274
 275 /*! \fn bool QFutureWatcher::isCanceled() const
 276
 277     Returns true if the asynchronous computation has been canceled with the
 278     cancel() function; otherwise returns false.
 279
 280     Be aware that the computation may still be running even though this
 281     function returns true. See cancel() for more details.
 282 */
 283 bool QFutureWatcherBase::isCanceled() const
 284 {
 285     return futureInterface().queryState(QFutureInterfaceBase::Canceled);
 286 }
 287
 288 /*! \fn bool QFutureWatcher::isPaused() const
 289
 290     Returns true if the asynchronous computation has been paused with the
 291     pause() function; otherwise returns false.
 292
 293     Be aware that the computation may still be running even though this
 294     function returns true. See setPaused() for more details.
 295
 296     \sa setPaused(), togglePaused()
 297 */
 298 bool QFutureWatcherBase::isPaused() const
 299 {
 300     return futureInterface().queryState(QFutureInterfaceBase::Paused);
 301 }
 302
 303 /*! \fn void QFutureWatcher::waitForFinished()
 304
 305     Waits for the asynchronous computation to finish (including cancel()ed
 306     computations).
 307 */
 308 void QFutureWatcherBase::waitForFinished()
 309 {
 310     futureInterface().waitForFinished();
 311 }
 312
 313 /*! \fn void QFutureWatcher::setPendingResultsLimit(int limit)
 314
 315     The setPendingResultsLimit() provides throttling control. When the number
 316     of pending resultReadyAt() or resultsReadyAt() signals exceeds the
 317     \a limit, the computation represented by the future will be throttled
 318     automatically. The computation will resume once the number of pending
 319     signals drops below the \a limit.
 320 */
 321
 322 bool QFutureWatcherBase::event(QEvent *event)
 323 {
 324     Q_D(QFutureWatcherBase);
 325     if (event->type() == QEvent::FutureCallOut) {
 326         QFutureCallOutEvent *callOutEvent = static_cast<QFutureCallOutEvent *>(event);
 327
 328         if (futureInterface().isPaused()) {
 329             d->pendingCallOutEvents.append(callOutEvent->clone());
 330             return true;
 331         }
 332
 333         if (callOutEvent->callOutType == QFutureCallOutEvent::Resumed
 334             && !d->pendingCallOutEvents.isEmpty()) {
 335             // send the resume
 336             d->sendCallOutEvent(callOutEvent);
 337
 338             // next send all pending call outs
 339             for (int i = 0; i < d->pendingCallOutEvents.count(); ++i)
 340                 d->sendCallOutEvent(d->pendingCallOutEvents.at(i));
 341             qDeleteAll(d->pendingCallOutEvents);
 342             d->pendingCallOutEvents.clear();
 343         } else {
 344             d->sendCallOutEvent(callOutEvent);
 345         }
 346         return true;
 347     }
 348     return QObject::event(event);
 349 }
 350
 351 void QFutureWatcherBase::setPendingResultsLimit(int limit)
 352 {
 353     Q_D(QFutureWatcherBase);
 354     d->maximumPendingResultsReady = limit;
 355 }
 356
 357 void QFutureWatcherBase::connectNotify(const char * signal)
 358 {
 359     Q_D(QFutureWatcherBase);
 360     if (qstrcmp(signal, SIGNAL(resultReadyAt(int))) == 0)
 361         d->resultAtConnected.ref();
 362 }
 363
 364 void QFutureWatcherBase::disconnectNotify(const char * signal)
 365 {
 366     Q_D(QFutureWatcherBase);
 367     if (qstrcmp(signal, SIGNAL(resultReadyAt(int))) == 0)
 368         d->resultAtConnected.deref();
 369 }
 370
 371 /*!
 372     \internal
 373 */
 374 QFutureWatcherBasePrivate::QFutureWatcherBasePrivate()
 375     : maximumPendingResultsReady(QThread::idealThreadCount() * 2),
 376       resultAtConnected(0)
 377 { }
 378
 379 /*!
 380     \internal
 381 */
 382 void QFutureWatcherBase::connectOutputInterface()
 383 {
 384     futureInterface().d->connectOutputInterface(d_func());
 385 }
 386
 387 /*!
 388     \internal
 389 */
 390 void QFutureWatcherBase::disconnectOutputInterface(bool pendingAssignment)
 391 {
 392     if (pendingAssignment) {
 393         Q_D(QFutureWatcherBase);
 394         d->pendingResultsReady = 0;
 395         qDeleteAll(d->pendingCallOutEvents);
 396         d->pendingCallOutEvents.clear();
 397         d->finished = false;
 398     }
 399
 400     futureInterface().d->disconnectOutputInterface(d_func());
 401 }
 402
 403 void QFutureWatcherBasePrivate::postCallOutEvent(const QFutureCallOutEvent &callOutEvent)
 404 {
 405     Q_Q(QFutureWatcherBase);
 406
 407     if (callOutEvent.callOutType == QFutureCallOutEvent::ResultsReady) {
 408         if (pendingResultsReady.fetchAndAddRelaxed(1) >= maximumPendingResultsReady)
 409             q->futureInterface().d->internal_setThrottled(true);
 410     }
 411
 412     QCoreApplication::postEvent(q, callOutEvent.clone());
 413 }
 414
 415 void QFutureWatcherBasePrivate::callOutInterfaceDisconnected()
 416 {
 417     QCoreApplication::removePostedEvents(q_func(), QEvent::FutureCallOut);
 418 }
 419
 420 void QFutureWatcherBasePrivate::sendCallOutEvent(QFutureCallOutEvent *event)
 421 {
 422     Q_Q(QFutureWatcherBase);
 423
 424     switch (event->callOutType) {
 425         case QFutureCallOutEvent::Started:
 426             emit q->started();
 427         break;
 428         case QFutureCallOutEvent::Finished:
 429             finished = true;
 430             emit q->finished();
 431         break;
 432         case QFutureCallOutEvent::Canceled:
 433             pendingResultsReady = 0;
 434             emit q->canceled();
 435         break;
 436         case QFutureCallOutEvent::Paused:
 437             if (q->futureInterface().isCanceled())
 438                 break;
 439             emit q->paused();
 440         break;
 441         case QFutureCallOutEvent::Resumed:
 442             if (q->futureInterface().isCanceled())
 443                 break;
 444             emit q->resumed();
 445         break;
 446         case QFutureCallOutEvent::ResultsReady: {
 447             if (q->futureInterface().isCanceled())
 448                 break;
 449
 450             if (pendingResultsReady.fetchAndAddRelaxed(-1) <= maximumPendingResultsReady)
 451                 q->futureInterface().setThrottled(false);
 452
 453             const int beginIndex = event->index1;
 454             const int endIndex = event->index2;
 455
 456             emit q->resultsReadyAt(beginIndex, endIndex);
 457
 458             if (int(resultAtConnected) <= 0)
 459                 break;
 460
 461             for (int i = beginIndex; i < endIndex; ++i)
 462                 emit q->resultReadyAt(i);
 463
 464         } break;
 465         case QFutureCallOutEvent::Progress:
 466             if (q->futureInterface().isCanceled())
 467                 break;
 468
 469             emit q->progressValueChanged(event->index1);
 470             if (!event->text.isNull()) // ###
 471                 q->progressTextChanged(event->text);
 472         break;
 473         case QFutureCallOutEvent::ProgressRange:
 474             emit q->progressRangeChanged(event->index1, event->index2);
 475         break;
 476         default: break;
 477     }
 478 }
 479
 480
 481 /*! \fn const T &QFutureWatcher::result() const
 482
 483     Returns the first result in the future(). If the result is not immediately
 484     available, this function will block and wait for the result to become
 485     available. This is a convenience method for calling resultAt(0).
 486
 487     \sa resultAt()
 488 */
 489
 490 /*! \fn const T &QFutureWatcher::resultAt(int index) const
 491
 492     Returns the result at \a index in the future(). If the result is not
 493     immediately available, this function will block and wait for the result to
 494     become available.
 495
 496     \sa result()
 497 */
 498
 499 /*! \fn void QFutureWatcher::setFuture(const QFuture<T> &future)
 500
 501     Starts watching the given \a future.
 502 */
 503
 504 /*! \fn QFuture<T> QFutureWatcher::future() const
 505
 506     Returns the watched future.
 507 */
 508
 509 /*! \fn void QFutureWatcher::started()
 510
 511     This signal is emitted when this QFutureWatcher starts watching the future
 512     set with setFuture().
 513 */
 514
 515 /*!
 516     \fn void QFutureWatcher::finished()
 517     This signal is emitted when the watched future finishes.
 518 */
 519
 520 /*!
 521     \fn void QFutureWatcher::canceled()
 522     This signal is emitted if the watched future is canceled.
 523 */
 524
 525 /*! \fn void QFutureWatcher::paused()
 526     This signal is emitted when the watched future is paused.
 527 */
 528
 529 /*! \fn void QFutureWatcher::resumed()
 530     This signal is emitted when the watched future is resumed.
 531 */
 532
 533 /*!
 534     \fn void QFutureWatcher::progressRangeChanged(int minimum, int maximum)
 535
 536     The progress range for the watched future has changed to \a minimum and
 537     \a maximum
 538 */
 539
 540 /*!
 541     \fn void QFutureWatcher::progressValueChanged(int progressValue)
 542
 543     This signal is emitted when the watched future reports progress,
 544     \a progressValue gives the current progress. In order to avoid overloading
 545     the GUI event loop, QFutureWatcher limits the progress signal emission
 546     rate. This means that listeners connected to this slot might not get all
 547     progress reports the future makes. The last progress update (where
 548     \a progressValue equals the maximum value) will always be delivered.
 549 */
 550
 551 /*! \fn void QFutureWatcher::progressTextChanged(const QString &progressText)
 552
 553     This signal is emitted when the watched future reports textual progress
 554     information, \a progressText.
 555 */
 556
 557 /*!
 558     \fn void QFutureWatcher::resultReadyAt(int index)
 559
 560     This signal is emitted when the watched future reports a ready result at
 561     \a index. If the future reports multiple results, the index will indicate
 562     which one it is. Results can be reported out-of-order. To get the result,
 563     call future().result(index);
 564 */
 565
 566 /*!
 567     \fn void QFutureWatcher::resultsReadyAt(int beginIndex, int endIndex);
 568
 569     This signal is emitted when the watched future reports ready results.
 570     The results are indexed from \a beginIndex to \a endIndex.
 571
 572 */
 573
 574 QT_END_NAMESPACE
 575
 576 #endif // QT_NO_CONCURRENT