From f84206ba6962a6ad735787cac6313223238f5d4a Mon Sep 17 00:00:00 2001 From: Andreas Hartmetz Date: Tue, 25 Jan 2022 14:52:13 +0100 Subject: Better document attaching a QFutureWatcher to a started QFuture It is an important and useful part of the API contract that the QFutureWatcher signals will emit complete information after setFuture() on an already started QFuture. If that wasn't so, some API clients would need two code paths to gather state and progress information: one through the signals for not yet started QFutures, and one through the state querying APIs for already started QFutures. The previous documentation was not precise enough to rely on, even though the implemented behavior - cf. QFutureInterfaceBasePrivate::connectOutputInterface() - seems well thought out and implemented to rely on. Pick-to: 6.3 6.2 Change-Id: Iaf3db37a851f07ac85881adaea5c83612a7fd843 Reviewed-by: Leena Miettinen Reviewed-by: Sona Kurazyan --- src/corelib/thread/qfuturewatcher.cpp | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/corelib/thread/qfuturewatcher.cpp b/src/corelib/thread/qfuturewatcher.cpp index f86f0ce6ba..d3a904ab00 100644 --- a/src/corelib/thread/qfuturewatcher.cpp +++ b/src/corelib/thread/qfuturewatcher.cpp @@ -610,9 +610,15 @@ QT_WARNING_POP Starts watching the given \a future. - One of the signals might be emitted for the current state of the - \a future. For example, if the future is already stopped, the - finished signal will be emitted. + If \a future has already started, the watcher will initially emit signals + that bring their listeners up to date about the future's state. The + following signals will, if applicable, be emitted in the given order: + started(), progressRangeChanged(), progressValueChanged(), + progressTextChanged(), resultsReadyAt(), resultReadyAt(), suspending(), + suspended(), canceled() finished(). Of these, resultsReadyAt() and + resultReadyAt() may be emitted several times to cover all available + results. progressValueChanged() and progressTextChanged() will only be + emitted once for the latest available progress value and text. To avoid a race condition, it is important to call this function \e after doing the connections. -- cgit v1.2.3