Класс QPromise

Класс QPromise предоставляет способ хранения результатов вычислений, к которым можно получить доступ с помощью QFuture. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются безопасными для многопоточного доступа.

Открытые функции

Подробное описание

QPromise предоставляет простой способ передачи прогресса и результатов пользовательских вычислений в QFuture в асинхронном режиме. Для работы связи, QFuture должен быть создан QPromise.

Вы можете использовать рабочие нагрузки на основе QPromise в качестве альтернативы Qt Concurrent фреймворку, когда требуется точный контроль или достаточно высокоуровневого коммуникационного примитива, сопровождающего QFuture.

Простейшим случаем взаимодействия promise и future будет передача единственного результата:

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

    QScopedPointer<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 — это объект, который можно только перемещать. Это поведение помогает гарантировать, что при уничтожении promise связанный объект future уведомляется и не будет ждать вечно, пока результаты не станут доступны. Однако это неудобно, если нужно использовать одну и ту же promise для отчета о результатах из разных потоков. В настоящее время нет специального способа сделать это, но существуют известные механизмы, такие как использование умных указателей или сырых указателей/ссылок. QSharedPointer — хороший выбор по умолчанию, если вы хотите скопировать promise и использовать её в нескольких местах одновременно. Сырые указатели или ссылки, в некотором смысле, проще и, вероятно, работают быстрее (так как нет необходимости управлять ресурсами), но могут привести к висячим ссылкам.

Вот пример того, как promise можно использовать в нескольких потоках:

    QSharedPointer<QPromise<int>> sharedPromise(new QPromise<int>());
    QFuture<int> future = sharedPromise->future();

    // ...

    // here, QPromise is shared between threads via a smart pointer
    QScopedPointer<QThread> threads[] = {
        QScopedPointer<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(0, 0);  // adds value 0 by index 0
        }, sharedPromise)),
        QScopedPointer<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(-1, 1);  // adds value -1 by index 1
        }, sharedPromise)),
        QScopedPointer<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

См. также QFuture.

Документация по функциям-членам

Добавляет result в внутренний набор результатов в позиции index. Если index не указан, result добавляется в конец набора.

Возвращает true при добавлении result в набор.

Возвращает false когда данная promise находится в состоянии отмены или завершения или когда result отклоняется. addResult() отклоняет result, если в наборе уже есть другой результат, сохранённый в том же индексе.

Вы можете получить результат по определённому индексу, вызвав QFuture::resultAt().

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

Перемещает конструктор нового QPromise из other.

См. также operator=().

QPromise::QPromise()

Создает QPromise в стандартном состоянии.

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

Перемещает присваивание other в эту promise и возвращает ссылку на эту promise.

QPromise::~QPromise()

Уничтожает promise.

void QPromise::finish()

Сообщает о завершении вычисления. После завершения новые результаты не будут добавляться при вызове addResult(). Этот метод сопровождает start().

См. также QFuture::isFinished(), QFuture::waitForFinished(), и start().

QFuture<T> QPromise::future() const

Возвращает future, связанную с этой promise.

bool QPromise::isCanceled() const

Возвращает, была ли отменена вычисление с помощью функции QFuture::cancel(). Возвращаемое значение true указывает, что вычисление должно быть завершено и finish() вызвано.

void QPromise::setException(const QException &e)

Устанавливает исключение e в качестве результата вычисления.

См. также isCanceled().

void QPromise::setException(std::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 полагаются на эту информацию.

См. также QFuture::isStarted(), QFuture::waitForFinished() и finish().

void QPromise::suspendIfRequested()

Условно приостанавливает текущий поток выполнения и ожидает возобновления или отмены соответствующими методами QFuture. Этот метод не блокирует, если вычисление не запрошено на приостановку QFuture::suspend() или другим родственным методом. Если вы хотите проверить, было ли выполнение приостановлено, используйте QFuture::isSuspended().

Следующие фрагменты кода демонстрируют использование механизма приостановки:

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

    promise.start();
    // Start a computation thread that supports suspension and cancellation
    QScopedPointer<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().

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

Меняет местами обещание other с этим обещанием. Эта операция очень быстрая и никогда не терпит неудач.