include/QtCore/qfuturewatcher.h

0001 // Copyright (C) 2020 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003 // Qt-Security score:significant reason:default
0004
0005 #ifndef QFUTUREWATCHER_H
0006 #define QFUTUREWATCHER_H
0007
0008 #include <QtCore/qfuture.h>
0009 #include <QtCore/qobject.h>
0010
0011 QT_REQUIRE_CONFIG(future);
0012
0013 QT_BEGIN_NAMESPACE
0014
0015
0016 class QEvent;
0017
0018 class QFutureWatcherBasePrivate;
0019 class Q_CORE_EXPORT QFutureWatcherBase : public QObject
0020 {
0021     Q_OBJECT
0022     Q_DECLARE_PRIVATE(QFutureWatcherBase)
0023
0024 public:
0025     explicit QFutureWatcherBase(QObject *parent = nullptr);
0026     // de-inline dtor
0027
0028     int progressValue() const;
0029     int progressMinimum() const;
0030     int progressMaximum() const;
0031     QString progressText() const;
0032
0033     bool isStarted() const;
0034     bool isFinished() const;
0035     bool isRunning() const;
0036     bool isCanceled() const;
0037 #if QT_DEPRECATED_SINCE(6, 0)
0038     QT_DEPRECATED_VERSION_X_6_0("Use isSuspending() or isSuspended() instead.")
0039     bool isPaused() const;
0040 #endif
0041     bool isSuspending() const;
0042     bool isSuspended() const;
0043
0044     void waitForFinished();
0045
0046     void setPendingResultsLimit(int limit);
0047
0048     bool event(QEvent *event) override;
0049
0050 Q_SIGNALS:
0051     void started();
0052     void finished();
0053     void canceled();
0054 #if QT_DEPRECATED_SINCE(6, 0)
0055     QT_DEPRECATED_VERSION_X_6_0("Use suspending() instead.")
0056     void paused();
0057 #endif
0058     void suspending();
0059     void suspended();
0060     void resumed();
0061     void resultReadyAt(int resultIndex);
0062     void resultsReadyAt(int beginIndex, int endIndex);
0063     void progressRangeChanged(int minimum, int maximum);
0064     void progressValueChanged(int progressValue);
0065     void progressTextChanged(const QString &progressText);
0066
0067 public Q_SLOTS:
0068     void cancel();
0069     void setSuspended(bool suspend);
0070     void suspend();
0071     void resume();
0072     void toggleSuspended();
0073
0074 #if QT_DEPRECATED_SINCE(6, 0)
0075     QT_DEPRECATED_VERSION_X_6_0("Use setSuspended() instead.")
0076     void setPaused(bool paused);
0077
0078     QT_DEPRECATED_VERSION_X_6_0("Use suspend() instead.")
0079     void pause();
0080
0081     QT_DEPRECATED_VERSION_X_6_0("Use toggleSuspended() instead.")
0082     void togglePaused();
0083 #endif
0084
0085 protected:
0086     void connectNotify (const QMetaMethod &signal) override;
0087     void disconnectNotify (const QMetaMethod &signal) override;
0088
0089     // called from setFuture() implemented in template sub-classes
0090     void connectOutputInterface();
0091     void disconnectOutputInterface(bool pendingAssignment = false);
0092
0093 private:
0094     // implemented in the template sub-classes
0095     virtual const QFutureInterfaceBase &futureInterface() const = 0;
0096     virtual QFutureInterfaceBase &futureInterface() = 0;
0097 };
0098
0099 template <typename T>
0100 class QFutureWatcher : public QFutureWatcherBase
0101 {
0102 public:
0103     explicit QFutureWatcher(QObject *_parent = nullptr)
0104         : QFutureWatcherBase(_parent)
0105     { }
0106     ~QFutureWatcher()
0107     { disconnectOutputInterface(); }
0108
0109     void setFuture(const QFuture<T> &future);
0110     QFuture<T> future() const
0111     { return m_future; }
0112
0113     template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>>
0114     T result() const { return m_future.result(); }
0115
0116     template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>>
0117     T resultAt(int index) const { return m_future.resultAt(index); }
0118
0119 #ifdef Q_QDOC
0120     int progressValue() const;
0121     int progressMinimum() const;
0122     int progressMaximum() const;
0123     QString progressText() const;
0124
0125     bool isStarted() const;
0126     bool isFinished() const;
0127     bool isRunning() const;
0128     bool isCanceled() const;
0129 #if QT_DEPRECATED_SINCE(6, 0)
0130     bool isPaused() const;
0131 #endif
0132     bool isSuspending() const;
0133     bool isSuspended() const;
0134
0135     void waitForFinished();
0136
0137     void setPendingResultsLimit(int limit);
0138
0139 Q_SIGNALS:
0140     void started();
0141     void finished();
0142     void canceled();
0143 #if QT_DEPRECATED_SINCE(6, 0)
0144     void paused();
0145 #endif
0146     void suspending();
0147     void suspended();
0148     void resumed();
0149     void resultReadyAt(int resultIndex);
0150     void resultsReadyAt(int beginIndex, int endIndex);
0151     void progressRangeChanged(int minimum, int maximum);
0152     void progressValueChanged(int progressValue);
0153     void progressTextChanged(const QString &progressText);
0154
0155 public Q_SLOTS:
0156     void cancel();
0157     void setSuspended(bool suspend);
0158     void suspend();
0159     void resume();
0160     void toggleSuspended();
0161 #if QT_DEPRECATED_SINCE(6, 0)
0162     void setPaused(bool paused);
0163     void pause();
0164     void togglePaused();
0165 #endif // QT_DEPRECATED_SINCE(6, 0)
0166
0167 #endif // Q_QDOC
0168
0169 private:
0170     QFuture<T> m_future;
0171     const QFutureInterfaceBase &futureInterface() const override { return m_future.d; }
0172     QFutureInterfaceBase &futureInterface() override { return m_future.d; }
0173 };
0174
0175 template <typename T>
0176 Q_INLINE_TEMPLATE void QFutureWatcher<T>::setFuture(const QFuture<T> &_future)
0177 {
0178     if (_future.d == m_future.d)
0179         return;
0180
0181     disconnectOutputInterface(true);
0182     m_future = _future;
0183     connectOutputInterface();
0184 }
0185
0186 QT_END_NAMESPACE
0187
0188 #endif // QFUTUREWATCHER_H