En esta página

QThread Class

La clase QThread ofrece una forma independiente de la plataforma para gestionar subprocesos. Más información...

Encabezado: #include <QThread>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredado de: QObject

Tipos públicos

enum Priority { IdlePriority, LowestPriority, LowPriority, NormalPriority, HighPriority, …, InheritPriority }
(since 6.9) enum class QualityOfService { Auto, High, Eco }

Funciones públicas

QThread(QObject *parent = nullptr)
virtual ~QThread()
QAbstractEventDispatcher *eventDispatcher() const
(since 6.8) bool isCurrentThread() const
bool isFinished() const
bool isInterruptionRequested() const
bool isRunning() const
int loopLevel() const
QThread::Priority priority() const
void requestInterruption()
(since 6.9) QThread::QualityOfService serviceLevel() const
void setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)
void setPriority(QThread::Priority priority)
(since 6.9) void setServiceLevel(QThread::QualityOfService serviceLevel)
void setStackSize(uint stackSize)
uint stackSize() const
bool wait(QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))
bool wait(unsigned long time)

Funciones públicas reimplementadas

virtual bool event(QEvent *event) override

Ranuras públicas

void exit(int returnCode = 0)
void quit()
void start(QThread::Priority priority = InheritPriority)
void terminate()

Señales

void finished()
void started()

Miembros públicos estáticos

QThread *create(Function &&f, Args &&... args)
QThread *currentThread()
Qt::HANDLE currentThreadId()
int idealThreadCount()
(since 6.8) bool isMainThread()
void msleep(unsigned long msecs)
(since 6.6) void sleep(std::chrono::nanoseconds nsecs)
void sleep(unsigned long secs)
void usleep(unsigned long usecs)
void yieldCurrentThread()

Funciones protegidas

int exec()
virtual void run()

Miembros estáticos protegidos

void setTerminationEnabled(bool enabled = true)

Descripción detallada

Un objeto QThread gestiona un hilo de control dentro del programa. Los QThreads comienzan a ejecutarse en run(). Por defecto, run() inicia el bucle de eventos llamando a exec() y ejecuta un bucle de eventos de Qt dentro del hilo.

Puedes utilizar objetos «worker» trasladándolos al hilo mediante ` QObject::moveToThread()`.

class Worker : public QObject
{
    Q_OBJECT

public slots:
    void doWork(const QString &parameter) {
        QString result;
        /* ... here is the expensive or blocking operation ... */
        emit resultReady(result);
    }

signals:
    void resultReady(const QString &result);
};

class Controller : public QObject
{
    Q_OBJECT
    QThread workerThread;
public:
    Controller() {
        Worker *worker = new Worker;
        worker->moveToThread(&workerThread);
        connect(&workerThread, &QThread::finished, worker, &QObject::deleteLater);
        connect(this, &Controller::operate, worker, &Worker::doWork);
        connect(worker, &Worker::resultReady, this, &Controller::handleResults);
        workerThread.start();
    }
    ~Controller() {
        workerThread.quit();
        workerThread.wait();
    }
public slots:
    void handleResults(const QString &);
signals:
    void operate(const QString &);
};

El código dentro del slot del Worker se ejecutaría entonces en un hilo independiente. Sin embargo, se pueden conectar libremente los slots del Worker a cualquier señal, procedente de cualquier objeto, en cualquier hilo. Es seguro conectar señales y slots entre diferentes hilos, gracias a un mecanismo denominado queued connections.

Otra forma de hacer que el código se ejecute en un hilo independiente es crear una subclase de `QThread` y reimplementar ` run()`. Por ejemplo:

class WorkerThread : public QThread
{
    Q_OBJECT
public:
    explicit WorkerThread(QObject *parent = nullptr) : QThread(parent) { }
protected:
    void run() override {
        QString result;
        /* ... here is the expensive or blocking operation ... */
        emit resultReady(result);
    }
signals:
    void resultReady(const QString &s);
};

void MyObject::startWorkInAThread()
{
    WorkerThread *workerThread = new WorkerThread(this);
    connect(workerThread, &WorkerThread::resultReady, this, &MyObject::handleResults);
    connect(workerThread, &WorkerThread::finished, workerThread, &QObject::deleteLater);
    workerThread->start();
}

En ese ejemplo, el hilo se cerrará una vez que la función `run` haya devuelto un valor. No habrá ningún bucle de eventos en ejecución en el hilo a menos que se llame a ` exec()`.

Es importante recordar que una instancia de QThread ejecuta ` lives in ` en el hilo antiguo que la instanció, no en el nuevo hilo que llama a ` run()`. Esto significa que todas las ranuras en cola de QThread y ` invoked methods ` se ejecutarán en el hilo antiguo. Por lo tanto, un desarrollador que desee invocar slots en el nuevo hilo debe utilizar el enfoque de «objeto de trabajo»; no se deben implementar nuevos slots directamente en una subclase de QThread.

A diferencia de las ranuras en cola o los métodos invocados, los métodos llamados directamente sobre el objeto QThread se ejecutarán en el hilo que llama al método. Al crear una subclase de QThread, hay que tener en cuenta que el constructor se ejecuta en el hilo antiguo, mientras que run() se ejecuta en el nuevo hilo. Si se accede a una variable miembro desde ambas funciones, se accede a la variable desde dos hilos diferentes. Comprueba que sea seguro hacerlo.

Nota: Hay que tenercuidado al interactuar con objetos entre diferentes hilos. Como regla general, las funciones solo pueden invocarse desde el hilo que creó el propio objeto `QThread` (p. ej., ` setPriority()`), a menos que la documentación indique lo contrario. Consulte Sincronización de hilos para obtener más detalles.

Gestión de subprocesos

QThread le notificará mediante una señal cuando el hilo esté en started() y finished(), o bien puede utilizar isFinished() y isRunning() para consultar el estado del hilo.

Puedes detener el hilo llamando a exit() o quit(). En casos extremos, es posible que desees forzar la detención de un hilo en ejecución mediante terminate(). Sin embargo, hacerlo es peligroso y no se recomienda. Lee la documentación de terminate() y setTerminationEnabled() para obtener información detallada.

A menudo es conveniente desasignar los objetos que residen en un hilo cuando este finaliza. Para ello, conecte la señal finished() a QObject::deleteLater().

Utilice wait() para bloquear el hilo que realiza la llamada hasta que el otro hilo haya finalizado su ejecución (o hasta que haya transcurrido un tiempo especificado).

QThread también proporciona funciones de suspensión estáticas e independientes de la plataforma: sleep(), msleep() y usleep() permiten una resolución de segundos, milisegundos y microsegundos, respectivamente.

Nota: Las funcioneswait() y sleep() no deberían ser necesarias en general, ya que Qt es un marco de trabajo basado en eventos. En lugar de wait(), se recomienda escuchar la señal finished(). En lugar de las funciones sleep(), se recomienda utilizar QChronoTimer.

Las funciones estáticas currentThreadId() y currentThread() devuelven identificadores del hilo que se está ejecutando en ese momento. La primera devuelve un identificador específico de la plataforma para el hilo; la segunda devuelve un puntero a QThread.

Para elegir el nombre que se le asignará a tu hilo (tal y como lo identifica el comando ps -L en Linux, por ejemplo), puedes llamar a setObjectName() antes de iniciar el hilo. Si no se llama a setObjectName(), el nombre que se le asignará al hilo será el nombre de la clase del tipo de tiempo de ejecución del objeto del hilo (por ejemplo, "RenderThread" en el caso del ejemplo de Mandelbrot, ya que ese es el nombre de la subclase de QThread). Ten en cuenta que, actualmente, esto no está disponible en las compilaciones de versión final en Windows.

Véase también «Multihilo en Qt», QThreadStorage, «Sincronización de subprocesos», «Mandelbrot», «Productor y consumidor mediante semáforos» y «Productor y consumidor mediante condiciones de espera».

Documentación sobre tipos de miembros

enum QThread::Priority

Este tipo de enumeración indica cómo debe programar el sistema operativo los hilos recién creados.

ConstanteValorDescripción
QThread::IdlePriority0Se programan solo cuando no hay otros subprocesos en ejecución.
QThread::LowestPriority1Se programan con menos frecuencia que los de «LowPriority».
QThread::LowPriority2Se programa con menos frecuencia que «NormalPriority».
QThread::NormalPriority3La prioridad predeterminada del sistema operativo.
QThread::HighPriority4Se programa con más frecuencia que «NormalPriority».
QThread::HighestPriority5Se programa con más frecuencia que «HighPriority».
QThread::TimeCriticalPriority6se programa con la mayor frecuencia posible.
QThread::InheritPriority7utiliza la misma prioridad que el hilo creador. Este es el valor por defecto.

[since 6.9] enum class QThread::QualityOfService

Esta enumeración describe el nivel de calidad de servicio de un hilo y proporciona al programador información sobre el tipo de trabajo que realiza dicho hilo. En plataformas con diferentes perfiles de CPU, o con la capacidad de reducir la frecuencia de reloj de determinados núcleos de una CPU, esto permite al programador seleccionar o configurar un núcleo de CPU con características de rendimiento y consumo energético adecuadas para el hilo.

ConstanteValorDescripción
QThread::QualityOfService::Auto0El valor por defecto, que deja en manos del programador la decisión de en qué núcleo de la CPU se ejecutará el hilo.
QThread::QualityOfService::High1El programador debería ejecutar este hilo en un núcleo de CPU de alto rendimiento.
QThread::QualityOfService::Eco2El programador debería ejecutar este hilo en un núcleo de CPU de bajo consumo.

Esta enumeración se introdujo en Qt 6.9.

Véase también Priority, serviceLevel() y QThreadPool::serviceLevel().

Documentación de las funciones miembro

[explicit] QThread::QThread(QObject *parent = nullptr)

Crea un nuevo QThread para gestionar un nuevo hilo. El ` parent ` asume la propiedad del QThread. El hilo no comienza a ejecutarse hasta que se llama a ` start()`.

Véase también start().

[virtual noexcept] QThread::~QThread()

Elimina el objeto ` QThread`.

Ten en cuenta que eliminar un objeto ` QThread ` no detendrá la ejecución del hilo que gestiona. Eliminar un ` QThread ` en ejecución (es decir, cuando ` isFinished()` devuelve ` false`) provocará un fallo del programa. Espera a que se active la señal ` finished()` antes de eliminar el ` QThread`.

Desde Qt 6.3, está permitido eliminar una instancia de ` QThread ` creada mediante una llamada a ` QThread::create()` incluso si el hilo correspondiente sigue ejecutándose. En tal caso, Qt enviará una solicitud de interrupción a ese hilo (mediante ` requestInterruption()`); pedirá al bucle de eventos del hilo (si lo hay) que se cierre (mediante ` quit()`); y se bloqueará hasta que el hilo haya finalizado.

Véase también create(), isInterruptionRequested(), exec() y quit().

[static] template <typename Function, typename... Args> QThread *QThread::create(Function &&f, Args &&... args)

Crea un nuevo objeto ` QThread ` que ejecutará la función ` f ` con los argumentos ` args`.

El nuevo hilo no se inicia; debe iniciarse mediante una llamada explícita a start(). Esto te permite conectarte a sus señales, trasladar QObjects al hilo, elegir la prioridad del nuevo hilo, etc. La función f se llamará en el nuevo hilo.

Devuelve la instancia de ` QThread ` recién creada.

Nota: quien realiza la llamada adquiere la propiedad de la instancia de ` QThread ` devuelta.

Advertencia: no llames a ` start()` en la instancia ` QThread ` devuelta más de una vez; hacerlo provocará un comportamiento indefinido.

Véase también ` start()`.

[static] QThread *QThread::currentThread()

Devuelve un puntero a un objeto ` QThread ` que gestiona el hilo que se está ejecutando en ese momento.

[static noexcept] Qt::HANDLE QThread::currentThreadId()

Devuelve el identificador del hilo que se está ejecutando en ese momento.

Advertencia: El identificador devuelto por esta función se utiliza con fines internos y no debe emplearse en ningún código de aplicación.

Nota: En Windows, esta función devuelve el valor DWORD (ID del hilo de Windows) que devuelve la función Win32 GetCurrentThreadId(), no el pseudo-HANDLE (HANDLE del hilo de Windows) que devuelve la función Win32 GetCurrentThread().

[override virtual] bool QThread::event(QEvent *event)

Reimplementa: QObject::event(QEvent *e).

QAbstractEventDispatcher *QThread::eventDispatcher() const

Devuelve un puntero al objeto distribuidor de eventos del hilo. Si no existe ningún distribuidor de eventos para el hilo, esta función devuelve ` nullptr`.

Véase también setEventDispatcher().

[protected] int QThread::exec()

Entra en el bucle de eventos y espera hasta que se llame a ` exit()`, devolviendo el valor que se pasó a ` exit()`. El valor devuelto es 0 si se llama a ` exit()` a través de ` quit()`.

Esta función está pensada para ser llamada desde dentro de run(). Es necesario llamar a esta función para iniciar la gestión de eventos.

Nota: Solose puede llamar desde el propio hilo, es decir, cuando es el hilo actual.

Véase también quit() y exit().

[slot] void QThread::exit(int returnCode = 0)

Indica al bucle de eventos del hilo que finalice con un código de retorno.

Tras llamar a esta función, el hilo abandona el bucle de eventos y sale de la llamada a QEventLoop::exec(). La función QEventLoop::exec() devuelve returnCode.

Por convención, un valor de ` returnCode ` igual a 0 significa éxito, mientras que cualquier valor distinto de cero indica un error.

Ten en cuenta que, a diferencia de la función de la biblioteca C del mismo nombre, esta función sí que vuelve al llamante: lo que se detiene es el procesamiento de eventos.

No se iniciará ningún QEventLoop más en este hilo hasta que se vuelva a llamar a QThread::exec(). Si el bucle de eventos de QThread::exec() no se está ejecutando, la siguiente llamada a QThread::exec() también devolverá un resultado de inmediato.

Nota: Esta función es segura para subprocesos.

Véase también quit() y QEventLoop.

[private signal] void QThread::finished()

Esta señal se emite desde el hilo asociado justo antes de que este termine de ejecutarse.

Cuando se emite esta señal, el bucle de eventos ya ha dejado de ejecutarse. No se procesarán más eventos en el hilo, salvo los eventos de eliminación diferida. Esta señal puede conectarse a QObject::deleteLater(), para liberar objetos en ese hilo.

Nota: Si el hilo asociado se ha terminado mediante ` terminate()`, no está definido desde qué hilo se emite esta señal.

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

Véase también ` started()`.

[static noexcept] int QThread::idealThreadCount()

Devuelve el número ideal de subprocesos que este proceso puede ejecutar en paralelo. Para ello, consulta el número de procesadores lógicos disponibles para este proceso (si el sistema operativo lo admite) o el número total de procesadores lógicos del sistema. Esta función devuelve 1 si no se ha podido determinar ninguno de los dos valores.

Nota: En los sistemas operativos que admiten la configuración de la afinidad de un hilo con un subconjunto de todos los procesadores lógicos, el valor devuelto por esta función puede variar entre hilos y con el paso del tiempo.

Nota: En los sistemas operativos que admiten la conexión y desconexión en caliente de CPU, el valor devuelto por esta función también puede variar con el tiempo (y ten en cuenta que las CPU pueden activarse y desactivarse mediante software, sin necesidad de un cambio físico de hardware).

[noexcept, since 6.8] bool QThread::isCurrentThread() const

Devuelve «true» si este hilo es de tipo « QThread::currentThread ».

Esta función se introdujo en Qt 6.8.

Véase también currentThreadId().

bool QThread::isFinished() const

Devuelve ` true ` si el hilo ha finalizado; en caso contrario, devuelve ` false`.

Se considera que un hilo ha finalizado si ha regresado de la función ` run()` y se ha emitido la señal ` finished()`.

Ten en cuenta que el hilo puede seguir ejecutándose durante un tiempo arbitrario tras la emisión de la señal ` finished()`, realizando operaciones de limpieza, como la ejecución de los destructores de las variables ` thread_local `. Para sincronizarte con todos los efectos del hilo, llama a ` wait()` y comprueba que devuelve `true`.

Nota: Esta función es segura para subprocesos.

Véase también isRunning().

bool QThread::isInterruptionRequested() const

Devuelve «true» si la tarea que se está ejecutando en este hilo debe detenerse. Se puede solicitar una interrupción mediante la función ` requestInterruption()`.

Esta función se puede utilizar para que las tareas de larga duración sean interrumpibles de forma ordenada. No supone ningún riesgo no comprobar nunca el valor devuelto por esta función ni actuar en función de él; sin embargo, es recomendable hacerlo con regularidad en funciones de larga duración. Hay que tener cuidado de no llamarla con demasiada frecuencia, para mantener baja la sobrecarga.

void long_task() {
     forever {
        if ( QThread::currentThread()->isInterruptionRequested() ) {
            return;
        }
    }
}

Nota: Solo se puede llamar aesta función desde el propio hilo, es decir, cuando es el hilo activo.

Véase también currentThread() y requestInterruption().

[static noexcept, since 6.8] bool QThread::isMainThread()

Devuelve si el hilo que se está ejecutando actualmente es el hilo principal.

El hilo principal es aquel en el que se creó ` QCoreApplication `. Suele ser el hilo que llamó a la función ` main() `, aunque no necesariamente. Es el hilo que procesa los eventos de la interfaz gráfica de usuario y en el que se pueden crear objetos gráficos (`QWindow`, ` QWidget`).

Esta función se introdujo en Qt 6.8.

Véanse también currentThread() y QCoreApplication::instance().

bool QThread::isRunning() const

Devuelve ` true ` si el hilo está en ejecución; en caso contrario, devuelve ` false`.

Se considera que un hilo está en ejecución si QThread se ha iniciado con start(), pero aún no ha finalizado.

Ten en cuenta que el hilo puede seguir ejecutándose durante un tiempo arbitrario después de que se emita la señal ` finished()`, realizando operaciones de limpieza como la ejecución de los destructores de las variables ` thread_local `. Para sincronizarte con todos los efectos del hilo, llama a ` wait()` y comprueba que devuelva `true`.

Nota: Esta función es segura para subprocesos.

Véase también isFinished().

int QThread::loopLevel() const

Devuelve el nivel actual del bucle de eventos del hilo.

Nota: Solo se puede llamar aesta función desde el propio hilo, es decir, cuando es el hilo actual.

[static] void QThread::msleep(unsigned long msecs)

Esta es una función sobrecargada, equivalente a llamar a:

QThread::sleep(std::chrono::milliseconds{msecs});

Nota: Esta función no garantiza la precisión. La aplicación puede permanecer inactiva durante más tiempo que msecs en condiciones de carga elevada. Algunos sistemas operativos podrían redondear msecs a 10 ms o 15 ms.

Véanse también sleep() y usleep().

QThread::Priority QThread::priority() const

Devuelve la prioridad de un hilo en ejecución. Si el hilo no está en ejecución, esta función devuelve « InheritPriority ».

Véanse también Priority, setPriority() y start().

[slot] void QThread::quit()

Indica al bucle de eventos del hilo que finalice con el código de retorno 0 (éxito). Equivale a llamar a ` QThread::exit(0)`.

Esta función no hace nada si el hilo no tiene un bucle de eventos.

Nota: Esta función es segura para subprocesos.

Véase también ` exit()` y ` QEventLoop`.

void QThread::requestInterruption()

Solicita la interrupción del hilo. Dicha solicitud tiene carácter consultivo y corresponde al código que se ejecuta en el hilo decidir si debe actuar ante dicha solicitud y de qué manera. Esta función no detiene ningún bucle de eventos que se esté ejecutando en el hilo ni lo termina de ninguna manera.

Esta función no tiene ningún efecto sobre el hilo principal y no realiza ninguna acción si el hilo no se está ejecutando en ese momento.

Nota: Esta función es segura para subprocesos.

Véase también isInterruptionRequested().

[virtual protected] void QThread::run()

El punto de partida del hilo. Tras llamar a ` start()`, el hilo recién creado llama a esta función. La implementación por defecto se limita a llamar a ` exec()`.

Puedes reimplementar esta función para facilitar la gestión avanzada de hilos. Al salir de este método, se dará por terminada la ejecución del hilo.

Véanse también start() y wait().

[since 6.9] QThread::QualityOfService QThread::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 QThreadPool::serviceLevel().

void QThread::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

Establece el distribuidor de eventos del hilo en eventDispatcher. Esto solo es posible siempre y cuando aún no se haya instalado ningún distribuidor de eventos para el hilo.

Se crea automáticamente un distribuidor de eventos para el hilo principal al instanciar ` QCoreApplication ` y, en el caso de los hilos auxiliares, al llamar a ` start()`.

Este método asume la propiedad del objeto.

Véase también eventDispatcher().

void QThread::setPriority(QThread::Priority priority)

Esta función establece el valor de « priority » para un hilo en ejecución. Si el hilo no está en ejecución, esta función no realiza ninguna acción y devuelve el resultado de inmediato. Utiliza « start()» para iniciar un hilo con una prioridad específica.

El argumento « priority » puede ser cualquier valor de la enumeración « QThread::Priority », excepto « InheritPriority ».

El efecto del parámetro priority depende de la política de programación del sistema operativo. En concreto, el valor priority se ignorará en sistemas que no admitan prioridades de subprocesos (como en Linux; véase http://linux.die.net/man/2/sched_setscheduler para más detalles).

Véanse también Priority, priority() y start().

[since 6.9] void QThread::setServiceLevel(QThread::QualityOfService serviceLevel)

Establece el nivel de calidad de servicio del objeto de hilo en « serviceLevel ». ¡Esto solo se puede llamar desde el propio hilo o antes de que se inicie el hilo!

Actualmente, esto solo está implementado en plataformas de Apple y en Windows. La llamada a la función se completará correctamente en otras plataformas, pero por el momento no tendrá ningún efecto.

Esta función se introdujo en Qt 6.9.

Véase también ` serviceLevel()` y ` QThreadPool::setServiceLevel()`.

void QThread::setStackSize(uint stackSize)

Establece el tamaño de la pila del hilo en stackSize bytes. Si stackSize es cero, el sistema operativo o el entorno de ejecución elegirán un valor por defecto. De lo contrario, el tamaño de la pila del hilo será el valor proporcionado (que puede redondearse hacia arriba o hacia abajo).

En la mayoría de los sistemas operativos, la cantidad de memoria asignada a la pila será inicialmente inferior a ` stackSize ` y aumentará a medida que el hilo utilice la pila. Este parámetro establece el tamaño máximo hasta el que se permitirá que crezca (es decir, establece el tamaño del espacio de memoria virtual que la pila puede ocupar).

Esta función solo se puede invocar antes de que se inicie el hilo.

Advertencia: La mayoría de los sistemas operativos establecen límites mínimos y máximos para el tamaño de la pila de los hilos. El hilo no se iniciará si el tamaño de la pila se encuentra fuera de estos límites.

Véase también stackSize().

[static protected] void QThread::setTerminationEnabled(bool enabled = true)

Activa o desactiva la terminación del hilo actual en función del parámetro « enabled ». El hilo debe haber sido iniciado mediante « QThread ».

Cuando enabled es false, la terminación está desactivada. Las futuras llamadas a QThread::terminate() se devolverán inmediatamente sin efecto alguno. En su lugar, la terminación se aplaza hasta que se active.

Cuando enabled es true, la terminación está habilitada. Las futuras llamadas a QThread::terminate() terminarán el hilo normalmente. Si la terminación se ha aplazado (es decir, si se ha llamado a QThread::terminate() con la terminación deshabilitada), esta función terminará el hilo de llamada inmediatamente. Tenga en cuenta que, en este caso, esta función no retornará.

Véase también terminate().

[static, since 6.6] void QThread::sleep(std::chrono::nanoseconds nsecs)

Obliga al hilo actual a permanecer inactivo durante nsecs.

Evita utilizar esta función si necesitas esperar a que cambie una condición determinada. En su lugar, conecta un slot a la señal que indique el cambio o utiliza un controlador de eventos (véase QObject::event()).

Nota: Esta función no garantiza la precisión. La aplicación puede permanecer inactiva durante más tiempo que nsecs en condiciones de carga elevada.

Esta función se introdujo en Qt 6.6.

[static] void QThread::sleep(unsigned long secs)

Obliga al hilo actual a permanecer inactivo durante secs segundos.

Se trata de una función sobrecargada, equivalente a llamar a:

QThread::sleep(std::chrono::seconds{secs});

Véase también ` msleep()` y ` usleep()`.

uint QThread::stackSize() const

Devuelve el tamaño máximo de la pila del hilo en bytes (si se ha establecido mediante ` setStackSize()`); en caso contrario, devuelve cero.

Véase también setStackSize().

[slot] void QThread::start(QThread::Priority priority = InheritPriority)

Inicia la ejecución del hilo llamando a ` run()`. El sistema operativo programará el hilo de acuerdo con el parámetro ` priority `. Si el hilo ya se está ejecutando, esta función no realiza ninguna acción.

El efecto del parámetro priority depende de la política de programación del sistema operativo. En concreto, el parámetro priority se ignorará en sistemas que no admitan prioridades de subprocesos (como en Linux; consulte la documentación de sched_setscheduler para obtener más detalles).

Véanse también run() y terminate().

[private signal] void QThread::started()

Esta señal se emite desde el hilo asociado cuando este comienza a ejecutarse, por lo que cualquier slot conectado a él puede ser invocado mediante una invocación en cola. Aunque el evento se haya publicado antes de que se llame a ` run()`, es posible que la entrega de la señal entre hilos siga pendiente.

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

Véase también ` run()` y ` finished()`.

[slot] void QThread::terminate()

Finaliza la ejecución del hilo. El hilo puede finalizar de forma inmediata o no, dependiendo de las políticas de programación del sistema operativo. Para asegurarte, utiliza ` QThread::wait()` después de `terminate()`.

Cuando se termina el hilo, se activarán todos los hilos que estén esperando a que este finalice.

Advertencia: Esta función es peligrosa y se desaconseja su uso. El hilo puede terminarse en cualquier punto de su ruta de ejecución. Los hilos pueden terminarse mientras modifican datos. El hilo no tiene oportunidad de limpiar lo que haya dejado, desbloquear los mutex que tenga retenidos, etc. En resumen, utiliza esta función solo si es absolutamente necesario.

La terminación se puede habilitar o deshabilitar explícitamente llamando a ` QThread::setTerminationEnabled()`. Llamar a esta función mientras la terminación está deshabilitada hace que la terminación se aplace hasta que se vuelva a habilitar. Consulte la documentación de ` QThread::setTerminationEnabled()` para obtener más información.

Nota: Esta función es segura para subprocesos.

Véase también setTerminationEnabled().

[static] void QThread::usleep(unsigned long usecs)

Esta es una función sobrecargada, equivalente a llamar a:

QThread::sleep(std::chrono::microseconds{secs});

Nota: Esta función no garantiza la precisión. La aplicación puede permanecer inactiva durante más tiempo que usecs en condiciones de carga elevada. Algunos sistemas operativos pueden redondear usecs a 10 ms o 15 ms; en Windows, se redondeará al múltiplo de 1 ms más cercano.

Véanse también sleep() y msleep().

bool QThread::wait(QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))

Bloquea el hilo hasta que se cumpla alguna de estas condiciones:

  • El hilo asociado a este objeto ` QThread ` ha finalizado su ejecución (es decir, cuando vuelve de ` run()`). Esta función devolverá `true` si el hilo ha finalizado. También devolverá `true` si el hilo aún no se ha iniciado.
  • Se alcanza el deadline. Esta función devolverá «false» si se alcanza el plazo.

Un temporizador de plazo fijado en QDeadlineTimer::Forever (el valor por defecto) nunca agotará el tiempo de espera: en este caso, la función solo devuelve un resultado cuando el hilo sale de run() o si el hilo aún no se ha iniciado.

Esto proporciona una funcionalidad similar a la función POSIX ` pthread_join() `.

Nota: En algunos sistemas operativos, esta función puede devolver «true» mientras el hilo del sistema operativo sigue en ejecución y puede estar ejecutando código de limpieza, como los destructores « thread_local » de C++11. Entre los sistemas operativos en los que esta función solo devuelve «true» una vez que el hilo del sistema operativo ha finalizado por completo se incluyen Linux, Windows y los sistemas operativos de Apple.

Véase también ` sleep()` y ` terminate()`.

bool QThread::wait(unsigned long time)

time es el tiempo de espera en milisegundos. Si « time » es ULONG_MAX, la espera nunca agotará el tiempo de espera.

Esta es una función sobrecargada.

[static] void QThread::yieldCurrentThread()

Cede el control de la ejecución del hilo actual a otro hilo ejecutable, si lo hay. Ten en cuenta que es el sistema operativo el que decide a qué hilo se produce el cambio.

© 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.