QFuture Class
template <typename T> class QFutureLa clase QFuture representa el resultado de un cálculo asíncrono. Más información...
| Encabezado: | #include <QFuture> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluidos los miembros heredados
- Miembros obsoletos
- QFuture forma parte de las clases de subprocesos.
Nota: Todas las funciones de esta clase son seguras para subprocesos, con las siguientes excepciones:
Tipos públicos
| class | const_iterator |
| ConstIterator |
Funciones públicas
| QFuture() | |
| QFuture(const QFuture<T> &other) | |
| ~QFuture() | |
| QFuture<T>::const_iterator | begin() const |
| void | cancel() |
(since 6.10) void | cancelChain() |
| QFuture<T>::const_iterator | constBegin() const |
| QFuture<T>::const_iterator | constEnd() const |
| QFuture<T>::const_iterator | end() const |
| bool | isCanceled() const |
| bool | isFinished() const |
| bool | isResultReadyAt(int index) const |
| bool | isRunning() const |
| bool | isStarted() const |
(since 6.0) bool | isSuspended() const |
(since 6.0) bool | isSuspending() const |
(since 6.0) bool | isValid() const |
(since 6.0) QFuture<T> | onCanceled(Function &&handler) |
(since 6.1) QFuture<T> | onCanceled(QObject *context, Function &&handler) |
(since 6.0) QFuture<T> | onFailed(Function &&handler) |
(since 6.1) QFuture<T> | onFailed(QObject *context, Function &&handler) |
| int | progressMaximum() const |
| int | progressMinimum() const |
| QString | progressText() const |
| int | progressValue() const |
| T | result() const |
| T | resultAt(int index) const |
| int | resultCount() const |
| QList<T> | results() const |
| void | resume() |
(since 6.0) void | setSuspended(bool suspend) |
(since 6.0) void | suspend() |
(since 6.0) T | takeResult() |
(since 6.0) QFuture<QFuture<T>::ResultType<Function>> | then(Function &&function) |
(since 6.1) QFuture<QFuture<T>::ResultType<Function>> | then(QObject *context, Function &&function) |
(since 6.0) QFuture<QFuture<T>::ResultType<Function>> | then(QThreadPool *pool, Function &&function) |
(since 6.0) QFuture<QFuture<T>::ResultType<Function>> | then(QtFuture::Launch policy, Function &&function) |
(since 6.0) void | toggleSuspended() |
(since 6.4) QFuture<U> | unwrap() |
| void | waitForFinished() |
| QFuture<T> & | operator=(const QFuture<T> &other) |
Descripción detallada
QFuture es una clase de plantilla en la que el parámetro de plantilla T especifica el tipo de resultados que produce el cálculo asíncrono.
QFuture permite sincronizar subprocesos con uno o más resultados que estarán listos en un momento posterior. El resultado puede ser de cualquier tipo que cuente con constructores por defecto, de copia y, posiblemente, de traslado. Si un resultado no está disponible en el momento de llamar a las funciones ` result()`, ` resultAt()`, ` results()` y ` takeResult()`, `QFuture` esperará hasta que el resultado esté disponible. Puedes utilizar la función ` isResultReadyAt()` para determinar si un resultado está listo o no. Para los objetos `QFuture` que informan de más de un resultado, la función ` resultCount()` devuelve el número de resultados consecutivos. Esto significa que siempre es seguro iterar por los resultados desde 0 hasta resultCount(). La función ` takeResult()` invalida un «future», y cualquier intento posterior de acceder a los resultados de dicho «future» da lugar a un comportamiento indefinido. La función ` isValid()` indica si se puede acceder a los resultados.
QFuture proporciona un iterador al estilo Java (QFutureIterator) y un iterador al estilo STL (QFuture::const_iterator). El uso de estos iteradores es otra forma de acceder a los resultados del futuro.
Si es necesario pasar el resultado de un cálculo asíncrono a otro, QFuture ofrece una forma cómoda de encadenar varios cálculos secuenciales mediante then(). onCanceled() se puede utilizar para añadir un controlador que se llamará si se cancela el QFuture. Además, onFailed() se puede utilizar para gestionar cualquier fallo que se haya producido en la cadena. Ten en cuenta que QFuture se basa en excepciones para la gestión de errores. Si no es posible utilizar excepciones, aún así puedes indicar el estado de error de QFuture haciendo que el tipo de error forme parte del tipo de QFuture. Por ejemplo, puedes utilizar std::variant, std::any o similares para almacenar el resultado o el fallo, o bien crear tu propio tipo personalizado.
El ejemplo siguiente muestra cómo se puede llevar a cabo la gestión de errores sin utilizar excepciones. Supongamos que queremos enviar una solicitud de red para obtener un archivo de gran tamaño desde una ubicación de red. A continuación, queremos escribirlo en el sistema de archivos y devolver su ubicación en caso de éxito. Ambas operaciones pueden fallar con diferentes errores. Por lo tanto, utilizamos ` std::variant ` para almacenar el resultado o el error:
using NetworkReply = std::variant<QByteArray, QNetworkReply::NetworkError>;
enum class IOError { FailedToRead, FailedToWrite };
using IOResult = std::variant<QString, IOError>;Y combinamos las dos operaciones utilizando ` then()`:
QFuture<IOResult> future = QtConcurrent::run([url] {
//...
return NetworkReply(QNetworkReply::TimeoutError);
}).then([](NetworkReply reply) {
if (auto error = std::get_if<QNetworkReply::NetworkError>(&reply))
return IOResult(IOError::FailedToRead);
auto data = std::get_if<QByteArray>(&reply);
// try to write *data and return IOError::FailedToWrite on failure
//...
});
auto result = future.result();
if (auto filePath = std::get_if<QString>(&result)) {
// do something with *filePath
}
else
{
// process the error
}Es posible encadenar varias continuaciones y controladores en cualquier orden. Por ejemplo:
QFuture<int> testFuture = someIntFuture;
auto resultFuture = testFuture.then([](int res) {
// Block 1
}).onCanceled([] {
// Block 2
}).onFailed([] {
// Block 3
}).then([] {
// Block 4
}).onFailed([] {
// Block 5
}).onCanceled([] {
// Block 6
});Dependiendo del estado de ` testFuture ` (cancelado, con excepción o con un resultado), se llamará a la siguiente ` onCanceled()`, ` onFailed()` o ` then()`. Así pues, si ` testFuture ` se ejecuta correctamente, se llamará a ` Block 1 `. Si esta también se ejecuta correctamente, se llamará a la siguiente ` then()` (Block 4). Si testFuture se cancela o falla con una excepción, se llamará, respectivamente, a Block 2 o a Block 3. A continuación, se llamará a la siguiente then(), y el proceso se repite.
Nota: Si se invoca Block 2 y lanza una excepción, el siguiente onFailed() (Block 3) se encargará de gestionarla. Si se invirtiera el orden de onFailed() y onCanceled(), el estado de excepción se propagaría a las siguientes continuaciones y, finalmente, sería capturado en Block 5.
En el siguiente ejemplo se elimina la primera llamada a onCanceled() (Block 2):
QFuture<int> testFuture = someIntFuture;
auto resultFuture = testFuture.then([](int res) {
// Block 1
}).onFailed([] {
// Block 3
}).then([] {
// Block 4
}).onFailed([] {
// Block 5
}).onCanceled([] {
// Block 6
});Si se cancela testFuture, su estado se propaga a la siguiente then(), que también se cancelará. Por lo tanto, en este caso se llamará a Block 6.
El «future» solo puede tener una continuación. Consideremos el siguiente ejemplo:
QPromise<int> p;
QFuture<int> f1 = p.future();
f1.then([](int) { qDebug("first"); });
QFuture<int> f2 = p.future();
f2.then([](int) { qDebug("second"); });
p.start();
p.addResult(42);
p.finish();En este caso, f1 y f2 son, en la práctica, el mismo objeto `QFuture`, ya que comparten el mismo estado interno. Como resultado, llamar a ` then ` en f2 sobrescribirá la continuación especificada para f1. Por lo tanto, solo se imprimirá "second" cuando se ejecute este código.
QFuture también ofrece formas de interactuar con un cálculo en ejecución. Por ejemplo, el cálculo se puede cancelar con la función ` cancel()`. Para suspender o reanudar el cálculo, utilice la función ` setSuspended()` o una de las funciones de conveniencia ` suspend()`, ` resume()` o ` toggleSuspended()`. Ten en cuenta que no todos los cálculos asíncronos en ejecución pueden cancelarse o suspenderse. Por ejemplo, el «future» devuelto por QtConcurrent::run() no puede cancelarse; sin embargo, el «future» devuelto por QtConcurrent::mappedReduced() sí puede.
La información sobre el progreso se obtiene mediante las funciones progressValue(), progressMinimum(), progressMaximum() y progressText(). La función waitForFinished() hace que el hilo que la invoca se bloquee y espere a que finalice el cálculo, lo que garantiza que todos los resultados estén disponibles.
El estado del cálculo representado por un QFuture puede consultarse mediante las funciones isCanceled(), isStarted(), isFinished(), isRunning(), isSuspending() o isSuspended().
QFuture<void> está especializado para no contener ninguna de las funciones de obtención de resultados. Cualquier QFuture<T> también se puede asignar o copiar en un QFuture<void>. Esto resulta útil si solo se necesita información sobre el estado o el progreso, y no los datos del resultado real.
Para interactuar con tareas en ejecución mediante señales y ranuras, utiliza ` QFutureWatcher`.
También puede utilizar ` QtFuture::connect()` para conectar señales a un objeto `QFuture`, que se resolverá cuando se emita una señal. Esto permite trabajar con señales como si se tratara de objetos `QFuture`. Por ejemplo, si lo combina con ` then()`, puede asociar varias continuaciones a una señal, las cuales se invocarán en el mismo hilo o en un nuevo hilo.
Las funciones QtFuture::whenAll() y QtFuture::whenAny() pueden utilizarse para combinar varios futuros y realizar un seguimiento de cuándo se completa el último o el primero de ellos.
Se puede crear un objeto `QFuture` listo con un valor o un objeto `QFuture` que contenga una excepción utilizando las funciones de conveniencia ` QtFuture::makeReadyVoidFuture()`, ` QtFuture::makeReadyValueFuture()`, ` QtFuture::makeReadyRangeFuture()` y ` QtFuture::makeExceptionalFuture()`.
Nota: Algunas API (véase QFuture::then() o varias sobrecargas del método QtConcurrent ) permiten programar el cálculo en un grupo de subprocesos específico. Sin embargo, QFuture implementa un algoritmo de «robo de trabajo» para evitar interbloqueos y optimizar el uso de los subprocesos. Como resultado, los cálculos pueden ejecutarse directamente en el subproceso que solicita el resultado de QFuture.
Nota: Para iniciar un cálculo y almacenar los resultados en un QFuture, utiliza QPromise o una de las API del Qt Concurrent marco.
Véase también QPromise, QtFuture::connect(), QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), QtFuture::makeExceptionalFuture(), QFutureWatcher y Qt Concurrent.
Documentación sobre los tipos de miembros
QFuture::ConstIterator
Sinónimo al estilo Qt de « QFuture::const_iterator ».
Documentación de la función miembro
QFuture::QFuture()
Crea un futuro vacío y anulado.
QFuture::QFuture(const QFuture<T> &other)
Crea una copia de other.
Véase también operator=().
QFuture::~QFuture()
Destruye el futuro.
Ten en cuenta que esto ni espera ni cancela el cálculo asíncrono. Utiliza waitForFinished() o QFutureSynchronizer cuando necesites asegurarte de que el cálculo se haya completado antes de que se destruya el futuro.
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::begin() const
Devuelve un iterador constante al estilo STL que apunta al primer resultado del futuro.
Véase también constBegin() y end().
void QFuture::cancel()
Cancela el cálculo asíncrono representado por este «future». Ten en cuenta que la cancelación es asíncrona. Utiliza ` waitForFinished()` después de llamar a `cancel()` cuando necesites una cancelación síncrona.
Se puede seguir accediendo a los resultados disponibles actualmente en un «future» cancelado, pero no se obtendrán nuevos resultados tras llamar a esta función. Cualquier objeto ` QFutureWatcher ` que esté supervisando este «future» no emitirá señales de progreso ni de resultado listo en un «future» cancelado.
Ten en cuenta que no todos los cálculos asíncronos en ejecución pueden cancelarse. Por ejemplo, el futuro devuelto por QtConcurrent::run() no puede cancelarse; sin embargo, el futuro devuelto por QtConcurrent::mappedReduced() sí puede.
Véase también cancelChain().
[since 6.10] void QFuture::cancelChain()
Cancela toda la cadena de continuaciones. Todos los futuros ya completados permanecen inalterados y sus resultados siguen estando disponibles. Se cancela cada continuación pendiente y se invoca su manejador onCanceled(), si existe en la cadena de continuaciones.
auto f = QtConcurrent::run([] {/*...*/})
.then([]{
// Then 1
})
.then([]{
// Then 2
})
.onCanceled([]{
// OnCanceled 1
})
.then([]{
// Then 3
})
.then([]{
// Then 4
})
.onCanceled([]{
// OnCanceled 2
});
//...
f.cancelChain();En el ejemplo, si la cadena se cancela antes de que se ejecute la continuación Then 2, se invocarán ambos controladores de cancelación: OnCanceled 1 y OnCanceled 2.
Si la cadena se cancela después de ` Then 2`, pero antes de ` Then 4`, solo se invocará ` OnCanceled 2 `.
Nota: Cuando se invoca sobre un «future» ya finalizado, este método no tiene ningún efecto. Se recomienda utilizarlo sobre el objeto ` QFuture ` que representa toda la cadena de continuaciones, tal y como se muestra en el ejemplo anterior.
Si alguna de las continuaciones de la cadena ejecuta un cálculo asíncrono y devuelve un ` QFuture ` que la representa, la llamada a ` cancelChain() ` no se propagará a dicho cálculo anidado una vez que este se haya iniciado. El motivo es que el futuro solo estará disponible en la cadena de continuaciones cuando se haya completado el futuro exterior, pero la cancelación podría producirse cuando tanto el futuro exterior como el anidado aún estén a la espera de que finalicen sus cálculos. En tales casos, es necesario capturar y cancelar explícitamente el futuro anidado.
QFuture<void> nested;
auto f = createFuture()
.then([&]{
nested = runNestedComputation();
// do some other work
return nested;
})
.unwrap()
.then([]{
// other continuation
})
.onCanceled([]{
// handle cancellation
});
//...
f.cancelChain();
nested.cancel();En este ejemplo, si « runNestedComputation() » ya está en curso, solo se puede cancelar llamando a « nested.cancel() ».
Esta función se introdujo en Qt 6.10.
Véase también cancel().
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constBegin() const
Devuelve un iterador constante al estilo STL que apunta al primer resultado del futuro.
Véase también ` begin()` y ` constEnd()`.
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constEnd() const
Devuelve un iterador constante al estilo STL que apunta al resultado imaginario posterior al último resultado en el futuro.
Véase también constBegin() y end().
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::end() const
Devuelve un iterador const al estilo STL que apunta al resultado imaginario posterior al último resultado en el futuro.
Véase también begin() y constEnd().
bool QFuture::isCanceled() const
Devuelve ` true ` si el cálculo asíncrono se ha cancelado con la función ` cancel()`; en caso contrario, devuelve ` false`.
Ten en cuenta que el cálculo puede seguir ejecutándose aunque esta función devuelva true. Consulta cancel() para obtener más detalles.
bool QFuture::isFinished() const
Devuelve « true » si el cálculo asíncrono representado por este «future» ha finalizado; en caso contrario, devuelve « false ».
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> bool QFuture::isResultReadyAt(int index) const
Devuelve true si el resultado en index está disponible de inmediato; en caso contrario, devuelve false.
Nota: La llamada a esta función da lugar a un comportamiento indefinido si isValid() devuelve false para este QFuture. Si este QFuture aún no se ha iniciado, llame a waitForFinished() antes de llamar a esta función para evitar un comportamiento indefinido.
Véase también resultAt(), resultCount() y takeResult().
bool QFuture::isRunning() const
Devuelve ` true ` si el cálculo asíncrono representado por este «future» se está ejecutando en ese momento; en caso contrario, devuelve ` false`.
bool QFuture::isStarted() const
Devuelve ` true ` si se ha iniciado el cálculo asíncrono representado por este «future»; en caso contrario, devuelve ` false`.
[since 6.0] bool QFuture::isSuspended() const
Devuelve « true » si se ha solicitado la suspensión del cálculo asíncrono y esta está en vigor, lo que significa que no se esperan más resultados ni cambios en el progreso.
Esta función se introdujo en Qt 6.0.
Véase también setSuspended(), toggleSuspended() y isSuspending().
[since 6.0] bool QFuture::isSuspending() const
Devuelve ` true ` si el cálculo asíncrono se ha suspendido con la función ` suspend()`, pero la tarea aún no se ha suspendido y el cálculo sigue en ejecución. En caso contrario, devuelve ` false `.
Para comprobar si la suspensión está realmente activa, utiliza en su lugar isSuspended() .
Esta función se introdujo en Qt 6.0.
Véase también setSuspended(), toggleSuspended() y isSuspended().
[since 6.0] bool QFuture::isValid() const
Devuelve « true » si se puede acceder a uno o varios resultados u obtenerlos de este objeto « QFuture ». Devuelve « false » si el objeto « QPromise » relacionado aún no se ha iniciado o si el resultado ya se ha obtenido del futuro.
Nota: El valor de retorno de esta función solo indica si el resultado del «future» se puede consumir, no si está listo. Esta función devolverá true cuando se haya iniciado el « QPromise » relacionado, pero el resultado aún no esté listo. Para comprobar si está listo, llama a isResultReadyAt() o a isFinished().
Esta función se introdujo en Qt 6.0.
Véase también takeResult(), result(), results(), resultAt(), isFinished() y isResultReadyAt().
[since 6.0] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(Function &&handler)
Asigna un manipulador de cancelación ( handler ) a este futuro. El futuro devuelto se comporta exactamente igual que este futuro (tiene el mismo estado y resultado), a menos que este futuro se cancele. El manipulador de cancelación ( handler ) es una función que no toma argumentos y devuelve un valor del tipo empaquetado por este futuro. Tras la cancelación, el futuro devuelto empaqueta el valor devuelto por handler.
Si se adjunta antes de la cancelación, handler se invocará en el mismo hilo que notifica que el futuro ha finalizado tras la cancelación. Si el manejador se adjunta después de que este futuro ya haya sido cancelado, se invocará inmediatamente en el hilo que ejecuta onCanceled(). Por lo tanto, el manejador no siempre puede dar por sentado en qué hilo se ejecutará. Utiliza la sobrecarga que toma un objeto de contexto si deseas controlar en qué hilo se invoca el controlador.
El siguiente ejemplo muestra cómo asociar un controlador de cancelación:
QFuture<int> testFuture /*...*/;
auto resultFuture = testFuture.then([](int res) {
// Block 1
//...
return 1;
}).then([](int res) {
// Block 2
//...
return 2;
}).onCanceled([] {
// Block 3
//...
return -1;
});Si se cancela testFuture, se llamará a Block 3 y resultFuture tendrá como resultado -1. A diferencia de testFuture, no estará en estado Canceled. Esto significa que puedes obtener su resultado, asociarle continuaciones, etc.
Ten en cuenta también que puedes cancelar la cadena de continuaciones mientras se están ejecutando a través del futuro que inició la cadena. Supongamos que se ha llamado a testFuture.cancel() mientras Block 1 ya se está ejecutando. La siguiente continuación detectará que se ha solicitado la cancelación, por lo que se omitirá Block 2 y se llamará al controlador de cancelación (Block 3).
Nota: Este método devuelve un nuevo ` QFuture ` que representa el resultado de la cadena de continuaciones. La cancelación del propio « QFuture » resultante no invocará el controlador de cancelación de la cadena que condujo a él. Esto significa que, si se llama a « resultFuture.cancel() », no se llamará a « Block 3 »: dado que « resultFuture » es el «future» que resulta de adjuntar el controlador de cancelación a « testFuture », no se ha adjuntado ningún controlador de cancelación al propio « resultFuture ». Solo la cancelación de « testFuture » o de los «futures» devueltos por las continuaciones adjuntas antes de la llamada a « onCancelled() » puede activar « Block 3 ».
Esta función se introdujo en Qt 6.0.
Véase también then() y onFailed().
[since 6.1] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(QObject *context, Function &&handler)
Asigna una función de cancelación ` handler ` a este «future», que se invocará cuando se cancele el «future». La función ` handler ` es una función invocable que no admite argumentos. Se invocará en el hilo del objeto ` context `. Esto puede resultar útil si es necesario gestionar la cancelación en un hilo específico.
Si el objeto ` context ` se destruye antes de que la cadena haya finalizado, el «future» se cancela. Consulte ` then()` para obtener más detalles.
Nota: Al llamar a este método, debe garantizarse que el objeto ` context ` permanezca activo durante la configuración de la cadena.
Consulte la documentación de la otra sobrecarga para obtener más detalles sobre ` handler`.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.1.
Véanse también then() y onFailed().
[since 6.0] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(Function &&handler)
Asigna un controlador de errores a este «future», para gestionar cualquier excepción. El «future» devuelto se comporta exactamente igual que este «future» (tiene el mismo estado y resultado), a menos que este «future» falle por una excepción.
La función « handler » es una función que admite ningún argumento o un solo argumento, para filtrar por tipos de error específicos, de forma similar a la instrucción «catch ». Devuelve un valor del tipo empaquetado por este «future». Tras el fallo, el «future» devuelto empaqueta el valor devuelto por « handler ».
El controlador solo se invocará si se lanza una excepción. Si la excepción se lanza después de que se haya asociado este controlador, este se ejecutará en el hilo que informa de que el futuro ha finalizado como consecuencia de la excepción. Si el manejador se asocia después de que este futuro ya haya fallado, se invocará inmediatamente, en el hilo que ejecuta onFailed(). Por lo tanto, el manejador no siempre puede dar por sentado en qué hilo se ejecutará. Utiliza la sobrecarga que toma un objeto de contexto si deseas controlar en qué hilo se invoca el manejador.
El siguiente ejemplo muestra cómo asociar un manejador de fallos:
QFuture<int> future = someIntFuture;
auto resultFuture = future.then([](int res) {
//...
throw Error();
//...
return res;
}).onFailed([](const Error &e) {
// Handle exceptions of type Error
//...
return -1;
}).onFailed([] {
// Handle all other types of errors
//...
return -1;
});
auto result = resultFuture.result(); // result is -1Si hay varios controladores asociados, se invocará el primer controlador que coincida con el tipo de excepción lanzada. Por ejemplo:
QFuture<int> future = someIntFuture;
future.then([](int res) {
//...
throw std::runtime_error("message");
//...
}).onFailed([](const std::exception &e) {
// This handler will be invoked
return -1;
}).onFailed([](const std::runtime_error &e) {
// This handler won't be invoked, because of the handler above.
return -1;
});Si ninguno de los manejadores coincide con el tipo de excepción lanzada, la excepción se propagará al futuro resultante:
QFuture<int> future = someIntFuture;
auto resultFuture = future.then([](int res) {
//...
throw Error("message");
//...
return res;
}).onFailed([](const std::exception &e) {
// Won't be invoked
return -1;
}).onFailed([](const QException &e) {
// Won't be invoked
return -1;
});
try {
auto result = resultFuture.result();
} catch(QException &someException) {
// Handle the exception
}Nota: Siemprepuedes asociar un manejador que no admita argumentos para gestionar todos los tipos de excepción y evitar escribir el bloque try-catch.
Esta función se introdujo en Qt 6.0.
Véase también then() y onCanceled().
[since 6.1] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(QObject *context, Function &&handler)
Asigna un controlador de errores a este «future», para gestionar cualquier excepción que el «future» genere o que ya haya generado. Devuelve un objeto « QFuture » del mismo tipo que este «future». El controlador solo se invocará en caso de excepción, en el hilo del objeto context. Esto puede resultar útil si es necesario gestionar el error en un hilo específico. Por ejemplo:
// somewhere in the main thread
auto future = QtConcurrent::run([] {
// This will run in a separate thread
//...
throw std::exception();
}).onFailed(this, [] {
// Update UI elements
});El controlador de fallos asociado a ` QtConcurrent::run ` actualiza los elementos de la interfaz de usuario y no puede invocarse desde un hilo que no sea de la interfaz gráfica. Por lo tanto, se proporciona ` this ` como contexto a ` .onFailed()`, para garantizar que se invoque en el hilo principal.
Si el ` context ` se destruye antes de que la cadena haya finalizado, el `future` se cancela. Consulte ` then()` para obtener más detalles.
Nota: Al llamar a este método, debe garantizarse que el ` context ` permanezca activo durante la configuración de la cadena.
Consulte la documentación de la otra sobrecarga para obtener más detalles sobre handler.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.1.
Véanse también then() y onCanceled().
int QFuture::progressMaximum() const
Devuelve el valor máximo de progressValue().
Véase también progressValue() y progressMinimum().
int QFuture::progressMinimum() const
Devuelve el valor mínimo de progressValue().
Véase también progressValue() y progressMaximum().
QString QFuture::progressText() const
Devuelve la representación textual (opcional) del progreso tal y como lo comunica el cálculo asíncrono.
Ten en cuenta que no todos los cálculos proporcionan una representación textual del progreso y, por lo tanto, esta función puede devolver una cadena vacía.
int QFuture::progressValue() const
Devuelve el valor de progreso actual, que se encuentra entre progressMinimum() y progressMaximum().
Véanse también progressMinimum() y progressMaximum().
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::result() const
Devuelve el primer resultado en el futuro. Si el resultado no está disponible de inmediato, esta función se bloqueará y esperará a que el resultado esté disponible. Se trata de un método de conveniencia para llamar a resultAt(0). Ten en cuenta que result() devuelve una copia del resultado almacenado internamente. Si T es un tipo de solo movimiento, o si no deseas copiar el resultado, utiliza en su lugar takeResult().
Nota: La llamada a esta función da lugar a un comportamiento indefinido si isValid() devuelve false para este QFuture. Si este QFuture aún no se ha iniciado, llama a waitForFinished() antes de llamar a esta función para evitar un comportamiento indefinido.
Véase también resultAt(), results() y takeResult().
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::resultAt(int index) const
Devuelve el resultado de index en un momento posterior. Si el resultado no está disponible de inmediato, esta función se bloqueará y esperará a que el resultado esté disponible.
Nota: La llamada a esta función da lugar a un comportamiento indefinido si isValid() devuelve false para este QFuture. Si este QFuture aún no se ha iniciado, llame a waitForFinished() antes de llamar a esta función para evitar un comportamiento indefinido.
Véase también result(), results(), takeResult() y resultCount().
int QFuture::resultCount() const
Devuelve el número de resultados continuos disponibles en este futuro. El número real de resultados almacenados podría diferir de este valor, debido a huecos en el conjunto de resultados. Siempre es seguro recorrer los resultados desde 0 hasta resultCount().
Véase también result(), resultAt(), results() y takeResult().
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QList<T> QFuture::results() const
Devuelve todos los resultados del «future». Si los resultados no están disponibles de inmediato, esta función se bloqueará y esperará a que estén disponibles. Ten en cuenta que « results() » devuelve una copia de los resultados almacenados internamente. Por el momento, no se admite la obtención de todos los resultados de un tipo «solo movimiento» ( T ). No obstante, aún es posible recorrer la lista de resultados de «solo movimiento» utilizando iteradores al estilo STL o iteradores de solo lectura al estilo Java.
Nota: La llamada a esta función da lugar a un comportamiento indefinido si isValid() devuelve false para este QFuture. Si este QFuture aún no se ha iniciado, llama a waitForFinished() antes de llamar a esta función para evitar un comportamiento indefinido.
Véase también result(), resultAt(), takeResult(), resultCount() y isValid().
void QFuture::resume()
Reanuda el cálculo asíncrono representado por future(). Se trata de un método de conveniencia que simplemente llama a setSuspended(false).
Véase también ` suspend()`.
[since 6.0] void QFuture::setSuspended(bool suspend)
Si suspend es verdadero, esta función suspende el cálculo asíncrono representado por future(). Si el cálculo ya está suspendido, esta función no realiza ninguna acción. QFutureWatcher no dejará de enviar inmediatamente las señales de progreso y de resultado listo cuando se suspenda el future. En el momento de la suspensión, puede que aún haya cálculos en curso que no puedan detenerse. Las señales correspondientes a dichos cálculos seguirán enviándose.
Si suspend es falso, esta función reanuda el cálculo asíncrono. Si el cálculo no estaba suspendido previamente, esta función no hace nada.
Ten en cuenta que no todos los cálculos pueden suspenderse. Por ejemplo, el objeto ` QFuture ` devuelto por `QtConcurrent::run()` no puede suspenderse; pero el objeto ` QFuture ` devuelto por `QtConcurrent::mappedReduced()` sí puede.
Esta función se introdujo en Qt 6.0.
Véase también isSuspended(), suspend(), resume() y toggleSuspended().
[since 6.0] void QFuture::suspend()
Suspende el cálculo asíncrono representado por este «future». Se trata de un método de conveniencia que simplemente llama a ` setSuspended(true)`.
Esta función se introdujo en Qt 6.0.
Véase también ` resume()`.
[since 6.0] template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::takeResult()
Llama a esta función solo si isValid() devuelve true; de lo contrario, el comportamiento es indefinido. Esta función extrae (mueve) el primer resultado del objeto QFuture, cuando solo se espera un resultado. Si hay algún otro resultado, se descarta tras extraer el primero. Si el resultado no está disponible de inmediato, esta función se bloqueará y esperará a que el resultado esté disponible. El ` QFuture ` intentará utilizar la semántica de movimiento si es posible, y recurrirá a la construcción por copia si el tipo no es movible. Una vez obtenido el resultado, ` isValid()` se evaluará como ` false`.
Nota: QFuture permite, en general, compartir los resultados entre diferentes objetos QFuture (y, potencialmente, entre diferentes subprocesos). takeResult() se introdujo para que QFuture también funcionara con tipos de solo movimiento (como std::unique_ptr), por lo que asume que solo un subproceso puede extraer los resultados del futuro, y hacerlo solo una vez. Ten en cuenta también que, por el momento, no se admite la obtención de la lista de todos los resultados. No obstante, puedes seguir iterando por la lista de resultados de solo movimiento utilizando iteradores al estilo STL o iteradores de solo lectura al estilo Java.
Esta función se introdujo en Qt 6.0.
Véase también result(), results(), resultAt() y isValid().
[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(Function &&function)
Adjunta una continuación a este «future», lo que permite encadenar múltiples cálculos asíncronos si se desea, utilizando la política « Sync ». « function » es una función que toma un argumento del tipo empaquetado por este «future» si este tiene un resultado (no es un « QFuture<void>»). De lo contrario, no toma ningún argumento. Este método devuelve un nuevo « QFuture » que empaqueta un valor del tipo devuelto por « function ». El «future» devuelto estará en un estado no inicializado hasta que se invoque la continuación adjunta, o hasta que este «future» falle o se cancele.
Nota: Utiliza otras sobrecargas de este método si necesitas ejecutar la continuación en un hilo independiente.
Puedes encadenar varias operaciones de esta forma:
QFuture<int> future = ...;
future.then([](int res1){ ... }).then([](int res2){ ... })...O bien:
QFuture<void> future = ...;
future.then([](){ ... }).then([](){ ... })...La continuación también puede tomar un argumento de tipo ` QFuture ` (en lugar de su valor), que representa el «future» anterior. Esto puede resultar útil si, por ejemplo, ` QFuture ` tiene varios resultados y el usuario desea acceder a ellos dentro de la continuación. O si el usuario necesita gestionar la excepción del «future» anterior dentro de la continuación, para no interrumpir la cadena de continuaciones múltiples. Por ejemplo:
QFuture<int> future = someIntFuture;
future.then([](QFuture<int> f) {
try {
//...
auto result = f.result();
//...
} catch (QException &e) {
// handle the exception
}
}).then([](){/*...*/});Advertencia: Si el «future» anterior contiene varios resultados de tipo T y la continuación toma un argumento de tipo T como parámetro, ¡solo se gestionará en la continuación el primer resultado del « QFuture » anterior!
Si el «future» anterior lanza una excepción y esta no se gestiona dentro de la continuación, la excepción se propagará al «future» de continuación, para permitir que quien realiza la llamada la gestione:
QFuture<int> future = someIntFuture;
auto continuation = future.then([](int res1){ /*...*/ return res1; }).then([](int res2){ /*...*/ return res2; })/*...*/;
//...
// future throws an exception
try {
auto result = continuation.result();
} catch (QException &e) {
// handle the exception
}En este caso, se interrumpirá toda la cadena de continuaciones.
Nota: Si este «future» se cancela, las continuaciones asociadas a él también se cancelarán.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.0.
Véase también onFailed() y onCanceled().
[since 6.1] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QObject *context, Function &&function)
Adjunta una continuación a este «future», lo que permite encadenar varios cálculos asíncronos si se desea. Cuando finalice el cálculo asíncrono representado por este «future», se invocará ` function ` en el hilo del objeto ` context `. Esto puede resultar útil si es necesario invocar la continuación en un hilo específico. Por ejemplo:
// somewhere in the main thread
auto future = QtConcurrent::run([] {
// This will run in a separate thread
//...
}).then(this, [] {
// Update UI elements
});La continuación asociada a QtConcurrent::run actualiza los elementos de la interfaz de usuario y no puede invocarse desde un hilo que no sea de la interfaz gráfica. Por lo tanto, se proporciona this como contexto a .then(), para garantizar que se invoque en el hilo principal.
Las siguientes continuaciones también se invocarán desde el mismo contexto, a menos que se especifique un contexto o una política de ejecución diferentes:
auto future = QtConcurrent::run([] {
//...
}).then(this, [] {
// Update UI elements
}).then([] {
// This will also run in the main thread
});Esto se debe a que, por defecto, .then() se invoca desde el mismo hilo que el anterior.
Pero ten en cuenta que, si la continuación se adjunta después de que este «future» ya haya finalizado, se invocará inmediatamente, en el hilo que ejecuta ` then()`:
QObject *context /*...*/;
auto future = cachedResultsReady ? QtFuture::makeReadyVoidFuture()
: QtConcurrent::run([] { /* compute result */});
auto continuation = future.then(context, [] {
// Runs in the context's thread
}).then([] {
// May or may not run in the context's thread
});En el ejemplo anterior, si cachedResultsReady es true y se devuelve un «future» listo, es posible que el primer .then() finalice antes de que se añada el segundo. En este caso, se resolverá en el hilo actual. Por lo tanto, en caso de duda, pasa el contexto de forma explícita.
Si el « context » se destruye antes de que la cadena haya finalizado, el «future» se cancela. Esto implica que podría invocarse un controlador de cancelación cuando el « context » ya no sea válido. Para evitarlo, captura el « context » como un « QPointer »:
QObject *context /*...*/;
QFuture<Result> future /*...*/;
auto continuation = future.then(context, [context](Result result) {
// ...
}).onCanceled([context = QPointer(context)] {
if (!context)
return; // context was destroyed already
// handle cancellation
});Cuando se destruye el objeto de contexto, la cancelación se produce de inmediato. Los futuros anteriores de la cadena no se cancelan y siguen ejecutándose hasta que finalizan.
Nota: Al llamar a este método, debe garantizarse que el context permanezca activo durante la configuración de la cadena.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.1.
Véase también onFailed() y onCanceled().
[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QThreadPool *pool, Function &&function)
Añade una continuación a este «future», lo que permite encadenar varios cálculos asíncronos si se desea. Cuando finalice el cálculo asíncrono representado por este «future», se programará function en pool.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.0.
Véase también onFailed() y onCanceled().
[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QtFuture::Launch policy, Function &&function)
Adjunta una continuación a este «future», lo que permite encadenar múltiples cálculos asíncronos. Cuando finalice el cálculo asíncrono representado por este «future», se invocará function de acuerdo con la política de ejecución especificada policy. Se devuelve un nuevo QFuture que representa el resultado de la continuación.
Dependiendo de policy, la continuación se invocará en el mismo hilo que este «future», en un nuevo hilo, o heredará la política de lanzamiento y el grupo de hilos de este «future». Si no se especifica ninguna política de lanzamiento (véase la sobrecarga que solo admite un objeto invocable), se utilizará la política Sync.
En el siguiente ejemplo, ambas continuaciones se invocarán en un nuevo hilo (pero en el mismo).
QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... });En el siguiente ejemplo, ambas continuaciones se invocarán en nuevos hilos utilizando el mismo grupo de hilos.
QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... })
.then(QtFuture::Launch::Inherit, [](int res2){ ... });Consulta la documentación de la otra sobrecarga para obtener más detalles sobre ` function`.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.0.
Véanse también ` onFailed()` y ` onCanceled()`.
[since 6.0] void QFuture::toggleSuspended()
Activa o desactiva el estado de suspensión del cálculo asíncrono. En otras palabras, si el cálculo se encuentra actualmente en proceso de suspensión o ya está suspendido, al llamar a esta función se reanuda; si el cálculo se está ejecutando, se suspende. Se trata de un método de conveniencia para llamar a setSuspended(!(isSuspending() || isSuspended())).
Esta función se introdujo en Qt 6.0.
Véase también setSuspended(), suspend() y resume().
[since 6.4] template <typename U> QFuture<U> QFuture::unwrap()
Desenvuelve el «future» interno de este « QFuture<T> », donde « T » es un «future» de tipo « QFuture<U> », es decir, este «future» tiene el tipo « QFuture<QFuture<U>> ». Por ejemplo:
unwrappedFuture se completará tan pronto como se complete el futuro interno anidado dentro de outerFuture, con el mismo resultado o excepción y en el mismo hilo que informa de que el futuro interno ha finalizado. Si se cancela el futuro interno, unwrappedFuture también se cancelará.
Esto resulta especialmente útil al encadenar múltiples cálculos, y uno de ellos devuelve un ` QFuture ` como tipo de resultado. Por ejemplo, supongamos que queremos descargar varias imágenes desde una URL, redimensionarlas y reducirlas a una sola imagen utilizando `QtConcurrent::mappedReduced()`. Podríamos escribir algo como:
auto downloadImages = [] (const QUrl &url) {
QList<QImage> images;
//...
return images;
};
auto processImages = [scale, reduceImages](const QList<QImage> &images) {
return QtConcurrent::mappedReduced(images, scale, reduceImages);
};
auto show = [](const QImage &image) { /*...*/ };
auto future = QtConcurrent::run(downloadImages, url)
.then(processImages)
.unwrap()
.then(show);Aquí, ` QtConcurrent::mappedReduced() ` devuelve un ` QFuture<QImage>`, por lo que ` .then(processImages) ` devuelve un ` QFuture<QFuture<QImage>>`. Dado que ` show() ` toma un ` QImage ` como argumento, el resultado de ` .then(processImages) ` no se le puede pasar directamente. Tenemos que llamar a ` .unwrap()`, que obtendrá el resultado del «future» interno cuando esté listo y lo pasará a la siguiente continuación.
En caso de anidamiento múltiple, ` .unwrap() ` desciende hasta el nivel más interno:
Esta función se introdujo en Qt 6.4.
void QFuture::waitForFinished()
Espera a que finalice el cálculo asíncrono (incluidos los cálculos realizados con ` cancel()`), es decir, hasta que ` isFinished()` devuelva ` true`.
QFuture<T> &QFuture::operator=(const QFuture<T> &other)
Asigna ` other ` a este «future» y devuelve una referencia a dicho «future».
© 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.