QPromise Class

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

[default] QPromise::QPromise()

デフォルトの状態を持つQPromiseを生成します。

[delete] QPromise::QPromise(const QPromise<T> &)

QPromise のインスタンスをコピーして生成します。この関数は削除されています。

[default] QPromise::QPromise(QPromise<T> &&other)

Moveは、other から新しいQPromiseを生成します。

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

QPromise::~QPromise()

プロミスを破棄します。

以下と同じ

emplaceResultAt(index, result);            // first overload
emplaceResultAt(index, std::move(result)); // second overload

あるいは、index == -1 （デフォルト）の場合

emplaceResult(result);            // first overload
emplaceResult(std::move(result)); // second overload

emplaceResultAt()、emplaceResult()、およびaddResults()も参照してください 。

[since 6.6] bool QPromise::addResults(const QList<T> &results)

内部の結果コレクションの末尾にresults を追加します。

results がコレクションに追加された場合、true を返します。

このプロミスが「canceled」または「finished」の状態にある場合、false を返します。

これは、addResult() をループ処理するよりも効率的です。なぜなら、個別のaddResult() を呼び出す場合のようにresults に含まれる要素ごとに通知されるのではなく、addResults() の呼び出しごとに 1 回だけ関連付けられたフューチャーに通知されるからです。 ただし、各要素の計算に時間がかかる場合、受信側（フューチャー）のコードはすべての結果が報告されるまで処理を進めることができないため、連続する要素の計算が比較的高速な場合にのみ、この関数を使用してください。

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

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

args... から構築された結果を、index の位置 (emplaceResultAt()) またはコレクションの末尾 (emplaceResult()) に追加します。

結果がコレクションに追加された場合、true を返します。

このプロミスがキャンセルまたは完了状態にある場合、または結果が拒否された場合、false を返します。addResult() は、コレクション内の同じインデックスにすでに別の結果が格納されている場合、結果の追加を拒否します。

これらの関数は、T が以下から構築可能な場合にのみ、オーバーロードの解決に関与します。args....

QFuture::resultAt() を呼び出すことで、特定のインデックスにある結果を取得できます。

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

addResult() およびaddResults()も参照してください 。

void QPromise::finish()

計算が完了したことを報告します。完了後は、addResult() を呼び出しても新しい結果は追加されません。このメソッドは、start() と組み合わせて使用されます。

QFuture::isFinished()、QFuture::waitForFinished()、およびstart()も参照してください 。

QFuture<T> QPromise::future() const

このプロミスに関連付けられたフューチャーを返します。

bool QPromise::isCanceled() const

QFuture::cancel() 関数によって計算がキャンセルされたかどうかを返します。戻り値がtrue の場合、計算を完了させ、finish()を呼び出す必要があることを示します。

void QPromise::setException(const QException &e)

e 例外を計算結果として設定します。

関連項目： isCanceled()。

void QPromise::setException(std::__exception_ptr::exception_ptr e)

void QPromise::setProgressRange(int minimum, int maximum)

計算の進行範囲をminimum からmaximum の間に設定します。

maximum がminimum より小さい場合、minimum が唯一の有効な値となります。

進行状況の値はminimum にリセットされます。

setProgressRange(0, 0) を使用することで、進行状況範囲の使用を無効にできます。この場合、進行状況の値も 0 にリセットされます。

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

void QPromise::setProgressValue(int progressValue)

計算の進行状況をprogressValue に設定します。進行状況の値は増加させることのみ可能です。これは、setProgressValueAndText(progressValue, QString())を呼び出すための便宜的なメソッドです。

progressValue が進行範囲外になった場合、このメソッドは効果を発揮しません。

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

void QPromise::setProgressValueAndText(int progressValue, const QString &progressText)

計算の進行状況値と進行状況テキストを、それぞれ `progressValue ` および `progressText ` に設定します。進行状況値のみをインクリメントすることも可能です。

関連項目： QFuture::progressValue()、QFuture::progressText()、QFuture::cancel()、およびfinish()。

void QPromise::start()

計算が開始されたことを報告します。QFuture メソッドはこの情報に依存しているため、計算の開始を明示するには、このメソッドを呼び出すことが重要です。

関連項目： QFuture::isStarted()、QFuture::waitForFinished()、およびfinish()。

void QPromise::suspendIfRequested()

現在の実行スレッドを条件付きで一時停止し、QFuture の対応するメソッドによって再開またはキャンセルされるまで待機します。このメソッドは、QFuture::suspend() またはその他の関連メソッドによって計算の一時停止が要求されない限り、ブロックしません。実行が一時停止されたことを確認したい場合は、QFuture::isSuspended() を使用してください。

以下のコードスニペットは、一時停止メカニズムの使用例を示しています：

    // Create promise and future
    QPromise<int> promise;
    QFuture<int> future = promise.future();

    promise.start();
    // Start a computation thread that supports suspension and cancellation
    const std::unique_ptr<QThread> thread(QThread::create([] (QPromise<int> promise) {
        for (int i = 0; i < 100; ++i) {
            promise.addResult(i);
            promise.suspendIfRequested();   // support suspension
            if (promise.isCanceled())       // support cancellation
                break;
        }
        promise.finish();
    }, std::move(promise)));
    thread->start();

QFuture::suspend() は、関連付けられたプロミスの実行を一時停止するよう要求します：

    future.suspend();

QFuture::isSuspended() がtrue になると、中間結果を取得できるようになります:

    future.resultCount();  // returns some number between 0 and 100
    for (int i = 0; i < future.resultCount(); ++i) {
        // process results available before suspension
    }

一時停止中は、待機中の計算を再開またはキャンセルできます:

    future.resume();  // resumes computation, this call will unblock the promise
    // alternatively, call future.cancel() to stop the computation

    future.waitForFinished();
    future.results();  // returns all computation results - array of values from 0 to 99

QFuture::resume()、QFuture::cancel()、QFuture::setSuspended()、およびQFuture::toggleSuspended()も参照してください 。

[noexcept] void QPromise::swap(QPromise<T> &other)

このプロミスを `other` に置き換えます。この操作は非常に高速で、失敗することはありません。

[noexcept] QPromise<T> &QPromise::operator=(QPromise<T> &&other)

Moveは、other をこのプロミスに割り当て、このプロミスへの参照を返します。

[delete] QPromise<T> &QPromise::operator=(const QPromise<T> &)

other をこのQPromise インスタンスにコピー・代入します。この関数は削除されます。