Move QFutureSynchronizer back to QtCore

This class, too, belongs with QFuture.

Change-Id: I41a532ca66c156f1631e4b22ffc1a5879c854488
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

3 files changed, 277 insertions, 0 deletions

diff --git a/src/corelib/thread/qfuturesynchronizer.h b/src/corelib/thread/qfuturesynchronizer.h
new file mode 100644
index 0000000000..12edcfb971
--- /dev/null
+++ b/src/corelib/thread/qfuturesynchronizer.h
@@ -0,0 +1,120 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QFUTURESYNCHRONIZER_H
+#define QFUTURESYNCHRONIZER_H
+
+#include <QtCore/qfuture.h>
+
+#ifndef QT_NO_QFUTURE
+
+QT_BEGIN_HEADER
+QT_BEGIN_NAMESPACE
+
+
+template <typename T>
+class QFutureSynchronizer
+{
+    Q_DISABLE_COPY(QFutureSynchronizer)
+
+public:
+    QFutureSynchronizer() : m_cancelOnWait(false) { }
+    explicit QFutureSynchronizer(const QFuture<T> &future)
+        : m_cancelOnWait(false)
+    { addFuture(future); }
+    ~QFutureSynchronizer()  { waitForFinished(); }
+
+    void setFuture(const QFuture<T> &future)
+    {
+        waitForFinished();
+        m_futures.clear();
+        addFuture(future);
+    }
+
+    void addFuture(const QFuture<T> &future)
+    {
+        m_futures.append(future);
+    }
+
+    void waitForFinished()
+    {
+        if (m_cancelOnWait) {
+            for (int i = 0; i < m_futures.count(); ++i) {
+                 m_futures[i].cancel();
+            }
+        }
+        
+        for (int i = 0; i < m_futures.count(); ++i) {
+             m_futures[i].waitForFinished();
+         }
+    }
+
+    void clearFutures()
+    {
+        m_futures.clear();
+    }
+
+    QList<QFuture<T> > futures() const
+    {
+        return m_futures;
+    }
+
+    void setCancelOnWait(bool enabled)
+    {
+        m_cancelOnWait = enabled;
+    }
+
+    bool cancelOnWait() const
+    {
+        return m_cancelOnWait;
+    }
+
+protected:
+    QList<QFuture<T> > m_futures;
+    bool m_cancelOnWait;
+};
+
+QT_END_NAMESPACE
+QT_END_HEADER
+
+#endif // QT_NO_QFUTURE
+
+#endif // QFUTURESYNCHRONIZER_H
diff --git a/src/corelib/thread/qfuturesynchronizer.qdoc b/src/corelib/thread/qfuturesynchronizer.qdoc
new file mode 100644
index 0000000000..903dc89d1e
--- /dev/null
+++ b/src/corelib/thread/qfuturesynchronizer.qdoc
@@ -0,0 +1,156 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*! \class QFutureSynchronizer
+    \since 4.4
+
+    \brief The QFutureSynchronizer class is a convenience class that simplifies
+    QFuture synchronization.
+
+    \ingroup thread
+
+    QFutureSynchronizer is a template class that simplifies synchronization of
+    one or more QFuture objects. Futures are added using the addFuture() or
+    setFuture() functions. The futures() function returns a list of futures.
+    Use clearFutures() to remove all futures from the QFutureSynchronizer.
+    
+    The waitForFinished() function waits for all futures to finish.
+    The destructor of QFutureSynchronizer calls waitForFinished(), providing
+    an easy way to ensure that all futures have finished before returning from
+    a function:
+    
+    \snippet code/src_corelib_thread_qfuturesynchronizer.cpp 0
+    
+    The behavior of waitForFinished() can be changed using the
+    setCancelOnWait() function. Calling setCancelOnWait(true) will cause
+    waitForFinished() to cancel all futures before waiting for them to finish.
+    You can query the status of the cancel-on-wait feature using the
+    cancelOnWait() function.
+    
+    \sa QFuture, QFutureWatcher, {Concurrent Programming}{Qt Concurrent}
+*/
+
+/*!
+    \fn QFutureSynchronizer::QFutureSynchronizer()
+
+    Constructs a QFutureSynchronizer.
+*/
+
+/*!
+    \fn QFutureSynchronizer::QFutureSynchronizer(const QFuture<T> &future)
+
+    Constructs a QFutureSynchronizer and begins watching \a future by calling
+    addFuture().
+    
+    \sa addFuture()
+*/
+
+/*!
+    \fn QFutureSynchronizer::~QFutureSynchronizer()
+    
+    Calls waitForFinished() function to ensure that all futures have finished
+    before destroying this QFutureSynchronizer.
+    
+    \sa waitForFinished()
+*/
+
+/*!
+    \fn void QFutureSynchronizer::setFuture(const QFuture<T> &future)
+    
+    Sets \a future to be the only future managed by this QFutureSynchronizer.
+    This is a convenience function that calls waitForFinished(),
+    then clearFutures(), and finally passes \a future to addFuture().
+    
+    \sa addFuture(), waitForFinished(), clearFutures()
+*/
+
+/*!
+    \fn void QFutureSynchronizer::addFuture(const QFuture<T> &future)
+
+    Adds \a future to the list of managed futures.
+    
+    \sa futures()
+*/
+
+/*!
+    \fn void QFutureSynchronizer::waitForFinished()
+
+    Waits for all futures to finish. If cancelOnWait() returns true, each
+    future is canceled before waiting for them to finish.
+    
+    \sa cancelOnWait(), setCancelOnWait()
+*/
+
+/*!
+    \fn void QFutureSynchronizer::clearFutures()
+
+    Removes all managed futures from this QFutureSynchronizer.
+    
+    \sa addFuture(), setFuture()
+*/
+
+/*!
+    \fn QList<QFuture<T> > QFutureSynchronizer::futures() const
+
+    Returns a list of all managed futures.
+    
+    \sa addFuture(), setFuture()
+*/
+
+/*!
+    \fn void QFutureSynchronizer::setCancelOnWait(bool enabled)
+    
+    Enables or disables the cancel-on-wait feature based on the \a enabled
+    argument. If \a enabled is true, the waitForFinished() function will cancel
+    all futures before waiting for them to finish.
+
+    \sa waitForFinished()
+*/
+
+/*!
+    \fn bool QFutureSynchronizer::cancelOnWait() const
+
+    Returns true if the cancel-on-wait feature is enabled; otherwise returns
+    false. If cancel-on-wait is enabled, the waitForFinished() function will
+    cancel all futures before waiting for them to finish.
+
+    \sa waitForFinished()
+*/
diff --git a/src/corelib/thread/thread.pri b/src/corelib/thread/thread.pri
index 6e341beb75..7247f2984e 100644
--- a/src/corelib/thread/thread.pri
+++ b/src/corelib/thread/thread.pri
@@ -14,6 +14,7 @@ HEADERS += thread/qmutex.h \
            thread/qresultstore.h \
            thread/qfuture.h \
            thread/qfutureinterface.h \
+           thread/qfuturesynchronizer.h \
            thread/qfuturewatcher.h \
            thread/qbasicatomic.h \
            thread/qgenericatomic.h \