QFutureWatcher Class

// Instantiate the objects and connect to the finished signal.
MyClass myObject;
QFutureWatcher<int> watcher;
QObject::connect(&watcher, &QFutureWatcher<int>::finished, &myObject, &MyClass::handleFinished);

// Start the computation.
QFuture<int> future = QtConcurrent::run([result](){ /*...*/ return result;});
watcher.setFuture(future);

メンバ関数のドキュメント

[explicit] QFutureWatcher::QFutureWatcher(QObject *parent = nullptr)

指定されたparent を使用して、新しいQFutureWatcherを構築します。setFuture()でフューチャーが設定されるまでは、isStarted()、isCanceled()、およびisFinished()の各関数は、true を返します。

[virtual] QFutureWatcher::~QFutureWatcher()

QFutureWatcher を削除します。

[slot] void QFutureWatcher::cancel()

future() で表される非同期計算をキャンセルします。キャンセル処理は非同期で行われる点に注意してください。同期的なキャンセルが必要な場合は、cancel() を呼び出した後にwaitForFinished() を使用してください。

キャンセルされたQFuture に対しては、現在利用可能な結果に引き続きアクセスできますが、この関数を呼び出した後は新しい結果は得られなくなります。また、一度キャンセルされると、このQFutureWatcher は進行状況や結果の準備完了シグナルを送信しなくなります。これには、progressValueChanged()、progressRangeChanged()、progressTextChanged()、resultReadyAt()、およびresultsReadyAt() シグナルが含まれます。

実行中の非同期計算のすべてがキャンセルできるわけではない点に注意してください。たとえば、QtConcurrent::run() によって返される `QFuture ` はキャンセルできませんが、QtConcurrent::mappedReduced() によって返される `QFuture ` はキャンセル可能です。

[signal] void QFutureWatcher::canceled()

監視対象のフューチャーがキャンセルされた場合、このシグナルが発信されます。

[signal] void QFutureWatcher::finished()

このシグナルは、監視対象の先物取引が終了した際に発信されます。

QFuture<T> QFutureWatcher::future() const

監視対象のフューチャーを返します。

setFuture()も参照してください 。

bool QFutureWatcher::isCanceled() const

cancel() 関数によって非同期計算がキャンセルされた場合、またはフューチャーが設定されていない場合は、true を返します。それ以外の場合は、false を返します。

この関数がtrue を返した場合でも、計算がまだ実行中である可能性があることに注意してください。詳細については、cancel() を参照してください。

bool QFutureWatcher::isFinished() const

future() で表される非同期計算が完了した場合、またはフューチャーが設定されていない場合は、true を返します。それ以外の場合は、false を返します。

bool QFutureWatcher::isRunning() const

future() で表される非同期計算が現在実行中の場合は、true を返し、そうでない場合はfalse を返します。

bool QFutureWatcher::isStarted() const

future() で表される非同期計算が開始されている場合、またはフューチャーが設定されていない場合は、true を返します。それ以外の場合は、false を返します。

[since 6.0] bool QFutureWatcher::isSuspended() const

非同期計算の一時停止が要求され、それが有効になっている場合（つまり、これ以上の結果や進行状況の変更は期待されない場合）、true を返します。

この関数は Qt 6.0 で導入されました。

suspended()、setSuspended()、およびisSuspending()も参照してください 。

[since 6.0] bool QFutureWatcher::isSuspending() const

suspend() 関数によって非同期計算が一時停止されているものの、処理自体はまだ一時停止されておらず、計算が実行中の場合は、true を返します。それ以外の場合は、false を返します。

一時停止が実際に有効になっているかどうかを確認するには、代わりに `isSuspended()` を使用してください。

この関数は Qt 6.0 で導入されました。

setSuspended()、toggleSuspended()、およびisSuspended()も参照してください 。

int QFutureWatcher::progressMaximum() const

progressValue() の最大値を返します。

progressValue() およびprogressMinimum()も参照してください 。

int QFutureWatcher::progressMinimum() const

progressValue() の最小値を返します。

progressValue() およびprogressMaximum()も参照してください 。

[signal] void QFutureWatcher::progressRangeChanged(int minimum, int maximum)

監視対象のフューチャーの進捗範囲が、minimum およびmaximum に変更されました。

QString QFutureWatcher::progressText() const

非同期計算によって報告された進捗状況の（オプションの）テキスト表現を返します。

すべての計算が進行状況のテキスト表現を提供するわけではないため、この関数は空の文字列を返す場合があることに注意してください。

[signal] void QFutureWatcher::progressTextChanged(const QString &progressText)

このシグナルは、監視対象の先物がテキスト形式の進捗情報を報告した際に発せられます。progressText 。

int QFutureWatcher::progressValue() const

現在の進行状況の値を返します。この値は、progressMinimum() とprogressMaximum() の間の値となります。

progressMinimum() およびprogressMaximum()も参照してください 。

[signal] void QFutureWatcher::progressValueChanged(int progressValue)

このシグナルは、監視対象のフューチャーが進行状況を報告した際に発せられます。progressValue は現在の進行状況を返します。GUI イベントループへの負荷を避けるため、QFutureWatcher は進行状況シグナルの発火頻度を制限しています。つまり、このスロットに接続されているリスナーは、フューチャーが生成するすべての進行状況レポートを受け取れない場合があります。ただし、最新の進行状況の更新（progressValue が最大値となるもの）は常に配信されます。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFutureWatcher::result() const

future() の最初の結果を返します。結果がすぐに利用できない場合、この関数はブロックされ、結果が利用可能になるまで待機します。これは、resultAt(0) を呼び出すための便利なメソッドです。

resultAt()も参照してください 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFutureWatcher::resultAt(int index) const

future() 内のindex にある結果を返します。結果がすぐに利用できない場合、この関数はブロックし、結果が利用可能になるまで待機します。

result()も参照してください 。

[signal] void QFutureWatcher::resultReadyAt(int index)

このシグナルは、監視対象のフューチャーが `index` で「ready」結果を報告したときに発火します。フューチャーが複数の結果を報告した場合、インデックスによってどの結果であるかが示されます。結果は順不同で報告されることがあります。結果を取得するには、resultAt(index) を呼び出してください。

[signal] void QFutureWatcher::resultsReadyAt(int beginIndex, int endIndex)

このシグナルは、監視対象の先物が結果を報告した際に発せられます。結果には、beginIndex からendIndex までのインデックスが付けられています。

[slot] void QFutureWatcher::resume()

future() で表される非同期計算を再開します。これは、単にsetSuspended(false) を呼び出すだけの便宜的なメソッドです。

suspend()も参照してください 。

[signal] void QFutureWatcher::resumed()

このシグナルは、監視対象のフューチャーが再開されたときに発せられます。

void QFutureWatcher::setFuture(const QFuture<T> &future)

指定されたfuture の監視を開始します。

future がすでに起動している場合、ウォッチャーは最初に、リスナーに対してフューチャーの状態に関する最新情報を伝えるシグナルを発行します。該当する場合、以下のシグナルが指定された順序で発行されます：started()、progressRangeChanged()、progressValueChanged()、progressTextChanged()、resultsReadyAt()、resultReadyAt()、suspending()、suspended()、canceled()、およびfinished()。 このうち、resultsReadyAt() およびresultReadyAt() は、利用可能なすべての結果を網羅するために複数回出力される場合があります。progressValueChanged() およびprogressTextChanged() は、利用可能な最新の進行状況値とテキストについて 1 回のみ出力されます。

競合状態を避けるため、接続処理を完了した後にこの関数を呼び出すことが重要です。

future()も参照してください 。

void QFutureWatcher::setPendingResultsLimit(int limit)

setPendingResultsLimit() メソッドは、スロットリング制御を提供します。resultReadyAt() またはresultsReadyAt() による保留中のシグナルの数がlimit を超えると、そのフューチャーが表す計算は自動的にスロットリングされます。保留中のシグナルの数がlimit を下回ると、計算は再開されます。

[slot, since 6.0] void QFutureWatcher::setSuspended(bool suspend)

suspend がtrueの場合、この関数はfuture()によって表される非同期計算を一時停止します。計算がすでに一時停止されている場合、この関数は何もしません。フューチャーが一時停止されても、QFutureWatcher は進行状況および結果の準備完了シグナルの配信を直ちに停止することはありません。 一時停止の時点でも、進行中で停止できない計算が残っている場合があります。そのような計算に関するシグナルは引き続き配信されます。

suspend がfalseの場合、この関数は非同期計算を再開します。計算が以前に一時停止されていなかった場合、この関数は何もしません。

すべての計算がサスペンドできるわけではない点に注意してください。たとえば、QtConcurrent::run() によって返される `QFuture ` はサスペンドできませんが、QtConcurrent::mappedReduced() によって返される `QFuture ` はサスペンド可能です。

この関数は Qt 6.0 で導入されました。

suspended()、suspend()、resume()、およびtoggleSuspended()も参照してください 。

[signal] void QFutureWatcher::started()

このシグナルは、このQFutureWatcher がsetFuture()を使用してfutureセットの監視を開始したときに発火します。

[slot, since 6.0] void QFutureWatcher::suspend()

このフューチャーによって表される非同期計算を一時停止します。これは、単に `setSuspended(true)` を呼び出すだけの便宜上のメソッドです。

この関数は Qt 6.0 で導入されました。

resume()も参照してください 。

[signal, since 6.0] void QFutureWatcher::suspended()

このシグナルは、suspend() が有効になったときに発火します。これは、実行中の計算がもうないことを意味します。このシグナルを受信した後は、結果の準備完了や進行状況の報告に関するシグナルはこれ以上発生しないものと見なされます。

この関数は Qt 6.0 で導入されました。

setSuspended() およびsuspend()も参照してください 。

[signal, since 6.0] void QFutureWatcher::suspending()

このシグナルは、監視対象のフューチャーの状態が「suspended」に設定されたときに発火します。

この関数は Qt 6.0 で導入されました。

関連項目： setSuspended()、suspend()、およびsuspended()。

[slot, since 6.0] void QFutureWatcher::toggleSuspended()

非同期計算の保留状態を切り替えます。つまり、計算が現在保留中または一時停止中の場合、この関数を呼び出すと計算が再開され、計算が実行中の場合は一時停止されます。これは、setSuspended(!(isSuspending() ||isSuspended()))を呼び出すための便利なメソッドです。

この関数は Qt 6.0 で導入されました。

setSuspended()、suspend()、およびresume()も参照してください 。

void QFutureWatcher::waitForFinished()

非同期計算（cancel() で実行された計算を含む）が完了するまで、つまりisFinished() がtrue を返すまで待機します。