QPromise Class

template <typename T> class QPromise

QPromise 클래스는 QFuture 에서 액세스할 수 있는 계산 결과를 저장하는 방법을 제공합니다. 더 보기...

헤더:	`#include <QPromise>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake:	`QT += core`
이후:	Qt 6.0

상속된 멤버를 포함한 모든 멤버 목록
QPromise는 스레딩 클래스의 일부입니다.

참고: 이 클래스의 모든 함수는 스레드 안전합니다.

공용 함수

	QPromise()
	QPromise(QPromise<T> &&other)
	~QPromise()
bool	addResult(T &&result, int index = -1)
bool	addResult(const T &result, int index = -1)
`(since 6.6)` bool	addResults(const QList<T> &results)
`(since 6.6)` bool	emplaceResult(Args &&... args)
`(since 6.6)` bool	emplaceResultAt(int index, Args &&... args)
void	finish()
QFuture<T>	future() const
bool	isCanceled() const
void	setException(const QException &e)
void	setException(std::__exception_ptr::exception_ptr e)
void	setProgressRange(int minimum, int maximum)
void	setProgressValue(int progressValue)
void	setProgressValueAndText(int progressValue, const QString &progressText)
void	start()
void	suspendIfRequested()
void	swap(QPromise<T> &other)
QPromise<T> &	operator=(QPromise<T> &&other)

상세 설명

QPromise는 사용자 정의 계산의 진행 상황과 결과를 비동기 방식으로 QFuture 에 전달하는 간단한 방법을 제공합니다. 통신이 작동하려면 QPromise에서 QFuture 을 구성해야 합니다.

세분화된 제어가 필요한 경우 QPromise 기반 워크로드를 대안으로 사용할 수 있습니다. Qt Concurrent 프레임워크의 대안으로 사용할 수 있으며, 세분화된 제어가 필요하거나 QFuture 에 수반되는 높은 수준의 통신 프리미티브만으로도 충분합니다.

약속과 향후 협업의 가장 간단한 사례는 단일 결과 커뮤니케이션입니다:

    QPromise<int> promise;
    QFuture<int> future = promise.future();

    const std::unique_ptr<QThread> thread(QThread::create([] (QPromise<int> promise) {
        promise.start();   // notifies QFuture that the computation is started
        promise.addResult(42);
        promise.finish();  // notifies QFuture that the computation is finished
    }, std::move(promise)));
    thread->start();

    future.waitForFinished();  // blocks until QPromise::finish is called
    future.result();  // returns 42

설계상 QPromise는 이동 전용 객체입니다. 이 동작은 약속이 파기될 때마다 관련된 미래 객체에 알림을 보내고 결과를 사용할 수 있을 때까지 영원히 기다리지 않도록 하는 데 도움이 됩니다. 그러나 동일한 프로미스를 사용하여 다른 스레드에서 결과를 보고하려는 경우 불편합니다. 현재로서는 이를 위한 구체적인 방법은 없지만 스마트 포인터 또는 원시 포인터/참조 사용과 같은 알려진 메커니즘이 존재합니다. 프로미스를 복사하여 여러 곳에서 동시에 사용하려는 경우 QSharedPointer 을 기본으로 선택하는 것이 좋습니다. 원시 포인터나 참조는 어떤 의미에서는 더 쉽고 성능이 더 좋을 수 있지만(리소스 관리를 할 필요가 없으므로), 매달림이 발생할 수 있습니다.

다음은 하나의 프로미스를 여러 스레드에서 사용하는 방법의 예입니다:

    const auto sharedPromise = std::make_shared<QPromise<int>>();
    QFuture<int> future = sharedPromise->future();

    // ...

    sharedPromise->start();

    // here, QPromise is shared between threads via a smart pointer
    const std::unique_ptr<QThread> threads[] = {
        std::unique_ptr<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(0, 0);  // adds value 0 by index 0
        }, sharedPromise)),
        std::unique_ptr<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(-1, 1);  // adds value -1 by index 1
        }, sharedPromise)),
        std::unique_ptr<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(-2, 2);  // adds value -2 by index 2
        }, sharedPromise)),
        // ...
    };
    // start all threads
    for (auto& t : threads)
        t->start();

    // ...

    future.resultAt(0);  // waits until result at index 0 becomes available. returns value  0
    future.resultAt(1);  // waits until result at index 1 becomes available. returns value -1
    future.resultAt(2);  // waits until result at index 2 becomes available. returns value -2

    sharedPromise->finish();

QFuture 를참조하세요 .

멤버 함수 문서

bool QPromise::addResult(T &&result, int index = -1)

bool QPromise::addResult(const T &result, int index = -1)

와 동일

emplaceResultAt(index, result);            // first overload
emplaceResultAt(index, std::move(result)); // second overload

또는 index == -1 (기본값)인 경우

emplaceResult(result);            // first overload
emplaceResult(std::move(result)); // second overload

emplaceResultAt(), emplaceResult() 및 addResults()도 참조하세요 .

`[since 6.6]` template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResult(Args &&... args)

`[since 6.6]` template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResultAt(int index, Args &&... args)

args... 에서 구성된 결과를 index 위치(emplaceResultAt()) 또는 컬렉션의 끝(emplaceResult())에 있는 내부 결과 컬렉션에 추가합니다.

결과가 컬렉션에 추가되면 true 을 반환합니다.

이 프로미스가 취소되거나 완료된 상태이거나 결과가 거부된 경우 false 를 반환합니다. addResult()는 컬렉션에 동일한 인덱스에 저장된 다른 결과가 이미 있는 경우 결과 추가를 거부합니다.

이러한 함수는 T 에서 구성 가능한 경우에만 과부하 해결에 참여합니다. args....

QFuture::resultAt()를 호출하여 특정 인덱스에서 결과를 얻을 수 있습니다.

참고: 임의의 인덱스를 지정하고 해당 인덱스에서 결과를 요청할 수 있습니다. 그러나 일부 QFuture 메서드는 연속적인 결과로 작동합니다. 예를 들어 QFuture::resultCount() 또는 QFuture::const_iterator 을 사용하는 반복적 접근 방식이 있습니다. 인덱스 간격이 있는지 여부를 고려하지 않고 사용 가능한 모든 결과를 얻으려면 QFuture::results()을 사용합니다.

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

addResult() 및 addResults()도 참조하십시오 .

QPromise::QPromise()

기본 상태로 QPromise를 구성합니다.

QPromise::QPromise(QPromise<T> &&other)

이동은 other 에서 새 QPromise를 구성합니다.

operator=()도 참조하세요 .

QPromise::~QPromise()

프라미스를 파괴합니다.

참고: 사용자가 finish()를 미리 호출하지 않는 한 프로미스는 소멸 시 취소된 상태로 암시적으로 전환됩니다.

`[since 6.6]` bool QPromise::addResults(const QList<T> &results)

내부 결과 컬렉션 끝에 results 을 추가합니다.

results 이 컬렉션에 추가되면 true 을 반환합니다.

이 프로미스가 취소되거나 완료된 상태이면 false 을 반환합니다.

이는 개별 addResult() 호출의 경우처럼 results 에 포함된 요소당 한 번이 아니라 addResults() 호출당 한 번만 관련 퓨처에 알림이 전송되므로 addResult() 루핑보다 더 효율적입니다. 그러나 각 요소의 계산에 시간이 걸리면 수신 측 코드(퓨처)는 모든 결과가 보고될 때까지 진행하지 못하므로 연속된 요소의 계산이 비교적 빠른 경우에만 이 함수를 사용하세요.

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

addResult()도 참조하세요 .

void QPromise::finish()

계산이 완료되었음을 보고합니다. 완료되면 addResult()를 호출할 때 새 결과가 추가되지 않습니다. 이 메서드는 start()와 함께 사용됩니다.

QFuture::isFinished(), QFuture::waitForFinished() 및 start()도 참조하세요 .

QFuture<T> QPromise::future() const

이 약속과 관련된 미래를 반환합니다.

bool QPromise::isCanceled() const

QFuture::cancel() 함수로 계산이 취소되었는지 여부를 반환합니다. 반환된 값 true 은 계산을 완료하고 finish()을 호출해야 함을 나타냅니다.

참고: 취소 후에도 현재 사용 가능한 결과는 계속 액세스할 수 있지만 addResult() 호출 시 새 결과가 추가되지는 않습니다.

void QPromise::setException(const QException &e)

예외 e 를 계산의 결과로 설정합니다.

참고: 계산 실행 중에 예외를 최대 한 번만 설정할 수 있습니다.

참고: 이 메서드는 QFuture::cancel() 또는 finish() 이후에는 적용되지 않습니다.

isCanceled()도 참조하세요 .

void QPromise::setException(std::__exception_ptr::exception_ptr e)

과부하가 걸린 기능입니다.

void QPromise::setProgressRange(int minimum, int maximum)

계산의 진행률 범위를 minimum 과 maximum 사이로 설정합니다.

maximum 이 minimum 보다 작으면 minimum 이 유일한 법적 값이 됩니다.

진행률 값은 minimum 로 재설정됩니다.

setProgressRange(0, 0)를 사용하여 진행률 범위 사용을 비활성화할 수 있습니다. 이 경우 진행률 값도 0으로 재설정됩니다.

QFuture::progressMinimum(), QFuture::progressMaximum() 및 QFuture::progressValue()도 참조하세요 .

void QPromise::setProgressValue(int progressValue)

계산의 진행률 값을 progressValue 으로 설정합니다. 진행률 값만 증가시킬 수 있습니다. 이는 setProgressValueAndText(progressValue, QString())를 호출할 때 편리하게 사용할 수 있는 메서드입니다.

progressValue 가 진행률 범위를 벗어나는 경우 이 메서드는 아무런 효과가 없습니다.

QFuture::progressValue() 및 setProgressRange()도 참조하세요 .

void QPromise::setProgressValueAndText(int progressValue, const QString &progressText)

계산의 진행률 값과 진행률 텍스트를 각각 progressValue 및 progressText 으로 설정합니다. 진행률 값만 증가시킬 수 있습니다.

참고: 프라미스가 취소 또는 완료 상태인 경우에는 이 함수가 적용되지 않습니다.

QFuture::progressValue(), QFuture::progressText(), QFuture::cancel(), finish()도 참조하세요 .

void QPromise::start()

계산이 시작되었음을 보고합니다. QFuture 메서드는 이 정보에 의존하므로 이 메서드를 호출하는 것은 계산의 시작을 알리는 데 중요합니다.

참고: 새로 생성된 스레드에서 start()를 호출할 때는 각별한 주의가 필요합니다. 이러한 경우 스레드 스케줄링의 구현 세부 사항으로 인해 호출이 자연스럽게 지연될 수 있습니다.

QFuture::isStarted(), QFuture::waitForFinished() 및 finish()도 참조하세요 .

void QPromise::suspendIfRequested()

조건부로 현재 실행 스레드를 일시 중단하고 QFuture 의 해당 메서드에 의해 재개되거나 취소될 때까지 기다립니다. QFuture::suspend() 또는 다른 관련 메서드에서 계산 일시 중단을 요청하지 않는 한 이 메서드는 차단하지 않습니다. 실행이 일시 중단되었는지 확인하려면 QFuture::isSuspended()를 사용합니다.

참고: 여러 스레드에서 동일한 프로미스를 사용하는 경우, 프로미스가 있는 스레드 중 하나 이상이 일시 중단되는 즉시 QFuture::isSuspended()는 true 이 됩니다.

다음 코드 스니펫은 일시 중단 메커니즘의 사용법을 보여줍니다:

    // Create promise and future
    QPromise<int> promise;
    QFuture<int> future = promise.future();

    promise.start();
    // Start a computation thread that supports suspension and cancellation
    const std::unique_ptr<QThread> thread(QThread::create([] (QPromise<int> promise) {
        for (int i = 0; i < 100; ++i) {
            promise.addResult(i);
            promise.suspendIfRequested();   // support suspension
            if (promise.isCanceled())       // support cancellation
                break;
        }
        promise.finish();
    }, std::move(promise)));
    thread->start();

QFuture::suspend()는 연결된 프라미스를 일시 중단하도록 요청합니다:

    future.suspend();

QFuture::isSuspended()가 true 이 되면 중간 결과를 얻을 수 있습니다:

    future.resultCount();  // returns some number between 0 and 100
    for (int i = 0; i < future.resultCount(); ++i) {
        // process results available before suspension
    }

일시 중단되면 대기 중인 계산을 재개하거나 취소할 수 있습니다:

    future.resume();  // resumes computation, this call will unblock the promise
    // alternatively, call future.cancel() to stop the computation

    future.waitForFinished();
    future.results();  // returns all computation results - array of values from 0 to 99

QFuture::resume(), QFuture::cancel(), QFuture::setSuspended(), QFuture::toggleSuspended()도 참조하세요 .

`[noexcept]` void QPromise::swap(QPromise<T> &other)

이 약속을 other 로 바꿉니다. 이 작업은 매우 빠르며 실패하지 않습니다.

`[noexcept]` QPromise<T> &QPromise::operator=(QPromise<T> &&other)

이동은 other 을 이 프로미스에 할당하고 이 프로미스에 대한 참조를 반환합니다.

© 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.

QPromise Class

공용 함수

상세 설명

멤버 함수 문서

bool QPromise::addResult(T &&result, int index = -1)

bool QPromise::addResult(const T &result, int index = -1)

[since 6.6] template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResult(Args &&... args)

[since 6.6] template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResultAt(int index, Args &&... args)

QPromise::QPromise()

QPromise::QPromise(QPromise<T> &&other)

QPromise::~QPromise()

[since 6.6] bool QPromise::addResults(const QList<T> &results)

void QPromise::finish()

QFuture<T> QPromise::future() const

bool QPromise::isCanceled() const

void QPromise::setException(const QException &e)

void QPromise::setException(std::__exception_ptr::exception_ptr e)

void QPromise::setProgressRange(int minimum, int maximum)

void QPromise::setProgressValue(int progressValue)

void QPromise::setProgressValueAndText(int progressValue, const QString &progressText)

void QPromise::start()

void QPromise::suspendIfRequested()

[noexcept] void QPromise::swap(QPromise<T> &other)

[noexcept] QPromise<T> &QPromise::operator=(QPromise<T> &&other)

`[since 6.6]` template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResult(Args &&... args)

`[since 6.6]` template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResultAt(int index, Args &&... args)

`[since 6.6]` bool QPromise::addResults(const QList<T> &results)

`[noexcept]` void QPromise::swap(QPromise<T> &other)

`[noexcept]` QPromise<T> &QPromise::operator=(QPromise<T> &&other)