QThreadPool Class
La clase QThreadPool gestiona un conjunto de QThreads. Más información...
| Encabezado: | #include <QThreadPool> |
| 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
- QThreadPool forma parte de las clases de subprocesos.
Nota: Todas las funciones de esta clase son seguras para subprocesos.
Propiedades
|
|
Funciones públicas
| QThreadPool(QObject *parent = nullptr) | |
| virtual | ~QThreadPool() |
| int | activeThreadCount() const |
| void | clear() |
(since 6.0) bool | contains(const QThread *thread) const |
| int | expiryTimeout() const |
| int | maxThreadCount() const |
| void | releaseThread() |
| void | reserveThread() |
(since 6.9) QThread::QualityOfService | serviceLevel() const |
| void | setExpiryTimeout(int expiryTimeout) |
| void | setMaxThreadCount(int maxThreadCount) |
(since 6.9) void | setServiceLevel(QThread::QualityOfService serviceLevel) |
| void | setStackSize(uint stackSize) |
| void | setThreadPriority(QThread::Priority priority) |
| uint | stackSize() const |
| void | start(QRunnable *runnable, int priority = 0) |
| void | start(Callable &&callableToRun, int priority = 0) |
(since 6.3) void | startOnReservedThread(QRunnable *runnable) |
(since 6.3) void | startOnReservedThread(Callable &&callableToRun) |
| QThread::Priority | threadPriority() const |
| bool | tryStart(QRunnable *runnable) |
| bool | tryStart(Callable &&callableToRun) |
| bool | tryTake(QRunnable *runnable) |
(since 6.8) bool | waitForDone(QDeadlineTimer deadline = QDeadlineTimer::Forever) |
| bool | waitForDone(int msecs) |
Miembros públicos estáticos
| QThreadPool * | globalInstance() |
Descripción detallada
QThread gestiona y recicla objetos individuales para ayudar a reducir los costes de creación de hilos en programas que utilizan hilos. Cada aplicación Qt tiene un objeto QThreadPool global, al que se puede acceder llamando a globalInstance().
Para utilizar uno de los subprocesos de QThreadPool, crea una subclase de QRunnable e implementa la función virtual run(). A continuación, crea un objeto de esa clase y pásalo a QThreadPool::start().
class HelloWorldTask : public QRunnable
{
void run() override
{
qDebug() << "Hello world from thread" << QThread::currentThread();
}
};
int main()
{
//...
HelloWorldTask *hello = new HelloWorldTask();
// QThreadPool se hace cargo de «hello» y lo elimina automáticamente
QThreadPool::globalInstance()->start(hello);
//...
}QThreadPool elimina el QRunnable automáticamente de forma predeterminada. Utiliza QRunnable::setAutoDelete() para cambiar el indicador de eliminación automática.
QThreadPool permite ejecutar el mismo QRunnable más de una vez llamando a tryStart(this) desde dentro de QRunnable::run(). Si autoDelete está habilitado, el QRunnable se eliminará cuando el último hilo salga de la función run. Llamar a start() varias veces con el mismo QRunnable cuando autoDelete está habilitado crea una condición de carrera y no se recomienda.
Los hilos que permanezcan inactivos durante un determinado periodo de tiempo caducarán. El tiempo de caducación por defecto es de 30 000 milisegundos (30 segundos). Este valor se puede modificar mediante la función ` setExpiryTimeout()`. Si se establece un tiempo de caducación negativo, se desactiva el mecanismo de caducación.
Llama a maxThreadCount() para consultar el número máximo de subprocesos que se pueden utilizar. Si es necesario, puedes modificar el límite con setMaxThreadCount(). El valor predeterminado de maxThreadCount() es QThread::idealThreadCount(). La función activeThreadCount() devuelve el número de subprocesos que están trabajando actualmente.
La función reserveThread() reserva un hilo para uso externo. Utiliza releaseThread() cuando hayas terminado de utilizar el hilo, para que pueda reutilizarse. Básicamente, estas funciones aumentan o reducen temporalmente el número de hilos activos y resultan útiles a la hora de implementar operaciones que requieren mucho tiempo y que no son visibles para el QThreadPool.
Ten en cuenta que QThreadPool es una clase de bajo nivel para la gestión de subprocesos; consulta el módulo Qt Concurrent para conocer alternativas de nivel superior.
Véase también QRunnable.
Documentación de propiedades
[read-only] activeThreadCount : int
Esta propiedad contiene el número de subprocesos activos en el grupo de subprocesos.
Nota: Es posible que esta función devuelva un valor superior a ` maxThreadCount()`. Consulte ` reserveThread()` para obtener más detalles.
Funciones de acceso:
| int | activeThreadCount() const |
Véase también reserveThread() y releaseThread().
expiryTimeout : int
Esta propiedad almacena el valor del tiempo de espera de caducidad del hilo en milisegundos.
Los hilos que permanezcan inactivos durante expiryTimeout milisegundos se considerarán caducados y se cerrarán. Dichos hilos se reiniciarán según sea necesario. El valor predeterminado de ` expiryTimeout ` es 30 000 milisegundos (30 segundos). Si ` expiryTimeout ` es un valor negativo, los hilos recién creados no caducarán; es decir, no se cerrarán hasta que se destruya el grupo de hilos.
Tenga en cuenta que configurar ` expiryTimeout ` no afecta a los hilos que ya se están ejecutando. Solo los hilos de nueva creación utilizarán el nuevo ` expiryTimeout`. Recomendamos configurar ` expiryTimeout ` inmediatamente después de crear el grupo de hilos, pero antes de llamar a ` start()`.
Funciones de acceso:
| int | expiryTimeout() const |
| void | setExpiryTimeout(int expiryTimeout) |
maxThreadCount : int
Esta propiedad almacena el número máximo de subprocesos que utiliza el grupo de subprocesos. Por defecto, esta propiedad adoptará el valor de ` QThread::idealThreadCount()` en el momento en que se cree el objeto ` QThreadPool `.
Nota: El grupo de subprocesos siempre utilizará al menos un subproceso, incluso si el límite de ` maxThreadCount ` es cero o negativo.
El valor predeterminado de ` maxThreadCount ` es ` QThread::idealThreadCount()`.
Funciones de acceso:
| int | maxThreadCount() const |
| void | setMaxThreadCount(int maxThreadCount) |
stackSize : uint
Esta propiedad almacena el tamaño de la pila de los hilos de trabajo del grupo de hilos.
El valor de esta propiedad solo se utiliza cuando el grupo de subprocesos crea nuevos subprocesos. Modificarlo no tiene ningún efecto sobre los subprocesos ya creados o en ejecución.
El valor por defecto es 0, lo que hace que QThread utilice el tamaño de pila predeterminado del sistema operativo.
Funciones de acceso:
| uint | stackSize() const |
| void | setStackSize(uint stackSize) |
[since 6.2] threadPriority : QThread::Priority
Esta propiedad almacena la prioridad de los nuevos subprocesos de trabajo.
El valor de la propiedad solo se utiliza cuando el grupo de subprocesos inicia nuevos subprocesos. Cambiarlo no tiene ningún efecto en los subprocesos que ya se están ejecutando.
El valor por defecto es ` QThread::InheritPriority`, lo que hace que ` QThread ` utilice la misma prioridad que aquella en la que se encuentra el objeto ` QThreadPool `.
Esta enumeración se introdujo en Qt 6.2.
Funciones de acceso:
| QThread::Priority | threadPriority() const |
| void | setThreadPriority(QThread::Priority priority) |
Véase también QThread::Priority.
Documentación de las funciones miembro
QThreadPool::QThreadPool(QObject *parent = nullptr)
Crea un grupo de subprocesos con el ` parent` especificado.
[virtual noexcept] QThreadPool::~QThreadPool()
Elimina el objeto ` QThreadPool`. Esta función permanecerá bloqueada hasta que se hayan completado todos los objetos ejecutables.
void QThreadPool::clear()
Elimina de la cola los elementos ejecutables que aún no se han iniciado. Se eliminan los elementos ejecutables para los que runnable->autoDelete() devuelve true.
Véase también ` start()`.
[since 6.0] bool QThreadPool::contains(const QThread *thread) const
Devuelve ` true ` si ` thread ` es un hilo gestionado por este grupo de hilos.
Esta función se introdujo en Qt 6.0.
[static] QThreadPool *QThreadPool::globalInstance()
Devuelve la instancia global de ` QThreadPool `.
void QThreadPool::releaseThread()
Libera un hilo reservado previamente mediante una llamada a reserveThread().
Nota: Llamar a esta función sin haber reservado previamente un hilo aumenta temporalmente el valor de ` maxThreadCount()`. Esto resulta útil cuando un hilo entra en estado de espera a la espera de más trabajo, lo que permite que otros hilos continúen. Asegúrate de llamar a ` reserveThread()` cuando haya terminado la espera, para que el grupo de hilos pueda mantener correctamente el valor de ` activeThreadCount()`.
Véase también reserveThread().
void QThreadPool::reserveThread()
Reserva un hilo, sin tener en cuenta las funciones activeThreadCount() y maxThreadCount().
Una vez que hayas terminado de utilizar el hilo, llama a releaseThread() para permitir su reutilización.
Nota: Aunque se reserven uno o más hilos con maxThreadCount(), el grupo de hilos seguirá permitiendo un mínimo de un hilo.
Nota: Esta función aumentará el número de subprocesos activos que se muestra. Esto significa que, al utilizar esta función, es posible que activeThreadCount() devuelva un valor mayor que maxThreadCount().
Véase también releaseThread().
[since 6.9] QThread::QualityOfService QThreadPool::serviceLevel() const
Devuelve el nivel actual de calidad de servicio del hilo.
Esta función se introdujo en Qt 6.9.
Véase también setServiceLevel() y QThread::serviceLevel().
[since 6.9] void QThreadPool::setServiceLevel(QThread::QualityOfService serviceLevel)
Establece el nivel de calidad de servicio de los objetos de hilo creados tras la llamada a este método setter en « serviceLevel ».
No está disponible en todas las plataformas. Consulta QThread::setServiceLevel() para obtener más detalles.
Esta función se introdujo en Qt 6.9.
Véase también serviceLevel() y QThread::serviceLevel().
void QThreadPool::start(QRunnable *runnable, int priority = 0)
Reserva un hilo y lo utiliza para ejecutar ` runnable`, a menos que dicho hilo haga que el recuento de hilos actuales supere el valor establecido en ` maxThreadCount()`. En ese caso, ` runnable ` se añade a una cola de ejecución. El argumento ` priority ` puede utilizarse para controlar el orden de ejecución de la cola.
Tenga en cuenta que el grupo de subprocesos asume la propiedad de runnable si runnable->autoDelete() devuelve true, y que runnable será eliminado automáticamente por el grupo de subprocesos una vez que runnable->run() haya finalizado. Si runnable->autoDelete() devuelve false, la propiedad de runnable sigue perteneciendo al autor de la llamada. Tenga en cuenta que cambiar la eliminación automática en runnable después de llamar a estas funciones da lugar a un comportamiento indefinido.
template <typename Callable> requires QRunnable::if_callable<Callable> void QThreadPool::start(Callable &&callableToRun, int priority = 0)
Reserva un hilo y lo utiliza para ejecutar callableToRun, a menos que este hilo haga que el recuento de hilos actuales supere maxThreadCount(). En ese caso, callableToRun se añade a una cola de ejecución. El argumento priority puede utilizarse para controlar el orden de ejecución de la cola de ejecución.
Nota: En las versiones de Qt anteriores a la 6.6, esta función aceptaba std::function<void()>, por lo que no podía gestionar funciones invocables de solo movimiento.
Restricciones
Participa en la resolución de sobrecargas solo si Callable es una función u objeto de función que se pueda invocar sin argumentos.
Esta es una función sobrecargada.
[since 6.3] void QThreadPool::startOnReservedThread(QRunnable *runnable)
Libera un hilo reservado previamente con ` reserveThread()` y lo utiliza para ejecutar ` runnable`.
Tenga en cuenta que el grupo de subprocesos asume la propiedad de runnable si runnable->autoDelete() devuelve true, y que runnable será eliminado automáticamente por el grupo de subprocesos una vez que runnable->run() haya finalizado. Si runnable->autoDelete() devuelve false, la propiedad de runnable sigue perteneciendo al autor de la llamada. Tenga en cuenta que cambiar la eliminación automática en runnable tras llamar a esta función da lugar a un comportamiento indefinido.
Nota: Llamar a esta función cuando no hay subprocesos reservados da lugar a un comportamiento indefinido.
Esta función se introdujo en Qt 6.3.
Véase también reserveThread() y start().
[since 6.3] template <typename Callable> requires QRunnable::if_callable<Callable> void QThreadPool::startOnReservedThread(Callable &&callableToRun)
Libera un hilo reservado previamente con ` reserveThread()` y lo utiliza para ejecutar ` callableToRun`.
Nota: En las versiones de Qt anteriores a la 6.6, esta función aceptaba std::function<void()>, por lo que no podía gestionar funciones llamables de solo movimiento.
Restricciones
Participa en la resolución de sobrecargas únicamente si ` Callable ` es una función u objeto de función que se pueda invocar sin argumentos.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.3.
bool QThreadPool::tryStart(QRunnable *runnable)
Intenta reservar un hilo para ejecutar runnable.
Si no hay hilos disponibles en el momento de la llamada, esta función no realiza ninguna acción y devuelve ` false`. En caso contrario, se ejecuta inmediatamente ` runnable ` utilizando un hilo disponible y esta función devuelve ` true`.
Tenga en cuenta que, en caso de éxito, el grupo de subprocesos asume la propiedad de runnable si runnable->autoDelete() devuelve true, y el runnable será eliminado automáticamente por el grupo de subprocesos una vez que runnable->run() haya finalizado. Si runnable->autoDelete() devuelve false, la propiedad de runnable sigue recayendo en el autor de la llamada. Tenga en cuenta que cambiar la eliminación automática en runnable después de llamar a esta función da lugar a un comportamiento indefinido.
template <typename Callable> requires QRunnable::if_callable<Callable> bool QThreadPool::tryStart(Callable &&callableToRun)
Intenta reservar un hilo para ejecutar callableToRun.
Si no hay hilos disponibles en el momento de la llamada, esta función no realiza ninguna acción y devuelve ` false`. En caso contrario, se ejecuta inmediatamente ` callableToRun ` utilizando un hilo disponible y esta función devuelve ` true`.
Nota: En las versiones de Qt anteriores a la 6.6, esta función aceptaba std::function<void()>, por lo que no podía gestionar funciones ejecutables de solo movimiento.
Restricciones
Participa en la resolución de sobrecargas solo si Callable es una función u objeto de función que se pueda invocar sin argumentos.
Esta es una función sobrecargada.
bool QThreadPool::tryTake(QRunnable *runnable)
Intenta eliminar el runnable especificado de la cola si aún no se ha iniciado. Si el runnable no se hubiera iniciado, devuelve true, y la propiedad de runnable se transfiere al llamante (incluso cuando runnable->autoDelete() == true). De lo contrario, devuelve false.
Nota: Si runnable->autoDelete() == true, esta función podría eliminar el «runnable» equivocado. Esto se conoce como el problema ABA: es posible que el « runnable » original ya se haya ejecutado y haya sido eliminado desde entonces. La memoria se reutiliza para otro «runnable», que es el que acaba siendo eliminado en lugar del previsto. Por este motivo, recomendamos llamar a esta función únicamente para elementos ejecutables que no se eliminen automáticamente.
Véase también start() y QRunnable::autoDelete().
[since 6.8] bool QThreadPool::waitForDone(QDeadlineTimer deadline = QDeadlineTimer::Forever)
Espera a que caduque ` deadline ` para que todos los hilos se cierren y elimina todos los hilos del grupo de hilos. Devuelve ` true ` si se han eliminado todos los hilos; en caso contrario, devuelve ` false`.
Esta función se introdujo en Qt 6.8.
bool QThreadPool::waitForDone(int msecs)
Espera hasta msecs milisegundos a que todos los hilos finalicen y elimina todos los hilos del grupo de hilos. Devuelve true si se han eliminado todos los hilos; en caso contrario, devuelve false. Si msecs es -1, esta función espera a que finalice el último hilo.
© 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.