QPromise Class
template <typename T> class QPromiseLa clase QPromise permite almacenar resultados de cálculos a los que puede acceder QFuture. Más información...
| Encabezado: | #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, incluidos los heredados
- QPromise forma parte de las clases de subprocesos.
Nota: Todas las funciones de esta clase son seguras para subprocesos.
Funciones públicas
| QPromise() | |
| QPromise(const QPromise<T> &) | |
| 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<T> & | operator=(const QPromise<T> &) |
Descripción detallada
QPromise es una clase de plantilla en la que el parámetro de plantilla « T » especifica el tipo de resultado que se puede almacenar y al que se puede acceder posteriormente mediante « QFuture ».
QPromise ofrece 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 creado por QPromise.
Se pueden utilizar cargas de trabajo basadas en QPromise como alternativa al Qt Concurrent framework cuando se necesita un control minucioso o basta con una primitiva de comunicación de alto nivel que acompañe a QFuture.
El caso más sencillo de colaboración entre «promise» y «future» 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 42Por diseño, QPromise es un objeto de «move-only». Este comportamiento ayuda a garantizar que, cada vez que se destruya la promesa, se notifique al objeto «future» asociado y este no espere indefinidamente a que los resultados estén disponibles. Sin embargo, esto resulta inconveniente si se desea utilizar la misma promesa para informar de resultados procedentes de diferentes subprocesos. Por el momento no existe una forma específica de hacerlo, pero sí existen mecanismos conocidos, como el uso de punteros inteligentes o punteros/referencias sin procesar. QSharedPointer es una buena opción por defecto si quieres copiar tu promesa y utilizarla en varios lugares simultáneamente. Los punteros o referencias sin tipo son, en cierto sentido, más sencillos y probablemente ofrecen un mejor rendimiento (ya que no es necesario gestionar los recursos), pero pueden dar lugar a punteros colgantes.
A continuación se muestra un ejemplo de cómo se puede utilizar una promesa en varios subprocesos:
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 de miembro
[default] QPromise::QPromise()
Crea un QPromise con un estado predeterminado.
[delete] QPromise::QPromise(const QPromise<T> &)
Crea una instancia de ` QPromise` mediante copia. Esta función se ha eliminado.
[default] QPromise::QPromise(QPromise<T> &&other)
La función «move» crea 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 al ser destruida, a menos que el usuario llame previamente a finish().
bool QPromise::addResult(T &&result, int index = -1)
bool QPromise::addResult(const T &result, int index = -1)
Es lo mismo que
emplaceResultAt(index, result); // first overload
emplaceResultAt(index, std::move(result)); // second overloado, si index == -1 (el valor por defecto)
emplaceResult(result); // first overload
emplaceResult(std::move(result)); // second overloadVé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 de resultados interna.
Devuelve true cuando se añaden results a la colección.
Devuelve false cuando esta promesa se encuentra en estado «cancelado» o «finalizado».
Esto es más eficiente que recorrer addResult(), ya que los futuros asociados recibirán una notificación única por cada llamada a addResults(), en lugar de una por cada elemento contenido en results, como ocurriría con llamadas individuales a addResult(). Sin embargo, si el cálculo de cada elemento lleva tiempo, el código en el extremo receptor (future) no podrá avanzar hasta que se hayan notificado todos los resultados, por lo que solo se debe utilizar esta función 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::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)
Añade un resultado creado 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 se encuentra en estado «cancelado» o «finalizado», o cuando el resultado ha sido rechazado. ` addResult()` rechaza la adición de un resultado si ya hay otro resultado en la colección almacenado en el mismo índice.
Estas funciones solo participan en la resolución de sobrecargas si T es construible a partir de args....
Puedes obtener un resultado en un índice específico llamando a QFuture::resultAt().
Nota: Es posible especificar un índice arbitrario y solicitar el 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 tener que preocuparse de si hay huecos en los índices o no, utiliza ` QFuture::results()`.
Estas funciones se introdujeron en Qt 6.6.
Véase también addResult() y addResults().
void QPromise::finish()
Indica que el cálculo ha finalizado. Una vez finalizado, no se añadirán nuevos resultados al llamar a ` addResult()`. Este método se utiliza junto con ` start()`.
Véanse también QFuture::isFinished(), QFuture::waitForFinished() y start().
QFuture<T> QPromise::future() const
Devuelve un «future» asociado a esta «promise».
bool QPromise::isCanceled() const
Devuelve si el cálculo se ha cancelado con la función QFuture::cancel(). El valor devuelto true indica que el cálculo debe finalizarse y que se debe llamar a finish().
Nota: Tras la cancelación, se podrá seguir accediendo a los resultados disponibles en ese momento mediante una futura llamada, 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: Solo se puede establecer como máximo una excepción durante toda la ejecución del cálculo.
Nota: Este método no tiene ningún efecto después de llamar a QFuture::cancel() o finish().
Véase también ` isCanceled()`.
void QPromise::setException(std::__exception_ptr::exception_ptr e)
Esta es 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 pasa a ser el único valor válido.
El valor de progreso se restablece a minimum.
El uso del rango de progreso se puede desactivar 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`. Solo es posible incrementar el valor de progreso. Se trata de un método de conveniencia para llamar a ` setProgressValueAndText(progressValue, QString())`.
En caso de que el valor de progreso ( progressValue ) se salga del rango de progreso, este método no tiene ningún 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 únicamente el valor de progreso.
Nota: Esta función no tiene ningún efecto si la promesa se encuentra en estado «cancelado» o «finalizado».
Véase también QFuture::progressValue(), QFuture::progressText(), QFuture::cancel() y finish().
void QPromise::start()
Indica que se ha iniciado el cálculo. Es importante llamar a este método para señalar el inicio del cálculo, ya que los métodos ` QFuture ` dependen de esta información.
Nota: Se debe prestarespecial atención cuando se llama a start() desde un hilo recién creado. En tal caso, la llamada podría 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 de forma condicional el hilo de ejecución actual y espera hasta que se reanude o se cancele mediante los métodos correspondientes de ` QFuture`. Este método no bloquea a menos que se solicite la suspensión del cálculo mediante ` QFuture::suspend()` u otro método relacionado. Si deseas comprobar que la ejecución se ha suspendido, utiliza ` QFuture::isSuspended()`.
Nota: Cuando se utiliza la misma promesa en varios hilos, QFuture::isSuspended() pasa a ser true en cuanto 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();Una vez que QFuture::isSuspended() se convierte 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 está suspendido, se puede reanudar o cancelar el cálculo pendiente:
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 99Véase también QFuture::resume(), QFuture::cancel(), QFuture::setSuspended() y QFuture::toggleSuspended().
[noexcept] void QPromise::swap(QPromise<T> &other)
Cambia esta promesa por other. Esta operación es muy rápida y nunca falla.
[noexcept] QPromise<T> &QPromise::operator=(QPromise<T> &&other)
La función «move» asigna « other » a esta promesa y devuelve una referencia a dicha promesa.
[delete] QPromise<T> &QPromise::operator=(const QPromise<T> &)
Asigna por copia other a esta instancia de QPromise. Esta función se ha eliminado.
© 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.