diff options
| author | Andreas Hartmetz <andreas@ixgreen.de> | 2022-01-25 14:52:13 +0100 |
|---|---|---|
| committer | Andreas Hartmetz <andreas@ixgreen.de> | 2022-02-02 21:53:41 +0100 |
| commit | f84206ba6962a6ad735787cac6313223238f5d4a (patch) | |
| tree | 208addf62b9174cb4b4c2773e4ca15906964d982 | |
| parent | 64e33727bb846c11b350e20ef00ec25688bddf27 (diff) | |
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 <riitta-leena.miettinen@qt.io>
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
| -rw-r--r-- | src/corelib/thread/qfuturewatcher.cpp | 12 |
1 files 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. |