summaryrefslogtreecommitdiffstats
path: root/src/corelib/thread/qpromise.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/thread/qpromise.qdoc')
-rw-r--r--src/corelib/thread/qpromise.qdoc88
1 files changed, 57 insertions, 31 deletions
diff --git a/src/corelib/thread/qpromise.qdoc b/src/corelib/thread/qpromise.qdoc
index f9040d4cd1..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
*/
@@ -83,7 +61,9 @@
\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=()
*/
@@ -111,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
@@ -127,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)