Back to Qt.io
Contact Us Blog Download Qt

QtFuture Namespace

QFuture クラスが使用する雑多な識別子を含む。詳細...

Header: #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)

詳細説明

クラス

クラスWhenAnyResult

QtFuture::WhenAnyResult は () の結果を表すために使用されます。QtFuture::whenAny詳細...

型 ドキュメント

[since 6.0] enum class QtFuture::Launch

QFuture 継続を実行するための実行ポリシーを表します。

定数値説明
QtFuture::Launch::Sync0継続は、継続がアタッチされた未来に関連付けられた約束を実行するスレッドと同じスレッドで起動されるか、すでに終了している場合は、継続はthen() を実行するスレッドですぐに起動されます。
QtFuture::Launch::Async1継続はグローバルスレッドQThreadPool とは別のスレッドで起動される。
QtFuture::Launch::Inherit2継続は、それがアタッチされている未来の起動ポリシーやスレッドプールを継承します。

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も参照してください 。

本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。