QFuture Class

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

QFuture::QFuture()

キャンセルされた空の未来を構築します。

QFuture::QFuture(const QFuture<T> &other)

other のコピーを構築する。

operator=()も参照 。

QFuture::~QFuture()

未来を破棄する。

これは非同期計算を待ったりキャンセルしたりしないことに注意してください。未来が破棄される前に計算が完了していることを確認する必要がある場合は、waitForFinished() またはQFutureSynchronizer を使用してください。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::begin() const

未来の最初の結果を指す constSTL 形式のイテレータを返します。

constBegin() およびend()も参照してください 。

void QFuture::cancel()

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

現在利用可能な結果は、キャンセルされた未来でもアクセスできますが、この関数を呼び出した後に新しい結果が利用可能になることはありません。このフューチャーをウォッチしているQFutureWatcher オブジェクトは、キャンセルされたフューチャーに対して進行状況と結果の準備完了シグナルを送出しません。

実行中のすべての非同期計算をキャンセルできるわけではないことに注意してください。例えば、QtConcurrent::run() が返す未来はキャンセルできませんが、QtConcurrent::mappedReduced() が返す未来はキャンセルできます。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constBegin() const

未来の最初の結果を指す constSTL 形式のイテレータを返します。

begin() およびconstEnd()も参照してください 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constEnd() const

未来における最後の結果の後の想像上の結果を指す constSTL 形式のイテレータを返します。

constBegin() およびend()も参照してください 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::end() const

未来における最後の結果の後の想像上の結果を指す constSTL 形式のイテレータを返します。

begin() およびconstEnd()も参照してください 。

bool QFuture::isCanceled() const

非同期計算がcancel() 関数でキャンセルされた場合はtrue を返し、そうでない場合はfalse を返す。

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

bool QFuture::isFinished() const

この future が表す非同期計算が終了した場合はtrue を返し、そうでない場合はfalse を返す。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> bool QFuture::isResultReadyAt(int index) const

index の結果がすぐに利用可能な場合はtrue を返し、そうでない場合はfalse を返す。

resultAt()、resultCount()、takeResult()も参照 。

bool QFuture::isRunning() const

このfutureで表される非同期計算が現在実行中であればtrue を返し、そうでなければfalse を返す。

bool QFuture::isStarted() const

この future で表される非同期計算が開始された場合はtrue を返し、そうでない場合はfalse を返す。

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

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

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

setSuspended(),toggleSuspended(),isSuspending()も参照してください 。

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

非同期計算がsuspend() 関数で中断されたが、まだ中断されておらず、計算が実行中である場合、true を返す。それ以外の場合はfalse を返す。

サスペンドが実際に有効かどうかを確認するには、代わりにisSuspended() を使用します。

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

setSuspended(),toggleSuspended(),isSuspended()も参照してください 。

[since 6.0] bool QFuture::isValid() const

このQFuture オブジェクトから結果または結果にアクセスまたは取得できる場合、true を返します。結果が未来から取得された後、false を返します。

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

takeResult(),result(),results(),resultAt()も参照してください 。

[since 6.0] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(Function &&handler)

この未来にキャンセルhandler をアタッチします。返された未来は、この未来がキャンセルされない限り、この未来とまったく同じように振る舞います（同じ状態と結果を持ちます）。handler は引数を取らない callable で、この future がパッケージした型の値を返します。キャンセル後、返された未来はhandler によって返された値をパッケージ化します。

キャンセルの前にアタッチされた場合、handler は、キャンセル後に未来が終了したと報告するのと同じスレッドで呼び出されます。この未来がすでにキャンセルされた後にハンドラがアタッチされた場合、ハンドラはonCanceled() を実行するスレッドで即座に呼び出されます。したがって、ハンドラは常にどのスレッドで実行されるかを想定することはできません。ハンドラがどのスレッドで起動されるかを制御したい場合は、コンテキストオブジェクトを受け取るオーバーロードを使用してください。

以下の例は、キャンセル・ハンドラをアタッチする方法を示している：

QFuture<int> testFuture = ...;
auto resultFuture = testFuture.then([](int res) {
    // Block 1
    ...
    return 1;
}).then([](int res) {
    // Block 2
    ...
    return 2;
}).onCanceled([] {
    // Block 3
    ...
    return -1;
});

testFuture がキャンセルされると、Block 3 が呼び出され、resultFuture はその結果として-1 を持つ。testFuture とは異なり、Canceled の状態にはならない。つまり、その結果を取得したり、カウンティニュエーションをアタッチしたりすることができる。

また、実行中の継続の連鎖は、その連鎖を開始した未来からキャンセルすることができる。例えば、Block 1 の実行中にtestFuture.cancel() が呼ばれたとしよう。次の継続はキャンセルが要求されたことを検出するので、Block 2 はスキップされ、キャンセルハンドラ (Block 3) が呼ばれます。

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

then() とonFailed()も参照してください 。

[since 6.1] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(QObject *context, Function &&handler)

これはオーバーロードされた関数です。

未来がキャンセルされたときに呼び出されるキャンセルhandler をこの未来にアタッチします。handler は引数をとらない callable です。これはcontext オブジェクトのスレッドで呼び出されます。これは、キャンセルを特定のスレッドで処理する必要がある場合に便利です。

チェーンが終了する前にcontext が破棄されると、未来はキャンセルされます。詳しくはthen() を参照してください。

handler の詳細については、他のオーバーロードのドキュメントを参照してください。

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

then() およびonFailed()も参照してください 。

[since 6.0] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(Function &&handler)

例外を処理するために、失敗ハンドラをこの future にアタッチします。返された未来は、この未来が例外で失敗しない限り、この未来とまったく同じように振る舞います（同じ状態と結果を持ちます）。

handler は callable で、引数なし、または引数をひとつ取り、catchステートメントと同様に、特定のエラータイプでフィルタリングします。これは、このfutureによってパッケージ化された型の値を返します。失敗の後、返されたfutureはhandler によって返された値をパッケージします。

ハンドラは、例外が発生した場合にのみ呼び出されます。このハンドラがアタッチされた後に例外が発生した場合、ハンドラは、例外の結果として future が終了したと報告したスレッドで実行されます。もしこのハンドラが、このフューチャーがすでに失敗した後にアタッチされた場合、ハンドラはonFailed() を実行するスレッドで即座に呼び出されます。したがって、ハンドラは常にどのスレッドで実行されるかを想定することはできません。ハンドラがどのスレッドで起動されるかを制御したい場合は、コンテキストオブジェクトを受け取るオーバーロードを使用してください。

以下の例は、失敗ハンドラをアタッチする方法を示しています：

QFuture<int> future = ...;
auto resultFuture = future.then([](int res) {
    ...
    throw Error();
    ...
}).onFailed([](const Error &e) {
    // Handle exceptions of type Error
    ...
    return -1;
}).onFailed([] {
    // Handle all other types of errors
    ...
    return -1;
});

auto result = resultFuture.result(); // result is -1

複数のハンドラがアタッチされている場合、スローされた例外の型にマッチする最初のハンドラが呼び出されます。例えば

QFuture<int> future = ...;
future.then([](int res) {
    ...
    throw std::runtime_error("message");
    ...
}).onFailed([](const std::exception &e) {
    // This handler will be invoked
}).onFailed([](const std::runtime_error &e) {
    // This handler won't be invoked, because of the handler above.
});

どのハンドラもスローされた例外の型と一致しない場合、例外は結果のフューチャーに伝搬されます：

QFuture<int> future = ...;
auto resultFuture = future.then([](int res) {
    ...
    throw Error("message");
    ...
}).onFailed([](const std::exception &e) {
    // Won't be invoked
}).onFailed([](const QException &e) {
    // Won't be invoked
});

try {
    auto result = resultFuture.result();
} catch(...) {
    // Handle the exception
}

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

then() およびonCanceled()も参照してください 。

[since 6.1] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(QObject *context, Function &&handler)

これはオーバーロードされた関数です。

失敗ハンドラをこの future にアタッチし、future が発生させる例外や、すでに発生させた例外を処理します。この future と同じ型のQFuture を返します。ハンドラは、context オブジェクトのスレッドで例外が発生した場合にのみ呼び出されます。これは、失敗を特定のスレッドで処理する必要がある場合に便利です。例えば

// somewhere in the main thread
auto future = QtConcurrent::run([] {
    // This will run in a separate thread
    ...
    throw std::exception();
}).onFailed(this, [] {
   // Update UI elements
});

QtConcurrent::run にアタッチされた失敗ハンドラはUIエレメントを更新するので、gui以外のスレッドから呼び出すことはできません。そこで、this を.onFailed() のコンテキストとして提供し、メインスレッドで起動されるようにします。

チェーンが終了する前にcontext が破棄されると、未来はキャンセルされます。詳細はthen() を参照。

handler の詳細については、他のオーバーロードのドキュメントを参照してください。

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

then() およびonCanceled()も参照してください 。

int QFuture::progressMaximum() const

progressValue() の最大値を返す。

progressValue() およびprogressMinimum()も参照 。

int QFuture::progressMinimum() const

progressValue() の最小値を返す。

progressValue() およびprogressMaximum()も参照 。

QString QFuture::progressText() const

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

すべての計算が進行状況のテキスト表現を提供するわけではないことに注意してください。

int QFuture::progressValue() const

progressMinimum() とprogressMaximum() の間にある現在の進捗値を返す。

progressMinimum() およびprogressMaximum()も参照 。

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

未来の最初の結果を返す。結果がすぐに利用可能でない場合、この関数はブロックして結果が利用可能になるのを待つ。これは、resultAt(0)を呼び出すための便利なメソッドである。result() は、内部に格納された結果のコピーを返すことに注意。T が移動専用型である場合、または結果をコピーしたくない場合は、代わりにtakeResult() を使用する。

resultAt()、results()、takeResult()も参照 。

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

index 、未来の結果を返す。結果がすぐに利用可能でない場合、この関数はブロックして結果が利用可能になるのを待つ。

result()、results()、takeResult()、resultCount()も参照 。

int QFuture::resultCount() const

この未来で利用可能な連続結果の数を返します。結果セットにギャップがあるため、実際に保存される結果の数はこの値と異なる可能性があります。0からresultCount()までの結果を繰り返し処理するのが常に安全です。

result()、resultAt()、results()、takeResult()も参照のこと 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QList<T> QFuture::results() const

未来からのすべての結果を返す。結果がすぐに利用できない場合、この関数はブロックして利用可能になるのを待つ。results() は内部的に保存された結果のコピーを返すことに注意。移動のみのタイプT のすべての結果を取得することは、現時点ではサポートされていません。しかし、STLスタイルのイテレータや読み取り専用のJavaスタイルのイテレータを使用することで、移動のみの結果のリストを繰り返し処理することは可能です。

result()、resultAt()、takeResult()、resultCount()、isValid()も参照のこと 。

void QFuture::resume()

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

suspend()も参照 。

[since 6.0] void QFuture::setSuspended(bool suspend)

suspend が真の場合、この関数は future() で表される非同期計算を一時停止する。すでに計算が中断されている場合、この関数は何もしません。QFutureWatcher は、future が中断されても、直ちに進行状況と結果の準備完了シグナルの配信を停止するわけではありません。中断された時点では、まだ進行中の計算があり、それを停止することはできません。そのような計算のシグナルはまだ配信されます。

suspend が false の場合、この関数は非同期計算を再開する。計算が中断されていない場合、この関数は何もしない。

すべての計算を中断できるわけではないことに注意してください。例えば、QtConcurrent::run() が返すQFuture は中断できませんが、QtConcurrent::mappedReduced() が返すQFuture は中断できます。

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

isSuspended(),suspend(),resume(),toggleSuspended()も参照してください 。

[since 6.0] void QFuture::suspend()

この future で表される非同期計算を一時停止します。これはsetSuspended(true) を呼び出すだけの便利なメソッドです。

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

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

[since 6.0] template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::takeResult()

isValid() がtrue を返す場合にのみ、この関数を呼び出す。この関数は、QFuture オブジェクトから最初の結果を取ります（移動します）。他の結果がある場合は、最初の結果を取得した後に破棄されます。結果がすぐに利用できない場合、この関数はブロックして結果が利用できるようになるのを待ちます。QFuture は、可能であればムーブ・セマンティクスを使おうとし、型がムーバブルでない場合はコピー・コンストラクションにフォールバックする。結果が取得された後、isValid （）はfalse として評価される。

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

result(),results(),resultAt(),isValid()も参照してください 。

[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(Function &&function)

これはオーバーロードされた関数である。

この future に継続をアタッチし、Sync ポリシーを使用して、必要であれば複数の非同期計算を連鎖させることができます。function は callable で、この future が結果を持つ場合（QFuture<void> ではない場合）、パッケージ化された型の引数を取ります。そうでない場合は引数を取りません。このメソッドはfunction によって返された型の値をパッケージ化した新しいQFuture を返します。返された future は、アタッチされた継続が呼び出されるか、この future が失敗するかキャンセルされるまで、初期化されていない状態になります。

このように複数の操作を連鎖させることができます：

QFuture<int> future = ...;
future.then([](int res1){ ... }).then([](int res2){ ... })...

または

QFuture<void> future = ...;
future.then([](){ ... }).then([](){ ... })...

継続はQFuture という引数を取ることもできます。これは、例えばQFuture が複数の結果を持っていて、ユーザーが継続の中でそれらにアクセスしたい場合に便利です。あるいは、複数の継続の連鎖を妨げないように、継続の内部で前の未来の例外を処理する必要があります。例えば

QFuture<int> future = ...;
    future.then([](QFuture<int> f) {
        try {
            ...
            auto result = f.result();
            ...
        } catch (QException &e) {
            // handle the exception
        }
    }).then(...);

前の未来が例外をスローし、それが継続の内部で処理されない場合、呼び出し元が例外を処理できるように、例外は継続の未来に伝搬されます：

QFuture<int> future = ...;
auto continuation = future.then([](int res1){ ... }).then([](int res2){ ... })...
...
// future throws an exception
try {
    auto result = continuation.result();
} catch (QException &e) {
    // handle the exception
}

この場合、継続のチェーン全体が中断されます。

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

onFailed() とonCanceled()も参照してください 。

[since 6.1] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QObject *context, Function &&function)

これはオーバーロードされた関数である。

必要であれば複数の非同期計算を連鎖させることができます。この future が表す非同期計算が終了すると、context オブジェクトのスレッドでfunction が呼び出されます。これは、継続を特定のスレッドで呼び出す必要がある場合に便利です。例えば

// somewhere in the main thread
auto future = QtConcurrent::run([] {
    // This will run in a separate thread
    ...
}).then(this, [] {
   // Update UI elements
});

QtConcurrent::run にアタッチされた継続は UI 要素を更新するので、gui 以外のスレッドから呼び出すことはできない。そこで、this を.then() のコンテキストとして提供し、メインスレッドで呼び出されるようにする。

異なるコンテキストや起動ポリシーが指定されない限り、以下の継続も同じコンテキストから起動される：

auto future = QtConcurrent::run([] {
    ...
}).then(this, [] {
   // Update UI elements
}).then([] {
    // This will also run in the main thread
});

これは、デフォルトでは.then() が前のスレッドと同じスレッドから呼び出されるためである。

しかし、この未来がすでに終了した後に継続がアタッチされた場合、then() を実行するスレッドですぐに呼び出されることに注意してください：

QObject *context = ...;
auto future = cachedResultsReady ? QtFuture::makeReadyValueFuture(result)
                                 : QtConcurrent::run([] { /* compute result */});
auto continuation = future.then(context, [] (Result result) {
    // Runs in the context's thread
}).then([] {
    // May or may not run in the context's thread
});

上記の例で、cachedResultsReady がtrue で、準備完了の未来が返された場合、最初の.then() が2番目の未来がアタッチされる前に終了する可能性があります。この場合、現在のスレッドで解決されます。したがって、疑わしい場合は、コンテキストを明示的に渡してください。

チェーンが終了する前にcontext が破棄された場合、未来はキャンセルされます。これは、context が有効でなくなったときにキャンセルハンドラが呼び出される可能性があることを意味します。これを防ぐには、context をQPointer としてキャプチャします：

QObject *context = ...;
auto future = ...;
auto continuation = future.then(context, [context](Result result) {
                               // ...
                           }).onCanceled([context = QPointer(context)] {
                               if (!context)
                                   return;  // context was destroyed already
                               // handle cancellation
                           });

コンテキスト・オブジェクトが破棄されると、直ちにキャンセルが行われる。コンテクストオブジェクトが破棄されると、即座にキャンセルされる。チェイン内の前のフューチャーはキャンセルされず、終了するまで実行され続ける。

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

onFailed() およびonCanceled()も参照してください 。

[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QThreadPool *pool, Function &&function)

これはオーバーロードされた関数です。

必要であれば、複数の非同期計算を連鎖させることができます。この future で表される非同期計算が終了すると、pool でfunction がスケジューリングされます。

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

onFailed() とonCanceled()も参照してください 。

[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QtFuture::Launch policy, Function &&function)

これはオーバーロードされた関数です。

複数の非同期計算を連鎖させることができるように、このfutureに継続をアタッチします。この future で表される非同期計算が終了すると、与えられた launchpolicy に従ってfunction が呼び出されます。継続の結果を表す新しいQFuture が返される。

policy に応じて、継続はこの future と同じスレッド、新しいスレッド、またはこの future の起動ポリシーとスレッドプールを継承して起動されます。起動ポリシーが指定されていない場合（ callable だけを取るオーバーロードを参照）、Sync ポリシーが使用されます。

次の例では、両方の継続が新しいスレッド（ただし同じスレッド）で呼び出されます。

QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... });

次の例では、両方の継続は、同じスレッドプールを使用する新しいスレッドで起動されます。

QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... })
      .then(QtFuture::Launch::Inherit, [](int res2){ ... });

function の詳細については、他のオーバーロードのドキュメントを参照してください。

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

onFailed() とonCanceled()も参照してください 。

[since 6.0] void QFuture::toggleSuspended()

非同期計算のサスペンド状態を切り替える。言い換えると、計算が現在サスペンド中または中断中の場合、この関数を呼び出すと再開され、計算が実行中の場合は中断される。これはsetSuspended(!(isSuspending() ||isSuspended())) を呼び出すための便利なメソッドです。

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

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

[since 6.4] template <typename U> QFuture<U> QFuture::unwrap()

このQFuture<T> から内側の未来を解き放ちます。ここでT はQFuture<U> 型の未来、つまりこの未来はQFuture<QFuture<U>> 型を持ちます：

QFuture<QFuture<int>> outerFuture = ...;
QFuture<int> unwrappedFuture = outerFuture.unwrap();

unwrappedFuture は、 の中に入れ子になっている内側の未来が、同じ結果または例外で、内側の未来が終了したと報告したスレッドで満たされるとすぐに満たされます。内側の未来がキャンセルされると、 もキャンセルされます。outerFuture unwrappedFuture

これは、複数の計算を連鎖させ、そのうちの1つが結果型としてQFuture を返す場合に特に便利です。例えば、URL から複数の画像をダウンロードし、画像を拡大縮小し、QtConcurrent::mappedReduced() を使用して 1 つの画像に縮小したいとします。次のように書くことができます：

auto downloadImages = [] (const QUrl &url) {
    QList<QImage> images;
    ...
    return images;
};

auto processImages = [](const QList<QImage> &images) {
   return QtConcurrent::mappedReduced(images, scale, reduceImages);
}

auto show = [](const QImage &image) { ... };

auto future = QtConcurrent::run(downloadImages, url)
               .then(processImages)
               .unwrap()
               .then(show);

ここで、QtConcurrent::mappedReduced() はQFuture<QImage> を返すので、.then(processImages) はQFuture<QFuture<QImage>> を返します。show() は引数としてQImage を取るので、.then(processImages) の結果を直接渡すことはできません。.unwrap() を呼び出す必要があります。 は、準備ができたら内側の未来の結果を取得し、次の継続に渡します。

複数のネストがある場合、.unwrap() は最も内側のレベルまで下がります：

QFuture<QFuture<QFuture<int>>>> outerFuture;
QFuture<int> unwrappedFuture = outerFuture.unwrap();

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

void QFuture::waitForFinished()

非同期計算（cancel()された計算を含む）が終了するまで、すなわちisFinished()がtrue を返すまで待つ。

QFuture<T> &QFuture::operator=(const QFuture<T> &other)

other をこの未来に割り当て、この未来への参照を返します。