diff options
Diffstat (limited to 'src/corelib/thread/qpromise.qdoc')
| -rw-r--r-- | src/corelib/thread/qpromise.qdoc | 146 |
1 files changed, 97 insertions, 49 deletions
diff --git a/src/corelib/thread/qpromise.qdoc b/src/corelib/thread/qpromise.qdoc index 9c7925da95..e9c3eb4b7e 100644 --- a/src/corelib/thread/qpromise.qdoc +++ b/src/corelib/thread/qpromise.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \class QPromise \inmodule QtCore @@ -62,6 +38,8 @@ \snippet snippet_qpromise.cpp multithread_init \codeline \snippet snippet_qpromise.cpp multithread_main + \codeline + \snippet snippet_qpromise.cpp multithread_cleanup \sa QFuture */ @@ -78,11 +56,14 @@ \sa operator=() */ -/*! \fn template <typename T> QPromise<T>::QPromise(QFutureInterface<T> &other) +/*! \fn template <typename T> QPromise<T>::QPromise(const QFutureInterface<T> &other) + \fn template <typename T> QPromise<T>::QPromise(QFutureInterface<T> &&other) noexcept \internal Constructs a QPromise with a passed QFutureInterface \a other. - Used internally for QtConcurrent::runWithPromise. + Used internally for QtConcurrent::run(), when its callable takes + a reference to the associated promise as its first argument + (run with promise mode). \sa operator=() */ @@ -98,8 +79,8 @@ Destroys the promise. - \note The promise implicitly transitions to a cancelled state on destruction - unless reportFinished() is called beforehand by the user. + \note The promise implicitly transitions to a canceled state on destruction + unless finish() is called beforehand by the user. */ /*! \fn template <typename T> QFuture<T> QPromise<T>::future() const @@ -107,10 +88,40 @@ Returns a future associated with this promise. */ -/*! \fn template <typename T> void QPromise<T>::addResult(const T &result, int index = -1) +/*! \fn template <typename T> bool QPromise<T>::addResult(const T &result, int index = -1) + \fn template <typename T> bool QPromise<T>::addResult(T &&result, int index = -1) + + Same as + \code + emplaceResultAt(index, result); // first overload + emplaceResultAt(index, std::move(result)); // second overload + \endcode + or, if \c{index == -1} (the default) + \code + emplaceResult(result); // first overload + emplaceResult(std::move(result)); // second overload + \endcode + + \sa emplaceResultAt(), emplaceResult(), addResults() +*/ + +/*! + \fn template <typename T> template <typename...Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise<T>::emplaceResultAt(int index, Args&&...args) + \fn template <typename T> template <typename...Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise<T>::emplaceResult(Args&&...args) + \since 6.6 + + Adds a result constructed from \a args... to the internal result collection + at \a index position (emplaceResultAt()) or the end of of the collection + (emplaceResult()). + + Returns \c true when the result was added to the collection. - Adds \a result to the internal result collection at \a index position. If - index is unspecified, \a result is added to the end of the collection. + Returns \c false when this promise is in canceled or finished state or when + the result was rejected. addResult() rejects to add a result if there's already + another result in the collection stored at the same index. + + These functions only participate in overload resolutions if \c T is + constructible from \a args.... You can get a result at a specific index by calling QFuture::resultAt(). @@ -119,11 +130,29 @@ For instance, iterative approaches that use QFuture::resultCount() or QFuture::const_iterator. In order to get all available results without thinking if there are index gaps or not, use QFuture::results(). + + \sa addResult(), addResults() */ -/*! \fn template <typename T> void QPromise<T>::addResult(T &&result, int index = -1) +/*! + \fn template <typename T> bool QPromise<T>::addResults(const QList<T> &results) + \since 6.6 - \overload + Adds \a results at the end of the internal result collection. + + Returns \c true when \a results are added to the collection. + + Returns \c false when this promise is in canceled or finished state. + + This is more efficient than looping over addResult(), because associated + futures will be notified only once per addResults() call, instead of once + per element contained in \a results, as would be the case with individual + addResult() calls. But if the calculation of each element takes time, then + the code on the receiving end (future) cannot make progress until all + results are reported, so use this function only if the calculation of + consecutive elements is relatively fast. + + \sa addResult() */ /*! \fn template<typename T> void QPromise<T>::setException(const QException &e) @@ -134,41 +163,48 @@ execution. \note This method must not be used after QFuture::cancel() or - reportFinished(). + finish(). \sa isCanceled() */ +#if QT_VERSION < QT_VERSION_CHECK(7, 0, 0) /*! \fn template<typename T> void QPromise<T>::setException(std::exception_ptr e) \overload */ +#else +/*! \fn template<typename T> void QPromise<T>::setException(const std::exception_ptr &e) + + \overload +*/ +#endif -/*! \fn template<typename T> void QPromise<T>::reportStarted() +/*! \fn template<typename T> void QPromise<T>::start() Reports that the computation is started. Calling this method is important to state the beginning of the computation as QFuture methods rely on this information. - \note Extra attention is required when reportStarted() is called from a + \note Extra attention is required when start() is called from a newly created thread. In such case, the call might naturally be delayed due to the implementation details of the thread scheduling. - \sa QFuture::isStarted(), QFuture::waitForFinished(), reportFinished() + \sa QFuture::isStarted(), QFuture::waitForFinished(), finish() */ -/*! \fn template<typename T> void QPromise<T>::reportFinished() +/*! \fn template<typename T> void QPromise<T>::finish() Reports that the computation is finished. Once finished, no new results will - be added when calling addResult(). This method accompanies reportStarted(). + be added when calling addResult(). This method accompanies start(). - \sa QFuture::isFinished(), QFuture::waitForFinished(), reportStarted() + \sa QFuture::isFinished(), QFuture::waitForFinished(), start() */ /*! \fn template<typename T> void QPromise<T>::suspendIfRequested() Conditionally suspends current thread of execution and waits until resumed - or cancelled by the corresponding methods of QFuture. This method does not + or canceled by the corresponding methods of QFuture. This method does not block unless the computation is requested to be suspended by QFuture::suspend() or another related method. If you want to check that the execution has been suspended, use QFuture::isSuspended(). @@ -202,9 +238,9 @@ /*! \fn template<typename T> bool QPromise<T>::isCanceled() const - Returns whether the computation has been cancelled with the + Returns whether the computation has been canceled with the QFuture::cancel() function. The returned value \c true indicates that the - computation should be finished and reportFinished() called. + computation should be finished and finish() called. \note After cancellation, results currently available may still be accessed by a future, but new results will not be added when calling addResult(). @@ -215,7 +251,16 @@ Sets the progress range of the computation to be between \a minimum and \a maximum. - \sa QFuture::progressMinimum(), QFuture::progressMaximum() + If \a maximum is smaller than \a minimum, \a minimum becomes the only + legal value. + + The progress value is reset to be \a minimum. + + The progress range usage can be disabled by using setProgressRange(0, 0). + In this case progress value is also reset to 0. + + \sa QFuture::progressMinimum(), QFuture::progressMaximum(), + QFuture::progressValue() */ /*! \fn template<typename T> void QPromise<T>::setProgressValue(int progressValue) @@ -224,7 +269,10 @@ possible to only increment the progress value. This is a convenience method for calling setProgressValueAndText(progressValue, QString()). - \sa QFuture::progressValue() + In case of the \a progressValue falling out of the progress range, + this method has no effect. + + \sa QFuture::progressValue(), setProgressRange() */ /*! \fn template<typename T> void QPromise<T>::setProgressValueAndText(int progressValue, const QString &progressText) @@ -233,11 +281,11 @@ progressValue and \a progressText respectively. It is possible to only increment the progress value. - \note This function has no effect if the promise is in cancelled or finished + \note This function has no effect if the promise is in canceled or finished state. \sa QFuture::progressValue(), QFuture::progressText(), QFuture::cancel(), - reportFinished() + finish() */ /*! \fn template<typename T> void QPromise<T>::swap(QPromise<T> &other) noexcept |