QtFuture Namespace
QFuture クラスが使用する雑多な識別子を含む。さらに...
| ヘッダ | #include <QFuture> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
クラス
(since 6.3) struct | WhenAnyResult |
型
(since 6.0) enum class | Launch { Sync, Async, Inherit } |
関数
| QFuture<QtFuture::ArgsType<Signal>> | connect(Sender *sender, Signal signal) |
(since 6.1) QFuture<T> | makeExceptionalFuture(const QException &exception) |
(since 6.1) QFuture<T> | makeExceptionalFuture(std::__exception_ptr::exception_ptr exception) |
(since 6.6) QFuture<QtFuture::ContainedType<Container>> | makeReadyRangeFuture(Container &&container) |
(since 6.6) QFuture<ValueType> | makeReadyRangeFuture(std::initializer_list<ValueType> values) |
(since 6.6) QFuture<std::decay_t<T>> | makeReadyValueFuture(T &&value) |
(since 6.6) QFuture<void> | makeReadyVoidFuture() |
(since 6.3) QFuture<OutputSequence> | whenAll(Futures &&... futures) |
(since 6.3) QFuture<OutputSequence> | whenAll(InputIt first, InputIt last) |
(since 6.3) QFuture<std::variant<std::decay_t<Futures>...>> | whenAny(Futures &&... futures) |
(since 6.3) QFuture<QtFuture::WhenAnyResult<T>> | whenAny(InputIt first, InputIt last) |
型のドキュメント
[since 6.0] enum class QtFuture::Launch
QFuture 継続を実行するための実行ポリシーを表します。
| 定数 | 値 | 説明 |
|---|---|---|
QtFuture::Launch::Sync | 0 | 継続は、継続がアタッチされた未来に関連付けられた約束を実行するのと同じスレッドで起動されるか、すでに終了している場合は、then() を実行するスレッドですぐに起動されます。 |
QtFuture::Launch::Async | 1 | 継続はグローバルスレッドQThreadPool とは別のスレッドで起動される。 |
QtFuture::Launch::Inherit | 2 | 継続は、それがアタッチされている未来の起動ポリシーやスレッドプールを継承します。 |
Sync はデフォルトの起動ポリシーとして使用されます。
この列挙型は Qt 6.0 で導入されました。
QFuture::then() とQThreadPool::globalInstance()も参照してください 。
関数のドキュメント
template <typename Sender, typename Signal, typename = QtPrivate::EnableIfInvocable<Sender, Signal>> QFuture<QtFuture::ArgsType<Signal>> QtFuture::connect(Sender *sender, Signal signal)
sender がsignal を発したときに利用可能になるQFuture を生成して返す。signal が引数を取らない場合、QFuture<void> が返される。signal が単一の引数を取る場合、結果のQFuture はシグナルの引数値で満たされる。signal が複数の引数を取る場合、結果のQFuture はシグナルの引数の値を格納した std::tuple で満たされます。signal が発行される前にsender が破棄された場合、生成されたQFuture はキャンセルされます。
例えば、次のようなオブジェクトがあるとしよう：
class Object : public QObject { Q_OBJECT ... signals: void noArgSignal(); void singleArgSignal(int value); void multipleArgs(int value1, double value2, const QString &value3); };
そのシグナルをQFuture オブジェクトに接続するには、次のようにする：
Object object; QFuture<void> voidFuture = QtFuture::connect(&object, &Object::noArgSignal); QFuture<int> intFuture = QtFuture::connect(&object, &Object::singleArgSignal); using Args = std::tuple<int, double, QString>; QFuture<Args> tupleFuture = QtFuture::connect(&object, &Object::multipleArgs)
また、シグナルが発せられたときに実行される継続をチェーンすることもできる：
QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) { // do something with the value });
また、QtFuture::Launch ポリシーを使用して、新しいスレッドやカスタムスレッドプールで継続を開始することもできます。例えば
QtFuture::connect(&object, &Object::singleArgSignal).then(QtFuture::Launch::Async, [](int value) { // this will run in a new thread });
Qt のシグナルスロット接続によって呼び出されたスロットから例外をスローすることは、スロット内で処理されない場合、未定義の動作とみなされます。しかし、QFuture::connect() を使えば、継続から例外を投げたり、処理したりすることができます：
QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) { ... throw std::exception(); ... }).onFailed([](const std::exception &e) { // handle the exception }).onFailed([] { // handle other exceptions });
注意: 接続された未来は、シグナルが初めて発信された時に一度だけ満たされます。
QFuture およびQFuture::then()も参照してください 。
[since 6.1] template <typename T = void> QFuture<T> QtFuture::makeExceptionalFuture(const QException &exception)
既に例外exception を持つQFuture を作成し、返します。
QException e; auto f = QtFuture::makeExceptionalFuture<int>(e); ... try { f.result(); // throws QException } catch (QException &) { // handle exception here }
この関数は Qt 6.1 で導入されました。
QFuture,QException,QtFuture::makeReadyVoidFuture(),QtFuture::makeReadyValueFuture()も参照してください 。
[since 6.1] template <typename T = void> QFuture<T> QtFuture::makeExceptionalFuture(std::__exception_ptr::exception_ptr exception)
これはオーバーロードされた関数である。
既に例外exception を持つQFuture を作成し、返します。
struct TestException { }; ... auto exception = std::make_exception_ptr(TestException()); auto f = QtFuture::makeExceptionalFuture<int>(exception); ... try { f.result(); // throws TestException } catch (TestException &) { // handle exception here }
この関数は Qt 6.1 で導入されました。
QFuture,QException,QtFuture::makeReadyVoidFuture(),QtFuture::makeReadyValueFuture()も参照してください 。
[since 6.6] template <typename Container, QtFuture::if_container_with_input_iterators<Container> = true> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)
これはオーバーロードされた関数である。
入力コンテナcontainer を受け取り、container の値から初期化されたContainedType 型の複数の結果を持つQFuture を返す。
注意： このオーバーロードは、Container に入力イテレータがある場合にのみ、オーバーロード解決に参加します。
const std::vector<int> values{1, 2, 3}; auto f = QtFuture::makeReadyRangeFuture(values); ... const int count = f.resultCount(); // count == 3 const auto results = f.results(); // results == { 1, 2, 3 }
この関数は Qt 6.6 で導入されました。
QFuture,QtFuture::makeReadyVoidFuture(),QtFuture::makeReadyValueFuture(),QtFuture::makeExceptionalFuture()も参照してください 。
[since 6.6] template <typename ValueType> QFuture<ValueType> QtFuture::makeReadyRangeFuture(std::initializer_list<ValueType> values)
これはオーバーロードされた関数である。
入力イニシャライザリストvalues から初期化されたValueType 型の複数の結果を持つQFuture を返します。
auto f = QtFuture::makeReadyRangeFuture({1, 2, 3}); ... const int count = f.resultCount(); // count == 3 const auto results = f.results(); // results == { 1, 2, 3 }
この関数は Qt 6.6 で導入されました。
QFuture 、QtFuture::makeReadyVoidFuture()、QtFuture::makeReadyValueFuture()、QtFuture::makeExceptionalFuture()も参照してください 。
[since 6.6] template <typename T> QFuture<std::decay_t<T>> QtFuture::makeReadyValueFuture(T &&value)
既に結果value を持つQFuture を作成し、返す。返されるQFuture の型は std::decay_t<T> で、T は void ではありません。返されたQFuture は既に終了した状態になっています。
auto f = QtFuture::makeReadyValueFuture(std::make_unique<int>(42)); ... const int result = *f.takeResult(); // result == 42
この関数は Qt 6.6 で導入されました。
QFuture,QtFuture::makeReadyRangeFuture(),QtFuture::makeReadyVoidFuture(),QtFuture::makeExceptionalFuture()も参照してください 。
[since 6.6] QFuture<void> QtFuture::makeReadyVoidFuture()
voidQFuture を生成して返す。このようなQFuture は結果を保存できない。それを使って計算の状態を問い合わせることができる。返されるQFuture は既に終了した状態です。
auto f = QtFuture::makeReadyVoidFuture(); ... const bool started = f.isStarted(); // started == true const bool running = f.isRunning(); // running == false const bool finished = f.isFinished(); // finished == true
この関数は Qt 6.6 で導入されました。
QFuture,QFuture::isStarted(),QFuture::isRunning(),QFuture::isFinished(),QtFuture::makeReadyValueFuture(),QtFuture::makeReadyRangeFuture(),QtFuture::makeExceptionalFuture()も参照してください 。
[since 6.3] template <typename OutputSequence, typename... Futures> QFuture<OutputSequence> QtFuture::whenAll(Futures &&... futures)
futures パッケージングされた任意の型がすべて完了したときに成功する、新しいQFuture を返す。OutputSequence は、完了した先物のシーケンスである。そのエントリの型はstd::variant<Futures...> である。whenAll() に渡される各QFuture<T> に対して、OutputSequence の対応する位置のエントリは、そのQFuture<T> を完了状態で保持するstd::variant となる。OutputSequence の型が指定されていない場合、結果のフューチャーはstd::variant<Futures...> のQList で返される：
QFuture<int> intFuture = ...; QFuture<QString> stringFuture = ...; QFuture<void> voidFuture = ...; using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>; // whenAll has type QFuture<QList<FuturesVariant>> auto whenAll = QtFuture::whenAll(intFuture, stringFuture, voidFuture); // whenAllVector has type QFuture<std::vector<FuturesVariant>> auto whenAllVector = QtFuture::whenAll<std::vector<FuturesVariant>>(intFuture, stringFuture, voidFuture);
注意： 出力シーケンスはランダムアクセスとresize() 操作をサポートする必要があります。
返されるフューチャーは、指定されたすべてのフューチャーが完了した後、常に正常に完了します。これらのフューチャーのどれかがエラーで完了しても、キャンセルされても問題にはなりません。whenAll() によって返されたフューチャーが成功した後、.then() を使って完了したフューチャーを処理することができる：
QFuture<int> intFuture = ...; QFuture<QString> stringFuture = ...; QFuture<void> voidFuture = ...; using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>; QtFuture::whenAll(intFuture, stringFuture, voidFuture) .then([](const QList<FuturesVariant> &results) { ... for (auto result : results) { // assuming handleResult() is overloaded based on the QFuture type std::visit([](auto &&future) { handleResult(future); }, result); } ... });
注意： 入力されたフューチャーが別々のスレッドで完了した場合、このメソッドが返すフューチャーは、最後のフューチャーが完了したスレッドで完了します。したがって、whenAll() によって返される未来にアタッチされた継続は、どのスレッドで実行されるかを常に仮定することはできません。どのスレッドで継続が呼び出されるかを制御したい場合は、コンテキストオブジェクトを取る.then() のオーバーロードを使用してください。
この関数はQt 6.3で導入されました。
[since 6.3] template <typename OutputSequence, typename InputIt> QFuture<OutputSequence> QtFuture::whenAll(InputIt first, InputIt last)
first からlast までのすべてのフューチャーが完了したときに成功する，新しいQFuture を返す．first とlast は，フューチャーのパッケージング型T のシーケンスへのイテレータである．OutputSequence は，first からlast までのすべての完了したフューチャーを含むシーケンスであり，入力と同じ順序で現れる．OutputSequence の型が指定されない場合，結果のフューチャーはQFuture<T> のQList で返される．
QList<QFuture<int>> inputFutures {...}; // whenAll has type QFuture<QList<QFuture<int>>> auto whenAll = QtFuture::whenAll(inputFutures.begin(), inputFutures.end()); // whenAllVector has type QFuture<std::vector<QFuture<int>>> auto whenAllVector = QtFuture::whenAll<std::vector<QFuture<int>>>(inputFutures.begin(), inputFutures.end());
注： 出力シーケンスは、ランダムアクセスとresize() 操作をサポートしなければならない。
first がlast に等しい場合、この関数は空のOutputSequence を含むレディQFuture を返します。
返されたフューチャーは、指定されたフューチャーがすべて完了した後、常に正常に完了します。これらのフューチャーのどれかがエラーで完了しても、キャンセルされても問題にはなりません。whenAll() によって返されたフューチャーが成功した後、.then() を使って完了したフューチャーを処理することができます：
QList<QFuture<int>> inputFutures {...}; QtFuture::whenAll(inputFutures.begin(), inputFutures.end()) .then([](const QList<QFuture<int>> &results) { for (auto future : results) { if (future.isCanceled()) // handle the cancellation (possibly due to an exception) else // do something with the result } });
注意： 入力されたフューチャーが別々のスレッドで完了した場合、このメソッドが返すフューチャーは、最後のフューチャーが完了したスレッドで完了します。したがって、whenAll() によって返される未来にアタッチされた継続は、どのスレッドで実行されるかを常に仮定することはできません。どのスレッドで継続が呼び出されるかを制御したい場合は、コンテキストオブジェクトを取る.then() のオーバーロードを使用してください。
この関数はQt 6.3で導入されました。
[since 6.3] template <typename... Futures> QFuture<std::variant<std::decay_t<Futures>...>> QtFuture::whenAny(Futures &&... futures)
futures のいずれかが完了したときに成功する新しいQFuture を返す。futures は任意の型をパッケージ化できる。返された未来はstd::variant<Futures...> 型の値をパッケージ化し、futures から最初に完了したQFuture をパッケージ化します。std::variant::index()を使うと、最初に完了したfutures のシーケンスにおける未来のインデックスを知ることができます。
返された未来は、指定された未来から最初の未来が完了した後、常に正常に完了します。最初の未来がエラーで終了しても、キャンセルされても関係ありません。whenAny() が返す未来が成功した後に、.then() を使って結果を処理することができます：
QFuture<int> intFuture = ...; QFuture<QString> stringFuture = ...; QFuture<void> voidFuture = ...; using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>; QtFuture::whenAny(intFuture, stringFuture, voidFuture).then([](const FuturesVariant &result) { ... // assuming handleResult() is overloaded based on the QFuture type std::visit([](auto &&future) { handleResult(future); }, result); ... });
注意: 入力されたフューチャーが異なるスレッドで完了した場合、このメソッドが返すフューチャーは、最初のフューチャーが完了したスレッドで完了します。したがって、whenAny() によって返される未来にアタッチされた継続は、どのスレッドで実行されるかを常に仮定することはできません。どのスレッドで継続が呼び出されるかを制御したい場合は、コンテキストオブジェクトを取る.then() のオーバーロードを使用してください。
この関数はQt 6.3で導入されました。
[since 6.3] template <typename T, typename InputIt> QFuture<QtFuture::WhenAnyResult<T>> QtFuture::whenAny(InputIt first, InputIt last)
first からlast までのいずれかのフューチャーが完了したときに成功する、新しいQFuture を返す。first とlast は、T 型をパッケージ化した一連のフューチャーへのイテレータである。返されたフューチャーはQtFuture::WhenAnyResult<T> 型の値をパッケージ化し、次に最初に完了したQFuture のインデックスとQFuture 自体をパッケージ化する。first がlast と等しい場合、この関数は、QtFuture::WhenAnyResult 構造体のindex フィールドに-1 を持ち、future フィールドにデフォルトで構築されたQFuture<T> を持つ、準備のできたQFuture を返します。default-constructedQFuture は、キャンセルされた状態の完了した未来であることに注意してください。
返されたフューチャーは、指定されたフューチャーの最初のフューチャーが完了した後、常に正常に完了します。最初の未来がエラーで完了しても、キャンセルされても問題ではありません。whenAny() が返す未来が成功した後に、.then() を使って結果を処理することができます：
QList<QFuture<int>> inputFutures = ...; QtFuture::whenAny(inputFutures.begin(), inputFutures.end()) .then([](const QtFuture::WhenAnyResult<int> &result) { qsizetype index = result.index; QFuture<int> future = result.future; // ... });
注意: 入力されたフューチャーが異なるスレッドで完了した場合、このメソッドが返すフューチャーは、最初のフューチャーが完了したスレッドで完了します。したがって、whenAny() によって返される未来にアタッチされた継続は、どのスレッドで実行されるかを常に仮定することはできません。どのスレッドで継続が呼び出されるかを制御したい場合は、コンテキストオブジェクトを取る.then() のオーバーロードを使用してください。
この関数は Qt 6.3 で導入されました。
QtFuture::WhenAnyResultも参照してください 。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
