diff options
Diffstat (limited to 'src/corelib/thread/qfuture.qdoc')
| -rw-r--r-- | src/corelib/thread/qfuture.qdoc | 82 |
1 files changed, 42 insertions, 40 deletions
diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index 79bd121aee..b278d39882 100644 --- a/src/corelib/thread/qfuture.qdoc +++ b/src/corelib/thread/qfuture.qdoc @@ -122,6 +122,12 @@ QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), and QtFuture::makeExceptionalFuture(). + \note Some APIs (see \l {QFuture::then()} or various QtConcurrent method + overloads) allow scheduling the computation to a specific thread pool. + However, QFuture implements a work-stealing algorithm to prevent deadlocks + and optimize thread usage. As a result, computations can be executed + directly in the thread which requests the QFuture's result. + \note To start a computation and store results in a QFuture, use QPromise or one of the APIs in the \l {Qt Concurrent} framework. @@ -384,7 +390,7 @@ computations), i.e. until isFinished() returns \c true. */ -/*! \fn template <typename T> T QFuture<T>::result() const +/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture<T>::result() const Returns the first result in the future. If the result is not immediately available, this function will block and wait for the result to become @@ -399,7 +405,7 @@ \sa resultAt(), results(), takeResult() */ -/*! \fn template <typename T> T QFuture<T>::resultAt(int index) const +/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture<T>::resultAt(int index) const Returns the result at \a index in the future. If the result is not immediately available, this function will block and wait for the result to @@ -411,7 +417,7 @@ \sa result(), results(), takeResult(), resultCount() */ -/*! \fn template <typename T> bool QFuture<T>::isResultReadyAt(int index) const +/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> bool QFuture<T>::isResultReadyAt(int index) const Returns \c true if the result at \a index is immediately available; otherwise returns \c false. @@ -422,7 +428,7 @@ \sa resultAt(), resultCount(), takeResult() */ -/*! \fn template <typename T> QList<T> QFuture<T>::results() const +/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QList<T> QFuture<T>::results() const Returns all results from the future. If the results are not immediately available, this function will block and wait for them to become available. Note that @@ -438,7 +444,7 @@ */ #if 0 -/*! \fn template <typename T> std::vector<T> QFuture<T>::takeResults() +/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> std::vector<T> QFuture<T>::takeResults() If isValid() returns \c false, calling this function leads to undefined behavior. takeResults() takes all results from the QFuture object and invalidates it @@ -457,7 +463,7 @@ */ #endif -/*! \fn template <typename T> std::vector<T> QFuture<T>::takeResult() +/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> std::vector<T> QFuture<T>::takeResult() \since 6.0 @@ -492,7 +498,7 @@ \sa takeResult(), result(), results(), resultAt() */ -/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::begin() const +/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::begin() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first result in the future. @@ -500,7 +506,7 @@ \sa constBegin(), end() */ -/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::end() const +/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::end() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary result after the last result in the future. @@ -508,7 +514,7 @@ \sa begin(), constEnd() */ -/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::constBegin() const +/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::constBegin() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first result in the future. @@ -516,7 +522,7 @@ \sa begin(), constEnd() */ -/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::constEnd() const +/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::constEnd() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary result after the last result in the future. @@ -607,17 +613,17 @@ Returns a pointer to the current result. */ -/*! \fn template <typename T> bool QFuture<T>::const_iterator::operator!=(const const_iterator &other) const +/*! \fn template <typename T> bool QFuture<T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs) - Returns \c true if \a other points to a different result than this iterator; + Returns \c true if \a lhs points to a different result than \a rhs iterator; otherwise returns \c false. \sa operator==() */ -/*! \fn template <typename T> bool QFuture<T>::const_iterator::operator==(const const_iterator &other) const +/*! \fn template <typename T> bool QFuture<T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs) - Returns \c true if \a other points to the same result as this iterator; + Returns \c true if \a lhs points to the same result as \a rhs iterator; otherwise returns \c false. \sa operator!=() @@ -930,7 +936,7 @@ \sa QtFuture::whenAny() */ -/*! \fn template<class Sender, class Signal> static QFuture<ArgsType<Signal>> QtFuture::connect(Sender *sender, Signal signal) +/*! \fn template<class Sender, class Signal, typename = QtPrivate::EnableIfInvocable<Sender, Signal>> static QFuture<ArgsType<Signal>> QtFuture::connect(Sender *sender, Signal signal) Creates and returns a QFuture which will become available when the \a sender emits the \a signal. If the \a signal takes no arguments, a QFuture<void> is returned. If @@ -969,16 +975,11 @@ \sa QFuture, QFuture::then() */ -/*! \fn template<typename T> static QFuture<std::decay_t<T>> QtFuture::makeReadyFuture(T &&value) +/*! \fn template<typename T, typename = QtPrivate::EnableForNonVoid<T>> static QFuture<std::decay_t<T>> QtFuture::makeReadyFuture(T &&value) \since 6.1 \overload - \deprecated [6.10] Use makeReadyValueFuture() instead - - The QtFuture::makeReadyFuture() method should be avoided because it has an - inconsistent set of overloads. It will be deprecated in future Qt releases. - Use QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() or - QtFuture::makeReadyRangeFuture() instead. + \deprecated [6.6] Use makeReadyValueFuture() instead. Creates and returns a QFuture which already has a result \a value. The returned QFuture has a type of std::decay_t<T>, where T is not void. @@ -989,6 +990,10 @@ const int result = *f.takeResult(); // result == 42 \endcode + The method should be avoided because + it has an inconsistent set of overloads. From Qt 6.10 onwards, using it + in code will result in compiler warnings. + \sa QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), QtFuture::makeExceptionalFuture() @@ -998,12 +1003,7 @@ \since 6.1 \overload - \deprecated [6.10] Use makeReadyVoidFuture() instead - - The QtFuture::makeReadyFuture() method should be avoided because it has an - inconsistent set of overloads. It will be deprecated in future Qt releases. - Use QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() or - QtFuture::makeReadyRangeFuture() instead. + \deprecated [6.6] Use makeReadyVoidFuture() instead. Creates and returns a void QFuture. Such QFuture can't store any result. One can use it to query the state of the computation. @@ -1017,6 +1017,10 @@ const bool finished = f.isFinished(); // finished == true \endcode + The method should be avoided because + it has an inconsistent set of overloads. From Qt 6.10 onwards, using it + in code will result in compiler warnings. + \sa QFuture, QFuture::isStarted(), QFuture::isRunning(), QFuture::isFinished(), QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), @@ -1027,12 +1031,7 @@ \since 6.1 \overload - \deprecated [6.10] Use makeReadyRangeFuture() instead - - The QtFuture::makeReadyFuture() method should be avoided because it has an - inconsistent set of overloads. It will be deprecated in future Qt releases. - Use QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() or - QtFuture::makeReadyRangeFuture() instead. + \deprecated [6.6] Use makeReadyRangeFuture() instead. Creates and returns a QFuture which already has multiple results set from \a values. @@ -1044,6 +1043,10 @@ const auto results = f.results(); // results == { 1, 2, 3 } \endcode + The method should be avoided because + it has an inconsistent set of overloads. From Qt 6.10 onwards, using it + in code will result in compiler warnings. + \sa QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), QtFuture::makeExceptionalFuture() @@ -1257,8 +1260,7 @@ Attaches a continuation to this future, allowing to chain multiple asynchronous computations if desired. When the asynchronous computation represented by this - future finishes, \a function will be invoked in a separate thread taken from the - QThreadPool \a pool. + future finishes, \a function will be scheduled on \a pool. \sa onFailed(), onCanceled() */ @@ -1314,7 +1316,7 @@ \sa onFailed(), onCanceled() */ -/*! \fn template<class T> template<class Function> QFuture<T> QFuture<T>::onFailed(Function &&handler) +/*! \fn template<class T> template<class Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture<T>::onFailed(Function &&handler) \since 6.0 @@ -1357,7 +1359,7 @@ \sa then(), onCanceled() */ -/*! \fn template<class T> template<class Function> QFuture<T> QFuture<T>::onFailed(QObject *context, Function &&handler) +/*! \fn template<class T> template<class Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture<T>::onFailed(QObject *context, Function &&handler) \since 6.1 \overload @@ -1385,7 +1387,7 @@ \sa then(), onCanceled() */ -/*! \fn template<class T> template<class Function> QFuture<T> QFuture<T>::onCanceled(Function &&handler) +/*! \fn template<class T> template<class Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture<T>::onCanceled(Function &&handler) \since 6.0 @@ -1430,7 +1432,7 @@ \sa then(), onFailed() */ -/*! \fn template<class T> template<class Function> QFuture<T> QFuture<T>::onCanceled(QObject *context, Function &&handler) +/*! \fn template<class T> template<class Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture<T>::onCanceled(QObject *context, Function &&handler) \since 6.1 \overload |