From 0235de994be7e04aca3456f1260b18313dd45b74 Mon Sep 17 00:00:00 2001 From: Dennis Oberst Date: Wed, 14 Jun 2023 18:31:40 +0200 Subject: QFuture: mention the work-stealing algorithm in the docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A number of users have explored the behavior and complained about it. Lets add a \note explaining this. The function in charge is QThreadPool::stealAndRunRunnable(QRunnable *), which is a private function, exclusively used by: QFutureInterfaceBase::waitForResult() QFutureInterfaceBase::waitForFinished() also update the documentation to reflect these changes accordingly. Fixes: QTBUG-112351 Pick-to: 6.6 6.5 6.2 5.15 Change-Id: I839858cb449063d8af9bef64d2f35a6816a419b0 Reviewed-by: Ivan Solovev Reviewed-by: Mårten Nordheim --- src/concurrent/qtconcurrentrun.cpp | 5 ++--- src/corelib/thread/qfuture.qdoc | 9 +++++++-- 2 files changed, 9 insertions(+), 5 deletions(-) (limited to 'src') diff --git a/src/concurrent/qtconcurrentrun.cpp b/src/concurrent/qtconcurrentrun.cpp index fc19b947e5..9a7fe2167a 100644 --- a/src/concurrent/qtconcurrentrun.cpp +++ b/src/concurrent/qtconcurrentrun.cpp @@ -259,9 +259,8 @@ \since 5.4 \fn QFuture QtConcurrent::run(QThreadPool *pool, Function function, ...); - Runs \a function in a separate thread. The thread is taken from the - QThreadPool \a pool. Note that \a function may not run immediately; \a function - will only be run once a thread becomes available. + Schedules \a function on \a pool. Note that \a function may not run + immediately; \a function will only be run once a thread becomes available. \include qtconcurrentrun.cpp run-description */ diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index 79bd121aee..2535d621ca 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. @@ -1257,8 +1263,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() */ -- cgit v1.2.3