src/corelib/concurrent/qfuturesynchronizer.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 /*! \class QFutureSynchronizer
  43     \since 4.4
  44
  45     \brief The QFutureSynchronizer class is a convenience class that simplifies
  46     QFuture synchronization.
  47
  48     \ingroup thread
  49
  50     QFutureSynchronizer is a template class that simplifies synchronization of
  51     one or more QFuture objects. Futures are added using the addFuture() or
  52     setFuture() functions. The futures() function returns a list of futures.
  53     Use clearFutures() to remove all futures from the QFutureSynchronizer.
  54
  55     The waitForFinished() function waits for all futures to finish.
  56     The destructor of QFutureSynchronizer calls waitForFinished(), providing
  57     an easy way to ensure that all futures have finished before returning from
  58     a function:
  59
  60     \snippet doc/src/snippets/code/src_corelib_concurrent_qfuturesynchronizer.cpp 0
  61
  62     The behavior of waitForFinished() can be changed using the
  63     setCancelOnWait() function. Calling setCancelOnWait(true) will cause
  64     waitForFinished() to cancel all futures before waiting for them to finish.
  65     You can query the status of the cancel-on-wait feature using the
  66     cancelOnWait() function.
  67
  68     \sa QFuture, QFutureWatcher, {Concurrent Programming}{Qt Concurrent}
  69 */
  70
  71 /*!
  72     \fn QFutureSynchronizer::QFutureSynchronizer()
  73
  74     Constructs a QFutureSynchronizer.
  75 */
  76
  77 /*!
  78     \fn QFutureSynchronizer::QFutureSynchronizer(const QFuture<T> &future)
  79
  80     Constructs a QFutureSynchronizer and begins watching \a future by calling
  81     addFuture().
  82
  83     \sa addFuture()
  84 */
  85
  86 /*!
  87     \fn QFutureSynchronizer::~QFutureSynchronizer()
  88
  89     Calls waitForFinished() function to ensure that all futures have finished
  90     before destroying this QFutureSynchronizer.
  91
  92     \sa waitForFinished()
  93 */
  94
  95 /*!
  96     \fn void QFutureSynchronizer::setFuture(const QFuture<T> &future)
  97
  98     Sets \a future to be the only future managed by this QFutureSynchronizer.
  99     This is a convenience function that calls waitForFinished(),
 100     then clearFutures(), and finally passes \a future to addFuture().
 101
 102     \sa addFuture(), waitForFinished(), clearFutures()
 103 */
 104
 105 /*!
 106     \fn void QFutureSynchronizer::addFuture(const QFuture<T> &future)
 107
 108     Adds \a future to the list of managed futures.
 109
 110     \sa futures()
 111 */
 112
 113 /*!
 114     \fn void QFutureSynchronizer::waitForFinished()
 115
 116     Waits for all futures to finish. If cancelOnWait() returns true, each
 117     future is canceled before waiting for them to finish.
 118
 119     \sa cancelOnWait(), setCancelOnWait()
 120 */
 121
 122 /*!
 123     \fn void QFutureSynchronizer::clearFutures()
 124
 125     Removes all managed futures from this QFutureSynchronizer.
 126
 127     \sa addFuture(), setFuture()
 128 */
 129
 130 /*!
 131     \fn QList<QFuture<T> > QFutureSynchronizer::futures() const
 132
 133     Returns a list of all managed futures.
 134
 135     \sa addFuture(), setFuture()
 136 */
 137
 138 /*!
 139     \fn void QFutureSynchronizer::setCancelOnWait(bool enabled)
 140
 141     Enables or disables the cancel-on-wait feature based on the \a enabled
 142     argument. If \a enabled is true, the waitForFinished() function will cancel
 143     all futures before waiting for them to finish.
 144
 145     \sa waitForFinished()
 146 */
 147
 148 /*!
 149     \fn bool QFutureSynchronizer::cancelOnWait() const
 150
 151     Returns true if the cancel-on-wait feature is enabled; otherwise returns
 152     false. If cancel-on-wait is enabled, the waitForFinished() function will
 153     cancel all futures before waiting for them to finish.
 154
 155     \sa waitForFinished()
 156 */