QPromise Class
template <typename T> class QPromiseLa clase QPromise proporciona una forma de almacenar los resultados de los cálculos a los que se puede acceder mediante QFuture. Más...
| Cabecera: | #include <QPromise> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Desde: | Qt 6.0 |
- Lista de todos los miembros, incluyendo los heredados
- QPromise es parte de la clase Threading Classes.
Nota: Todas las funciones de esta clase son thread-safe.
Funciones Públicas
| 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) |
Descripción Detallada
QPromise proporciona una forma sencilla de comunicar el progreso y los resultados del cálculo definido por el usuario a QFuture de forma asíncrona. Para que la comunicación funcione, QFuture debe ser construido por QPromise.
Puedes utilizar cargas de trabajo basadas en QPromise como alternativa a Qt Concurrent cuando se necesita un control de grano fino o basta con una primitiva de comunicación de alto nivel que acompañe a QFuture.
El caso más simple de colaboración entre promesa y futuro sería una comunicación de un único resultado:
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
Por diseño, QPromise es un objeto de sólo movimiento. Este comportamiento ayuda a asegurar que cada vez que la promesa se destruye, el objeto futuro asociado es notificado y no esperará eternamente a que los resultados estén disponibles. Sin embargo, esto es inconveniente si uno quiere usar la misma promesa para notificar resultados desde diferentes hilos. De momento no hay una forma específica de hacerlo, pero existen mecanismos conocidos, como el uso de punteros inteligentes o punteros/referencias sin procesar. QSharedPointer es una buena opción por defecto si se quiere copiar la promesa y utilizarla en varios sitios simultáneamente. Los punteros crudos o referencias son, en cierto sentido, más fáciles, y probablemente rindan mejor (ya que no hay necesidad de hacer una gestión de recursos) pero pueden llevar a dangling.
Aquí hay un ejemplo de cómo una promesa puede ser usada en múltiples hilos:
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();
Véase también QFuture.
Documentación de funciones miembro
QPromise::QPromise()
Construye una QPromise con un estado por defecto.
QPromise::QPromise(QPromise<T> &&other)
Move construye una nueva QPromise a partir de other.
Véase también operator=().
QPromise::~QPromise()
Destruye la promesa.
Nota: La promesa pasa implícitamente a un estado cancelado en el momento de la destrucción a menos que el usuario llame antes a finish().
bool QPromise::addResult(const T &result, int index = -1)
bool QPromise::addResult(T &&result, int index = -1)
Igual que
emplaceResultAt(index, result); // first overload emplaceResultAt(index, std::move(result)); // second overload
o, si index == -1 (por defecto)
emplaceResult(result); // first overload emplaceResult(std::move(result)); // second overload
Véase también emplaceResultAt(), emplaceResult() y addResults().
[since 6.6] bool QPromise::addResults(const QList<T> &results)
Añade results al final de la colección interna de resultados.
Devuelve true cuando se añade results a la colección.
Devuelve false cuando esta promesa está en estado cancelado o finalizado.
Esto es más eficiente que hacer un bucle sobre addResult(), porque los futuros asociados serán notificados sólo una vez por cada llamada a addResults(), en lugar de una vez por cada elemento contenido en results, como sería el caso con llamadas individuales a addResult(). Pero si el cálculo de cada elemento lleva tiempo, entonces el código en el extremo receptor (futuro) no puede progresar hasta que se notifiquen todos los resultados, así que utilice esta función sólo si el cálculo de elementos consecutivos es relativamente rápido.
Esta función se introdujo en Qt 6.6.
Véase también addResult().
[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] template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResult(Args &&... args)
Añade un resultado construido a partir de args... a la colección interna de resultados en la posición index (emplaceResultAt()) o al final de la colección (emplaceResult()).
Devuelve true cuando el resultado se ha añadido a la colección.
Devuelve false cuando esta promesa está en estado cancelado o finalizado o cuando el resultado fue rechazado. addResult() rechaza añadir un resultado si ya hay otro resultado en la colección almacenado en el mismo índice.
Estas funciones sólo participan en resoluciones de sobrecarga si T es construible a partir de args....
Puede obtener un resultado en un índice específico llamando a QFuture::resultAt().
Nota: Es posible especificar un índice arbitrario y solicitar un resultado en ese índice. Sin embargo, algunos métodos de QFuture operan con resultados continuos. Por ejemplo, los enfoques iterativos que utilizan QFuture::resultCount() o QFuture::const_iterator. Para obtener todos los resultados disponibles sin pensar si hay huecos de índice o no, utilice QFuture::results().
Estas funciones se introdujeron en Qt 6.6.
Véase también addResult() y addResults().
void QPromise::finish()
Informa de que el cálculo ha finalizado. Una vez finalizado, no se añadirán nuevos resultados al llamar a addResult(). Este método acompaña a start().
Véase también QFuture::isFinished(), QFuture::waitForFinished() y start().
QFuture<T> QPromise::future() const
Devuelve un futuro asociado a esta promesa.
bool QPromise::isCanceled() const
Devuelve si el cómputo ha sido cancelado con la función QFuture::cancel(). El valor devuelto true indica que se debe finalizar el cómputo y llamar a finish().
Nota: Tras la cancelación, se puede seguir accediendo a los resultados actualmente disponibles mediante un futuro, pero no se añadirán nuevos resultados al llamar a addResult().
void QPromise::setException(const QException &e)
Establece la excepción e como resultado del cálculo.
Nota: Puedes establecer como máximo una excepción a lo largo de la ejecución del cálculo.
Nota: Este método no tiene efecto después de QFuture::cancel() o finish().
Véase también isCanceled().
void QPromise::setException(std::__exception_ptr::exception_ptr e)
Se trata de una función sobrecargada.
void QPromise::setProgressRange(int minimum, int maximum)
Establece el rango de progreso del cálculo entre minimum y maximum.
Si maximum es menor que minimum, minimum se convierte en el único valor legal.
El valor de progreso se restablece a minimum.
El uso del rango de progreso puede desactivarse mediante setProgressRange(0, 0). En este caso, el valor de progreso también se restablece a 0.
Véase también QFuture::progressMinimum(), QFuture::progressMaximum(), y QFuture::progressValue().
void QPromise::setProgressValue(int progressValue)
Establece el valor de progreso del cálculo en progressValue. Es posible incrementar sólo el valor de progreso. Este es un método de conveniencia para llamar a setProgressValueAndText(progressValue, QString()).
En caso de que progressValue caiga fuera del rango de progreso, este método no tiene efecto.
Véase también QFuture::progressValue() y setProgressRange().
void QPromise::setProgressValueAndText(int progressValue, const QString &progressText)
Establece el valor de progreso y el texto de progreso del cálculo en progressValue y progressText respectivamente. Es posible incrementar sólo el valor de progreso.
Nota: Esta función no tiene efecto si la promesa está en estado cancelado o finalizado.
Véase también QFuture::progressValue(), QFuture::progressText(), QFuture::cancel(), y finish().
void QPromise::start()
Informa de que se ha iniciado el cálculo. Llamar a este método es importante para indicar el comienzo del cálculo, ya que los métodos de QFuture dependen de esta información.
Nota: Se requiere atención extra cuando start() es llamado desde un hilo recién creado. En tal caso, la llamada puede retrasarse de forma natural debido a los detalles de implementación de la programación de hilos.
Véase también QFuture::isStarted(), QFuture::waitForFinished(), y finish().
void QPromise::suspendIfRequested()
Suspende condicionalmente el hilo de ejecución actual y espera hasta que se reanude o cancele mediante los métodos correspondientes de QFuture. Este método no se bloquea a menos que se solicite la suspensión del cálculo mediante QFuture::suspend() u otro método relacionado. Si desea comprobar que la ejecución se ha suspendido, utilice QFuture::isSuspended().
Nota: Cuando se utiliza la misma promesa en múltiples hilos, QFuture::isSuspended() se convierte en true tan pronto como al menos un hilo con la promesa se suspende.
Los siguientes fragmentos de código muestran el uso del mecanismo de suspensión:
// 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() solicita a la promesa asociada que se suspenda:
future.suspend();Después de que QFuture::isSuspended() se convierta en true, puedes obtener resultados intermedios:
future.resultCount(); // returns some number between 0 and 100 for (int i = 0; i < future.resultCount(); ++i) { // process results available before suspension }
Cuando se suspende, se puede reanudar o cancelar el cómputo en espera:
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
Véase también QFuture::resume(), QFuture::cancel(), QFuture::setSuspended(), y QFuture::toggleSuspended().
[noexcept] void QPromise::swap(QPromise<T> &other)
Intercambia esta promesa con other. Esta operación es muy rápida y nunca falla.
[noexcept] QPromise<T> &QPromise::operator=(QPromise<T> &&other)
Move asigna other a esta promesa y devuelve una referencia a esta promesa.
© 2026 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.
