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 /*! \class QFuture

    43     \threadsafe

    44     \brief The QFuture class represents the result of an asynchronous computation.

    45     \since 4.4

    46 

    47     \ingroup thread

    48 

    49     To start a computation, use one of the APIs in the

    50     \l {Concurrent Programming}{Qt Concurrent} framework.

    51 

    52     QFuture allows threads to be synchronized against one or more results

    53     which will be ready at a later point in time. The result can be of any type

    54     that has a default constructor and a copy constructor. If a result is not

    55     available at the time of calling the result(), resultAt(), or results()

    56     functions, QFuture will wait until the result becomes available. You can

    57     use the isResultReadyAt() function to determine if a result is ready or

    58     not. For QFuture objects that report more than one result, the

    59     resultCount() function returns the number of continuous results. This

    60     means that it is always safe to iterate through the results from 0 to 

    61     resultCount().

    62 

    63     QFuture provides a \l{Java-style iterators}{Java-style iterator}

    64     (QFutureIterator) and an \l{STL-style iterators}{STL-style iterator}

    65     (QFuture::const_iterator). Using these iterators is  another way to access

    66     results in the future.

    67 

    68     QFuture also offers ways to interact with a runnning computation. For

    69     instance, the computation can be canceled with the cancel() function. To

    70     pause the computation, use the setPaused() function or one of the pause(),

    71     resume(), or togglePaused() convenience functions. Be aware that not all

    72     asynchronous computations can be canceled or paused. For example, the

    73     future returned by QtConcurrent::run() cannot be canceled; but the

    74     future returned by QtConcurrent::mappedReduced() can.

    75 

    76     Progress information is provided by the progressValue(),

    77     progressMinimum(), progressMaximum(), and progressText() functions. The

    78     waitForFinished() function causes the calling thread to block and wait for

    79     the computation to finish, ensuring that all results are available.

    80 

    81     The state of the computation represented by a QFuture can be queried using

    82     the isCanceled(), isStarted(), isFinished(), isRunning(), or isPaused()

    83     functions.

    84 

    85     QFuture is a lightweight reference counted class that can be passed by

    86     value.

    87 

    88     QFuture<void> is specialized to not contain any of the result fetching

    89     functions. Any QFuture<T> can be assigned or copied into a QFuture<void>

    90     as well. This is useful if only status or progress information is needed

    91     - not the actual result data.

    92 

    93     To interact with running tasks using signals and slots, use QFutureWatcher.

    94 

    95     \sa QFutureWatcher, {Concurrent Programming}{Qt Concurrent}

    96 */

    97 

    98 /*! \fn QFuture::QFuture()

    99 

   100     Constructs an empty future.

   101 */

   102 

   103 /*! \fn QFuture::QFuture(const QFuture &other)

   104 

   105     Constructs a copy of \a other.

   106 

   107     \sa operator=()

   108 */

   109 

   110 /*! \fn QFuture::QFuture(QFutureInterface<T> *resultHolder)

   111     \internal

   112 */

   113 

   114 /*! \fn QFuture::~QFuture()

   115 

   116     Destroys the future.

   117 

   118     Note that this neither waits nor cancels the asynchronous computation. Use

   119     waitForFinished() or QFutureSynchronizer when you need to ensure that the

   120     computation is completed before the future is destroyed.

   121 */

   122 

   123 /*! \fn QFuture &QFuture::operator=(const QFuture &other)

   124 

   125      Assigns \a other to this future and returns a reference to this future.

   126 */

   127 

   128 /*! \fn bool QFuture::operator==(const QFuture &other) const

   129 

   130     Returns true if \a other is a copy of this future; otherwise returns false.

   131 */

   132 

   133 /*! \fn bool QFuture::operator!=(const QFuture &other) const

   134 

   135     Returns true if \a other is \e not a copy of this future; otherwise returns

   136     false.

   137 */

   138 

   139 /*! \fn void QFuture::cancel()

   140 

   141     Cancels the asynchronous computation represented by this future. Note that

   142     the cancelation is asynchronous. Use waitForFinished() after calling

   143     cancel() when you need synchronous cancelation.

   144 

   145     Results currently available may still be accessed on a canceled future,

   146     but new results will \e not become available after calling this function.

   147     Any QFutureWatcher object that is watching this future will not deliver

   148     progress and result ready signals on a canceled future.

   149 

   150     Be aware that not all asynchronous computations can be canceled. For

   151     example, the future returned by QtConcurrent::run() cannot be canceled;

   152     but the future returned by QtConcurrent::mappedReduced() can.

   153 */

   154 

   155 /*! \fn bool QFuture::isCanceled() const

   156 

   157     Returns true if the asynchronous computation has been canceled with the

   158     cancel() function; otherwise returns false.

   159 

   160     Be aware that the computation may still be running even though this

   161     function returns true. See cancel() for more details.

   162 */

   163 

   164 /*! \fn void QFuture::setPaused(bool paused)

   165 

   166     If \a paused is true, this function pauses the asynchronous computation

   167     represented by the future. If the computation is  already paused, this

   168     function does nothing. Any QFutureWatcher object that is watching this

   169     future will stop delivering progress and result ready signals while the

   170     future is paused. Signal delivery will continue once the future is

   171     resumed.

   172 

   173     If \a paused is false, this function resumes the asynchronous computation.

   174     If the computation was not previously paused, this function does nothing.

   175 

   176     Be aware that not all computations can be paused. For example, the future

   177     returned by QtConcurrent::run() cannot be paused; but the future returned

   178     by QtConcurrent::mappedReduced() can.

   179 

   180     \sa pause(), resume(), togglePaused()

   181 */

   182 

   183 /*! \fn bool QFuture::isPaused() const

   184 

   185     Returns true if the asynchronous computation has been paused with the

   186     pause() function; otherwise returns false.

   187 

   188     Be aware that the computation may still be running even though this

   189     function returns true. See setPaused() for more details.

   190 

   191     \sa setPaused(), togglePaused()

   192 */

   193 

   194 /*! \fn void QFuture::pause()

   195 

   196     Pauses the asynchronous computation represented by this future. This is a

   197     convenience method that simply calls setPaused(true).

   198 

   199     \sa resume()

   200 */

   201 

   202 /*! \fn void QFuture::resume()

   203 

   204     Resumes the asynchronous computation represented by this future. This is a

   205     convenience method that simply calls setPaused(false).

   206 

   207     \sa pause()

   208 */

   209 

   210 /*! \fn void QFuture::togglePaused()

   211 

   212     Toggles the paused state of the asynchronous computation. In other words,

   213     if the computation is currently paused, calling this function resumes it;

   214     if the computation is running, it is paused. This is a convenience method

   215     for calling setPaused(!isPaused()).

   216 

   217     \sa setPaused(), pause(), resume()

   218 */

   219 

   220 /*! \fn bool QFuture::isStarted() const

   221 

   222     Returns true if the asynchronous computation represented by this future

   223     has been started; otherwise returns false.

   224 */

   225 

   226 /*! \fn bool QFuture::isFinished() const

   227 

   228     Returns true if the asynchronous computation represented by this future

   229     has finished; otherwise returns false.

   230 */

   231 

   232 /*! \fn bool QFuture::isRunning() const

   233 

   234     Returns true if the asynchronous computation represented by this future is

   235     currently running; otherwise returns false.

   236 */

   237 

   238 /*! \fn int QFuture::resultCount() const

   239 

   240     Returns the number of continuous results available in this future. The real

   241     number of results stored might be different from this value, due to gaps

   242     in the result set. It is always safe to iterate through the results from 0

   243     to resultCount().

   244     \sa result(), resultAt(), results()

   245 */

   246 

   247 /*! \fn int QFuture::progressValue() const

   248 

   249     Returns the current progress value, which is between the progressMinimum()

   250     and progressMaximum().

   251 

   252     \sa progressMinimum(), progressMaximum()

   253 */

   254 

   255 /*! \fn int QFuture::progressMinimum() const

   256 

   257     Returns the minimum progressValue().

   258 

   259     \sa progressValue(), progressMaximum()

   260 */

   261 

   262 /*! \fn int QFuture::progressMaximum() const

   263 

   264     Returns the maximum progressValue().

   265 

   266     \sa progressValue(), progressMinimum()

   267 */

   268 

   269 /*! \fn QString QFuture::progressText() const

   270 

   271     Returns the (optional) textual representation of the progress as reported

   272     by the asynchronous computation.

   273 

   274     Be aware that not all computations provide a textual representation of the

   275     progress, and as such, this function may return an empty string.

   276 */

   277 

   278 /*! \fn void QFuture::waitForFinished()

   279 

   280     Waits for the asynchronous computation to finish (including cancel()ed

   281     computations).

   282 */

   283 

   284 /*! \fn T QFuture::result() const

   285 

   286     Returns the first result in the future. If the result is not immediately

   287     available, this function will block and wait for the result to become

   288     available. This is a convenience method for calling resultAt(0).

   289 

   290     \sa resultAt(), results()

   291 */

   292 

   293 /*! \fn T QFuture::resultAt(int index) const

   294 

   295     Returns the result at \a index in the future. If the result is not

   296     immediately available, this function will block and wait for the result to

   297     become available.

   298 

   299     \sa result(), results(), resultCount()

   300 */

   301 

   302 /*! \fn bool QFuture::isResultReadyAt(int index) const

   303 

   304     Returns true if the result at \a index is immediately available; otherwise

   305     returns false.

   306 

   307     \sa resultAt(), resultCount()

   308 */

   309 

   310 /*! \fn QFuture::operator T() const

   311 

   312     Returns the first result in the future. If the result is not immediately

   313     available, this function will block and wait for the result to become

   314     available. This is a convenience method for calling result() or

   315     resultAt(0).

   316 

   317     \sa result(), resultAt(), results()

   318 */

   319 

   320 /*! \fn QList<T> QFuture::results() const

   321 

   322     Returns all results from the future. If the results are not immediately

   323     available, this function will block and wait for them to become available.

   324 

   325     \sa result(), resultAt(), resultCount()

   326 */

   327 

   328 /*! \fn QFuture::const_iterator QFuture::begin() const

   329 

   330     Returns a const \l{STL-style iterator} pointing to the first result in the

   331     future.

   332 

   333     \sa constBegin(), end()

   334 */

   335 

   336 /*! \fn QFuture::const_iterator QFuture::end() const

   337 

   338     Returns a const \l{STL-style iterator} pointing to the imaginary result

   339     after the last result in the future.

   340 

   341     \sa begin(), constEnd()

   342 */

   343 

   344 /*! \fn QFuture::const_iterator QFuture::constBegin() const

   345 

   346     Returns a const \l{STL-style iterator} pointing to the first result in the

   347     future.

   348 

   349     \sa begin(), constEnd()

   350 */

   351 

   352 /*! \fn QFuture::const_iterator QFuture::constEnd() const

   353 

   354     Returns a const \l{STL-style iterator} pointing to the imaginary result

   355     after the last result in the future.

   356 

   357     \sa constBegin(), end()

   358 */

   359 

   360 /*! \class QFuture::const_iterator

   361     \reentrant

   362     \since 4.4

   363 

   364     \brief The QFuture::const_iterator class provides an STL-style const

   365     iterator for QFuture.

   366 

   367     QFuture provides both \l{STL-style iterators} and \l{Java-style iterators}.

   368     The STL-style iterators are more low-level and more cumbersome to use; on

   369     the other hand, they are slightly faster and, for developers who already

   370     know STL, have the advantage of familiarity.

   371 

   372     The default QFuture::const_iterator constructor creates an uninitialized

   373     iterator. You must initialize it using a QFuture function like

   374     QFuture::constBegin() or QFuture::constEnd() before you start iterating.

   375     Here's a typical loop that prints all the results available in a future:

   376 

   377     \snippet doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp 0

   378 

   379     \sa QFutureIterator, QFuture

   380 */

   381 

   382 /*! \typedef QFuture::const_iterator::iterator_category

   383 

   384     Typedef for std::bidirectional_iterator_tag. Provided for STL compatibility.

   385 */

   386 

   387 /*! \typedef QFuture::const_iterator::difference_type

   388 

   389     Typedef for ptrdiff_t. Provided for STL compatibility.

   390 */

   391 

   392 /*! \typedef QFuture::const_iterator::value_type

   393 

   394     Typedef for T. Provided for STL compatibility.

   395 */

   396 

   397 /*! \typedef QFuture::const_iterator::pointer

   398 

   399     Typedef for const T *. Provided for STL compatibility.

   400 */

   401 

   402 /*! \typedef QFuture::const_iterator::reference

   403 

   404     Typedef for const T &. Provided for STL compatibility.

   405 */

   406 

   407 /*! \fn QFuture::const_iterator::const_iterator()

   408 

   409     Constructs an uninitialized iterator.

   410 

   411     Functions like operator*() and operator++() should not be called on an

   412     uninitialized iterartor. Use operator=() to assign a value to it before

   413     using it.

   414 

   415     \sa QFuture::constBegin() QFuture::constEnd()

   416 */

   417 

   418 /*! \fn QFuture::const_iterator::const_iterator(QFuture const * const future, int index)

   419     \internal

   420 */

   421 

   422 /*! \fn QFuture::const_iterator::const_iterator(const const_iterator &other)

   423 

   424     Constructs a copy of \a other.

   425 */

   426 

   427 /*! \fn QFuture::const_iterator &QFuture::const_iterator::operator=(const const_iterator &other)

   428 

   429     Assigns \a other to this iterator.

   430 */

   431 

   432 /*! \fn const T &QFuture::const_iterator::operator*() const

   433 

   434     Returns the current result.

   435 */

   436 

   437 /*! \fn const T *QFuture::const_iterator::operator->() const

   438 

   439     Returns a pointer to the current result.

   440 */

   441 

   442 /*! \fn bool QFuture::const_iterator::operator!=(const const_iterator &other) const

   443 

   444     Returns true if \a other points to a different result than this iterator;

   445     otherwise returns false.

   446 

   447     \sa operator==()

   448 */

   449 

   450 /*! \fn bool QFuture::const_iterator::operator==(const const_iterator &other) const

   451 

   452     Returns true if \a other points to the same result as this iterator;

   453     otherwise returns false.

   454 

   455     \sa operator!=()

   456 */

   457 

   458 /*! \fn QFuture::const_iterator &QFuture::const_iterator::operator++()

   459 

   460     The prefix ++ operator (\c{++it}) advances the iterator to the next result

   461     in the future and returns an iterator to the new current result.

   462 

   463     Calling this function on QFuture::constEnd() leads to undefined results.

   464 

   465     \sa operator--()

   466 */

   467 

   468 /*! \fn QFuture::const_iterator QFuture::const_iterator::operator++(int)

   469 

   470     \overload

   471 

   472     The postfix ++ operator (\c{it++}) advances the iterator to the next

   473     result in the future and returns an iterator to the previously current

   474     result.

   475 */

   476 

   477 /*! \fn QFuture::const_iterator &QFuture::const_iterator::operator--()

   478 

   479     The prefix -- operator (\c{--it}) makes the preceding result current and

   480     returns an iterator to the new current result.

   481 

   482     Calling this function on QFuture::constBegin() leads to undefined results.

   483 

   484     \sa operator++()

   485 */

   486 

   487 /*! \fn QFuture::const_iterator QFuture::const_iterator::operator--(int)

   488 

   489     \overload

   490 

   491     The postfix -- operator (\c{it--}) makes the preceding result current and

   492     returns an iterator to the previously current result.

   493 */

   494 

   495 /*! \fn QFuture::const_iterator &QFuture::const_iterator::operator+=(int j)

   496 

   497     Advances the iterator by \a j results. (If \a j is negative, the iterator

   498     goes backward.)

   499 

   500     \sa operator-=(), operator+()

   501 */

   502 

   503 /*! \fn QFuture::const_iterator &QFuture::const_iterator::operator-=(int j)

   504 

   505     Makes the iterator go back by \a j results. (If \a j is negative, the

   506     iterator goes forward.)

   507 

   508     \sa operator+=(), operator-()

   509 */

   510 

   511 /*! \fn QFuture::const_iterator QFuture::const_iterator::operator+(int j) const

   512 

   513     Returns an iterator to the results at \a j positions forward from this

   514     iterator. (If \a j is negative, the iterator goes backward.)

   515 

   516     \sa operator-(), operator+=()

   517 */

   518 

   519 /*! \fn QFuture::const_iterator QFuture::const_iterator::operator-(int j) const

   520 

   521     Returns an iterator to the result at \a j positions backward from this

   522     iterator. (If \a j is negative, the iterator goes forward.)

   523 

   524     \sa operator+(), operator-=()

   525 */

   526 

   527 /*! \typedef QFuture::ConstIterator

   528 

   529     Qt-style synonym for QFuture::const_iterator.

   530 */

   531 

   532 /*!

   533     \class QFutureIterator

   534     \reentrant

   535     \since 4.4

   536     \inmodule QtCore

   537 

   538     \brief The QFutureIterator class provides a Java-style const iterator for

   539     QFuture.

   540 

   541     QFuture has both \l{Java-style iterators} and \l{STL-style iterators}. The

   542     Java-style iterators are more high-level and easier to use than the

   543     STL-style iterators; on the other hand, they are slightly less efficient.

   544 

   545     An alternative to using iterators is to use index positions. Some QFuture

   546     member functions take an index as their first parameter, making it

   547     possible to access results without using iterators.

   548 

   549     QFutureIterator\<T\> allows you to iterate over a QFuture\<T\>. Note that

   550     there is no mutable iterator for QFuture (unlike the other Java-style

   551     iterators).

   552 

   553     The QFutureIterator constructor takes a QFuture as its argument. After

   554     construction, the iterator is located at the very beginning of the result

   555     list (i.e. before the first result). Here's how to iterate over all the

   556     results sequentially:

   557 

   558     \snippet doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp 1

   559 

   560     The next() function returns the next result (waiting for it to become

   561     available, if necessary) from the future and advances the iterator. Unlike

   562     STL-style iterators, Java-style iterators point \e between results rather

   563     than directly \e at results. The first call to next() advances the iterator

   564     to the position between the first and second result, and returns the first

   565     result; the second call to next() advances the iterator to the position

   566     between the second and third result, and returns the second result; and

   567     so on.

   568 

   569     \img javaiterators1.png

   570 

   571     Here's how to iterate over the elements in reverse order:

   572 

   573     \snippet doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp 2

   574 

   575     If you want to find all occurrences of a particular value, use findNext()

   576     or findPrevious() in a loop.

   577 

   578     Multiple iterators can be used on the same future. If the future is

   579     modified while a QFutureIterator is active, the QFutureIterator will

   580     continue iterating over the original future, ignoring the modified copy.

   581 

   582     \sa QFuture::const_iterator, QFuture

   583 */

   584 

   585 /*!

   586     \fn QFutureIterator::QFutureIterator(const QFuture<T> &future)

   587 

   588     Constructs an iterator for traversing \a future. The iterator is set to be

   589     at the front of the result list (before the first result).

   590 

   591     \sa operator=()

   592 */

   593 

   594 /*! \fn QFutureIterator &QFutureIterator::operator=(const QFuture<T> &future)

   595 

   596     Makes the iterator operate on \a future. The iterator is set to be at the

   597     front of the result list (before the first result).

   598 

   599     \sa toFront(), toBack()

   600 */

   601 

   602 /*! \fn void QFutureIterator::toFront()

   603 

   604     Moves the iterator to the front of the result list (before the first

   605     result).

   606 

   607     \sa toBack(), next()

   608 */

   609 

   610 /*! \fn void QFutureIterator::toBack()

   611 

   612     Moves the iterator to the back of the result list (after the last result).

   613 

   614     \sa toFront(), previous()

   615 */

   616 

   617 /*! \fn bool QFutureIterator::hasNext() const

   618 

   619     Returns true if there is at least one result ahead of the iterator, e.g.,

   620     the iterator is \e not at the back of the result list; otherwise returns

   621     false.

   622 

   623     \sa hasPrevious(), next()

   624 */

   625 

   626 /*! \fn const T &QFutureIterator::next()

   627 

   628     Returns the next result and advances the iterator by one position.

   629 

   630     Calling this function on an iterator located at the back of the result

   631     list leads to undefined results.

   632 

   633     \sa hasNext(), peekNext(), previous()

   634 */

   635 

   636 /*! \fn const T &QFutureIterator::peekNext() const

   637 

   638     Returns the next result without moving the iterator.

   639 

   640     Calling this function on an iterator located at the back of the result

   641     list leads to undefined results.

   642 

   643     \sa hasNext(), next(), peekPrevious()

   644 */

   645 

   646 /*! \fn bool QFutureIterator::hasPrevious() const

   647 

   648     Returns true if there is at least one result ahead of the iterator, e.g.,

   649     the iterator is \e not at the front of the result list; otherwise returns

   650     false.

   651 

   652     \sa hasNext(), previous()

   653 */

   654 

   655 /*! \fn const T &QFutureIterator::previous()

   656 

   657     Returns the previous result and moves the iterator back by one position.

   658 

   659     Calling this function on an iterator located at the front of the result

   660     list leads to undefined results.

   661 

   662     \sa hasPrevious(), peekPrevious(), next()

   663 */

   664 

   665 /*! \fn const T &QFutureIterator::peekPrevious() const

   666 

   667     Returns the previous result without moving the iterator.

   668 

   669     Calling this function on an iterator located at the front of the result

   670     list leads to undefined results.

   671 

   672     \sa hasPrevious(), previous(), peekNext()

   673 */

   674 

   675 /*! \fn bool QFutureIterator::findNext(const T &value)

   676 

   677     Searches for \a value starting from the current iterator position forward.

   678     Returns true if \a value is found; otherwise returns false.

   679 

   680     After the call, if \a value was found, the iterator is positioned just

   681     after the matching result; otherwise, the iterator is positioned at the

   682     back of the result list.

   683 

   684     \sa findPrevious()

   685 */

   686 

   687 /*! \fn bool QFutureIterator::findPrevious(const T &value)

   688 

   689     Searches for \a value starting from the current iterator position

   690     backward. Returns true if \a value is found; otherwise returns false.

   691 

   692     After the call, if \a value was found, the iterator is positioned just

   693     before the matching result; otherwise, the iterator is positioned at the

   694     front of the result list.

   695 

   696     \sa findNext()

   697 */