QtFuture Namespace

関数のドキュメント

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が格納されます。sender がsignal が発行される前に破棄された場合、結果として得られる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> requires if_container_with_input_iterators<Container> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

入力コンテナcontainer を受け取り、container の値から初期化されたContainedType 型の結果を複数含むQFuture を返します。

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 }

制約

Container が入力イテレータを持つ場合にのみ、オーバーロード解決の対象となります。

この関数は 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()

`void`型のQFuture を作成して返します。このような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);

返されるフューチャーは、指定されたすべてのフューチャーが完了した後、常に正常に完了します。これらのフューチャーのいずれかがエラーで完了したり、キャンセルされたりしても問題ありません。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);
            }
            //...
        });

この関数は 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());

first がlast に等しい場合、この関数は、空のOutputSequence を含む、準備完了状態のQFuture を返します。

返されるフューチャーは、指定されたすべてのフューチャーが完了した後、常に正常に完了します。これらのフューチャーのいずれかがエラーで完了したり、キャンセルされたりしても問題ありません。`.then() ` を使用すると、`whenAll() ` によって返されたフューチャーが成功した後、完了したフューチャーを処理することができます:

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
                }
            }
        });

この関数は 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);
    //...
});

この関数は 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 を返します。なお、デフォルト構築されたQFuture は、キャンセルされた状態の完了済みフューチャーであることに注意してください。

返されるフューチャーは、指定されたフューチャーのうち最初のフューチャーが完了した後、常に正常に完了します。最初のフューチャーがエラーで完了したか、キャンセルされたかは関係ありません。`.then() ` を使用すると、`whenAny() ` によって返されたフューチャーが成功した後に結果を処理できます:

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;
            //...
        });

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

QtFuture::WhenAnyResultも参照してください 。