diff options
Diffstat (limited to 'src/corelib/thread/qpromise.qdoc')
-rw-r--r-- | src/corelib/thread/qpromise.qdoc | 98 |
1 files changed, 66 insertions, 32 deletions
diff --git a/src/corelib/thread/qpromise.qdoc b/src/corelib/thread/qpromise.qdoc index 78182323be..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=() */ @@ -110,15 +91,38 @@ /*! \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) - 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. + 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 \a result is added to the collection. + Returns \c true when the result was added to the collection. Returns \c false when this promise is in canceled or finished state or when - \a result is rejected. addResult() rejects \a result if there's already + 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(). \note It is possible to specify an arbitrary index and request result at @@ -126,6 +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> bool QPromise<T>::addResults(const QList<T> &results) + \since 6.6 + + 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) @@ -141,10 +168,17 @@ \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>::start() |