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

또한 신호가 발신될 때 실행될 연속체(continuation)를 연쇄적으로 연결할 수도 있습니다:

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 는 임의의 유형을 포함할 수 있습니다. 반환된 future는 std::variant<Futures...> 유형의 값을 포함하며, 이 값은 futures 에서 가장 먼저 완료된 QFuture 를 포함합니다. std::variant::index()를 사용하여 futures 시퀀스에서 가장 먼저 완료된 future의 인덱스를 확인할 수 있습니다.

반환된 퓨처는 지정된 퓨처 중 첫 번째 퓨처가 완료된 후 항상 성공적으로 완료됩니다. 첫 번째 퓨처가 오류로 완료되든 취소되든 상관없습니다. 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 는 취소된 상태의 완료된 퓨처라는 점에 유의하십시오.

반환된 퓨처는 지정된 퓨처 중 첫 번째 퓨처가 완료된 후 항상 성공적으로 완료됩니다. 첫 번째 퓨처가 오류로 완료되든 취소되든 상관없습니다. ` 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;
            //...
        });

이 함수는 Qt 6.3에서 도입되었습니다.

QtFuture::WhenAnyResult도 참조하십시오 .