QFutureWatcher Class
template <typename T> class QFutureWatcherLa clase QFutureWatcher permite supervisar un objeto de tipo « QFuture » mediante señales y ranuras. Más información...
| Encabezado: | #include <QFutureWatcher> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Heredado de: | QObject |
- Lista de todos los miembros, incluidos los heredados
- Miembros obsoletos
- QFutureWatcher forma parte de las clases de subprocesos.
Nota: Todas las funciones de esta clase son reentrantes.
Funciones públicas
| QFutureWatcher(QObject *parent = nullptr) | |
| virtual | ~QFutureWatcher() |
| QFuture<T> | future() const |
| bool | isCanceled() const |
| bool | isFinished() const |
| bool | isRunning() const |
| bool | isStarted() const |
(since 6.0) bool | isSuspended() const |
(since 6.0) bool | isSuspending() const |
| int | progressMaximum() const |
| int | progressMinimum() const |
| QString | progressText() const |
| int | progressValue() const |
| T | result() const |
| T | resultAt(int index) const |
| void | setFuture(const QFuture<T> &future) |
| void | setPendingResultsLimit(int limit) |
| void | waitForFinished() |
Ranuras públicas
| void | cancel() |
| void | resume() |
(since 6.0) void | setSuspended(bool suspend) |
(since 6.0) void | suspend() |
(since 6.0) void | toggleSuspended() |
Señales
| void | canceled() |
| void | finished() |
| void | progressRangeChanged(int minimum, int maximum) |
| void | progressTextChanged(const QString &progressText) |
| void | progressValueChanged(int progressValue) |
| void | resultReadyAt(int index) |
| void | resultsReadyAt(int beginIndex, int endIndex) |
| void | resumed() |
| void | started() |
(since 6.0) void | suspended() |
(since 6.0) void | suspending() |
Descripción detallada
QFutureWatcher es una clase de plantilla en la que el parámetro de plantilla T especifica el tipo de resultado del QFuture que se está supervisando. QFutureWatcher proporciona información y notificaciones sobre un QFuture. Utiliza la función setFuture() para comenzar a supervisar un QFuture concreto. La función future() devuelve el futuro establecido con setFuture().
Para mayor comodidad, varias de las funciones de QFuture también están disponibles en QFutureWatcher: progressValue(), progressMinimum(), progressMaximum(), progressText(), isStarted(), isFinished(), isRunning(), isCanceled(), isSuspending(), isSuspended(), waitForFinished(), result() y resultAt(). Las funciones cancel(), setSuspended(), suspend(), resume() y toggleSuspended() son ranuras de QFutureWatcher.
Los cambios de estado se notifican a través de las señales « started » (), « finished » (), « canceled » (), « suspending » (), « suspended » (), « resumed » (), « resultReadyAt » () y « resultsReadyAt » (). La información sobre el progreso se proporciona a través de las señales « progressRangeChanged » (), «void progressValueChanged » () y « progressTextChanged » ().
El control de limitación lo proporciona la función setPendingResultsLimit(). Cuando el número de señales pendientes resultReadyAt() o resultsReadyAt() supera el límite, el cálculo representado por el «future» se limitará automáticamente. El cálculo se reanudará una vez que el número de señales pendientes descienda por debajo del límite.
Ejemplo: Iniciar un cálculo y recibir una llamada de retorno de slot cuando haya finalizado:
// Instantiate the objects and connect to the finished signal.
MyClass myObject;
QFutureWatcher<int> watcher;
QObject::connect(&watcher, &QFutureWatcher<int>::finished, &myObject, &MyClass::handleFinished);
// Start the computation.
QFuture<int> future = QtConcurrent::run([result](){ /*...*/ return result;});
watcher.setFuture(future);Ten en cuenta que no todos los cálculos asíncronos en ejecución pueden cancelarse o suspenderse. Por ejemplo, el futuro devuelto por `QtConcurrent::run()` no puede cancelarse; sin embargo, el futuro devuelto por `QtConcurrent::mappedReduced()` sí puede.
QFuture<void> está especializado para no contener ninguna de las funciones de obtención de resultados. Cualquier <T> también puede ser supervisado por un QFutureWatcher<void>. Esto resulta útil si solo se necesita información sobre el estado o el progreso, y no los datos del resultado real.
Véase también QFuture y Qt Concurrent.
Documentación de las funciones miembro
[explicit] QFutureWatcher::QFutureWatcher(QObject *parent = nullptr)
Crea un nuevo objeto `QFutureWatcher` con el ` parent` indicado. Hasta que se establezca un futuro mediante ` setFuture()` (), las funciones ` isStarted()`, ` isCanceled()` y ` isFinished()` devuelven ` true`.
[virtual] QFutureWatcher::~QFutureWatcher()
Destruye la « QFutureWatcher ».
[slot] void QFutureWatcher::cancel()
Cancela el cálculo asíncrono representado por la función ` 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.
Aún se puede acceder a los resultados disponibles actualmente en un QFuture cancelado, pero no se obtendrán nuevos resultados tras llamar a esta función. Además, este QFutureWatcher no emitirá las señales de progreso y de resultado listo una vez cancelado. Esto incluye las señales progressValueChanged(), progressRangeChanged(), progressTextChanged(), resultReadyAt() y resultsReadyAt().
Ten en cuenta que no todos los cálculos asíncronos en ejecución pueden cancelarse. Por ejemplo, el objeto ` QFuture ` devuelto por `QtConcurrent::run()` no puede cancelarse; sin embargo, el objeto ` QFuture ` devuelto por `QtConcurrent::mappedReduced()` sí puede cancelarse.
[signal] void QFutureWatcher::canceled()
Esta señal se emite si se cancela el contrato de futuros objeto de seguimiento.
[signal] void QFutureWatcher::finished()
Esta señal se emite cuando finaliza el contrato de futuros objeto de seguimiento.
QFuture<T> QFutureWatcher::future() const
Devuelve el «future» vigilado.
Véase también setFuture().
bool QFutureWatcher::isCanceled() const
Devuelve ` true ` si el cálculo asíncrono se ha cancelado con la función ` cancel()`, o si no se ha establecido ningún «future»; 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 QFutureWatcher::isFinished() const
Devuelve ` true ` si ha finalizado el cálculo asíncrono representado por ` future()`, o si no se ha establecido ningún «future»; en caso contrario, devuelve ` false`.
bool QFutureWatcher::isRunning() const
Devuelve ` true ` si el cálculo asíncrono representado por ` future()` se está ejecutando en ese momento; en caso contrario, devuelve ` false`.
bool QFutureWatcher::isStarted() const
Devuelve ` true ` si se ha iniciado el cálculo asíncrono representado por ` future()` o si no se ha establecido ningún «future»; en caso contrario, devuelve ` false`.
[since 6.0] bool QFutureWatcher::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 suspended(), setSuspended() y isSuspending().
[since 6.0] bool QFutureWatcher::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 ejecutándose. 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().
int QFutureWatcher::progressMaximum() const
Devuelve el valor máximo de progressValue().
Véanse también progressValue() y progressMinimum().
int QFutureWatcher::progressMinimum() const
Devuelve el mínimo de progressValue().
Véase también progressValue() y progressMaximum().
[signal] void QFutureWatcher::progressRangeChanged(int minimum, int maximum)
El intervalo de progreso para el futuro objeto de seguimiento ha cambiado a minimum y maximum.
QString QFutureWatcher::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.
[signal] void QFutureWatcher::progressTextChanged(const QString &progressText)
Esta señal se emite cuando el futuro supervisado envía información textual sobre el progreso, progressText.
int QFutureWatcher::progressValue() const
Devuelve el valor de progreso actual, que se encuentra entre progressMinimum() y progressMaximum().
Véanse también progressMinimum() y progressMaximum().
[signal] void QFutureWatcher::progressValueChanged(int progressValue)
Esta señal se emite cuando el «future» vigilado informa de su progreso; progressValue muestra el progreso actual. Para evitar sobrecargar el bucle de eventos de la interfaz gráfica de usuario, QFutureWatcher limita la frecuencia de emisión de la señal de progreso. Esto significa que es posible que los oyentes conectados a esta ranura no reciban todos los informes de progreso que genere el «future». La última actualización de progreso (en la que progressValue es igual al valor máximo) siempre se transmitirá.
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFutureWatcher::result() const
Devuelve el primer resultado de la función ` future()`. 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 práctico para llamar a la función ` resultAt(0)`.
Véase también resultAt().
template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFutureWatcher::resultAt(int index) const
Devuelve el resultado de « index » en « future()». Si el resultado no está disponible de inmediato, esta función se bloqueará y esperará a que el resultado esté disponible.
Véase también result().
[signal] void QFutureWatcher::resultReadyAt(int index)
Esta señal se emite cuando el «future» supervisado comunica un resultado listo en index. Si el «future» comunica varios resultados, el índice indicará de cuál se trata. Los resultados pueden comunicarse sin seguir un orden determinado. Para obtener el resultado, llama a resultAt(índice);
[signal] void QFutureWatcher::resultsReadyAt(int beginIndex, int endIndex)
Esta señal se emite cuando el futuro supervisado comunica que los resultados están listos. Los resultados se indexan desde beginIndex hasta endIndex.
[slot] void QFutureWatcher::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().
[signal] void QFutureWatcher::resumed()
Esta señal se emite cuando se reanuda el futuro en el que se está realizando el seguimiento.
void QFutureWatcher::setFuture(const QFuture<T> &future)
Comienza a supervisar el future indicado.
Si future ya se ha iniciado, el observador emitirá inicialmente señales que pondrán al día a sus oyentes sobre el estado futuro. Las siguientes señales se emitirán, si procede, en el orden indicado: started(), progressRangeChanged(), progressValueChanged(), progressTextChanged(), resultsReadyAt(), resultReadyAt(), suspending(), suspended(), canceled() y finished(). De ellas, resultsReadyAt() y resultReadyAt() pueden emitirse varias veces para cubrir todos los resultados disponibles. progressValueChanged() y progressTextChanged() solo se emitirán una vez para el último valor de progreso y texto disponibles.
Para evitar una condición de carrera, es importante llamar a esta función después de establecer las conexiones.
Véase también future().
void QFutureWatcher::setPendingResultsLimit(int limit)
El método `setPendingResultsLimit()` permite controlar la limitación de la ejecución. Cuando el número de señales pendientes de ` resultReadyAt()` o ` resultsReadyAt()` supera el valor de ` limit`, el cálculo representado por el `future` se limitará automáticamente. El cálculo se reanudará una vez que el número de señales pendientes sea inferior al valor de ` limit`.
[slot, since 6.0] void QFutureWatcher::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 futuro. 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 emitiéndose.
Si suspend es false, 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; sin embargo, el objeto ` QFuture ` devuelto por `QtConcurrent::mappedReduced()` sí puede.
Esta función se introdujo en Qt 6.0.
Véase también ` suspended()`, ` suspend()`, ` resume()` y ` toggleSuspended()`.
[signal] void QFutureWatcher::started()
Esta señal se emite cuando este QFutureWatcher comienza a seguir el conjunto futuro con setFuture().
[slot, since 6.0] void QFutureWatcher::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()`.
[signal, since 6.0] void QFutureWatcher::suspended()
Esta señal se emite cuando se ha ejecutado la función ` suspend()`, lo que significa que ya no hay ningún cálculo en curso. Tras recibir esta señal, no se esperan más señales de «resultado listo» ni de «informe de progreso».
Esta función se introdujo en Qt 6.0.
Véanse también « setSuspended()» y « suspend()».
[signal, since 6.0] void QFutureWatcher::suspending()
Esta señal se emite cuando el estado del futuro supervisado pasa a «suspendido».
Nota: Esta señal solo informa de que se ha solicitado la suspensión. No indica que se hayan detenido todas las operaciones en segundo plano. Las señales correspondientes a los cálculos que estaban en curso en el momento de la suspensión seguirán emitiéndose. Para saber cuándo la suspensión ha entrado realmente en vigor, utiliza la señal « suspended()».
Esta función se introdujo en Qt 6.0.
Véase también setSuspended(), suspend() y suspended().
[slot, since 6.0] void QFutureWatcher::toggleSuspended()
Activa o desactiva el estado de suspensión del cálculo asíncrono. En otras palabras, si el cálculo está 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().
void QFutureWatcher::waitForFinished()
Espera a que finalice el cálculo asíncrono (incluidos los cálculos realizados con ` cancel()`), es decir, hasta que ` isFinished()` devuelva ` true`.
© 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.