En esta página

QtTaskTree::QThreadFunction Class

template <typename ResultType> class QtTaskTree::QThreadFunction

Una plantilla de clase que controla la ejecución de una función en un hilo independiente mediante QtConcurrent::run(). Más información...

Cabecera: #include <qthreadfunctiontask.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS TaskTree)
target_link_libraries(mytarget PRIVATE Qt6::TaskTree)
qmake: QT += tasktree
Desde: Qt 6.11
Heredado de: QtTaskTree::QThreadFunctionBase
Estado: Vista previa tecnológica

Esta clase se encuentra en fase de vista previa tecnológica y está sujeta a cambios.

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QThreadFunction(QObject *parent = nullptr)
virtual ~QThreadFunction() override
QFuture<ResultType> future() const
QFutureWatcher<ResultType> *futureWatcher()
const QFutureWatcher<ResultType> *futureWatcher() const
bool isAutoDelayedSync() const
bool isDone() const
bool isResultAvailable() const
ResultType result() const
ResultType resultAt(int index) const
QList<ResultType> results() const
void setAutoDelayedSync(bool on)
void setThreadFunctionData(Function &&function, Args &&... args)
void setThreadPool(QThreadPool *pool)
ResultType takeResult() const
QThreadPool *threadPool() const

Descripción detallada

Una QThreadFunction es una plantilla de clase muy práctica, en la que ResultType especifica el tipo de retorno de la función almacenada, que combina una función almacenada —que se llamará más tarde mediante QtConcurrent::run()— con un QFutureWatcher interno que supervisa la ejecución de la función. Utiliza QThreadFunctionTask para ejecutar la QThreadFunction dentro de la receta « QTaskTree ».

Establece una función con sus argumentos para que se ejecute en un hilo independiente utilizando el método setThreadFunctionData().

Para notificar un error desde el interior de la función que se ejecuta en un hilo independiente, coloca el argumento QPromise<ResultType> &promise en dicha función como primer argumento y cancela el futuro de la promesa. Ejemplo:

static void copyFile(QPromise<void> &promise, const QString &source,
                     const QString &destination)
{
    const QFileInfo fi(source);
    if (!fi.exists()) {
        promise.future().cancel(); // The QThreadFunction finishes with DoneResult::Error
        return;
    }

    // Copy file...
}

QThreadFunction<void> task;
task.setThreadFunctionData(copyFile, "source.txt", "dest.txt");
task.start();

Utiliza ` setThreadPool()` para ejecutar una función en el ` QThreadPool` deseado; de lo contrario, la función utilizará el ` global thread pool`.

Utiliza ` setAutoDelayedSync()` para activar o desactivar la sincronización diferida automática.

Para controlar la ejecución de la función, conéctese a las señales del futureWatcher() asociado. Para recopilar los datos de salida, utilice los métodos de lectura result(), resultAt() o results().

Documentación de las funciones miembro

[implicit] QThreadFunction::QThreadFunction(QObject *parent = nullptr)

Crea un objeto `QThreadFunction` con un ` parent` dado.

[override virtual] QThreadFunction::~QThreadFunction()

Elimina el ` QThreadFunction`. Si el ` QThreadFunction ` no se está ejecutando, no se lleva a cabo ninguna otra acción; en caso contrario, se cancela el «future» asociado y, dependiendo de la sincronización diferida automática, se realizan las siguientes acciones:

Sincronización diferida automáticaAcción
ActivadaEl « QFuture » asociado se almacena en el registro global. Utiliza « QThreadFunctionBase::syncAll()» al cerrar la aplicación para sincronizar todos los «futures» almacenados previamente en el registro global.
DesactivadoSe ejecuta directamente una llamada bloqueante a ` QFuture::waitForFinished()`.

Cuando la sincronización diferida automática está activada, la cancelación del futuro puede ser interceptada dentro de la función que aún se está ejecutando en un hilo independiente, de modo que esta pueda finalizar lo antes posible sin completar su tarea.

Por último, al cerrar la aplicación, se debe llamar a ` QThreadFunctionBase::syncAll()` para sincronizar todas las funciones que aún puedan estar ejecutándose en hilos independientes. La llamada a ` QThreadFunctionBase::syncAll()` es bloqueante en caso de que algunas funciones aún estén finalizando.

Nota: Cuando la sincronización retardada automática está activada, la función seguirá ejecutándose durante un tiempo después de que haya finalizado el destructor de QThreadFunction, por lo que es responsabilidad del usuario asegurarse de que todos los datos con los que pueda operar la función sigan estando disponibles. Si eso no se puede garantizar, desactive la sincronización retardada automática mediante QThreadFunction::setAutoDelayedSync(false). En este caso, el destructor de ` QThreadFunction ` esperará de forma bloqueante a que la función haya finalizado antes de eliminar ` QThreadFunction`. Consulte la documentación de ` QCustomTask ` para obtener más información sobre el parámetro de plantilla ` Deleter `.

Véase también setAutoDelayedSync() y syncAll().

QFuture<ResultType> QThreadFunction::future() const

Devuelve el objeto ` QFuture` de tipo `<ResultType>` asociado a la función ejecutada en un hilo independiente.

QFutureWatcher<ResultType> *QThreadFunction::futureWatcher()

Devuelve el puntero al objeto « QFutureWatcher<ResultType> » asociado a la función ejecutada en un hilo independiente. La vida útil del «watcher» devuelto está vinculada a la instancia de « QThreadFunction ».

Utiliza esta función si necesitas un mayor control sobre la ejecución futura; por ejemplo, para conectarte a las señales de progreso del observador devuelto.

const QFutureWatcher<ResultType> *QThreadFunction::futureWatcher() const

Devuelve el puntero ` const ` al ` QFutureWatcher<ResultType> ` asociado a la función ejecutada en un hilo independiente.

Se trata de una función sobrecargada.

bool QThreadFunction::isAutoDelayedSync() const

Indica si la sincronización automática diferida está activada.

Véase también syncAll() y setAutoDelayedSync().

bool QThreadFunction::isDone() const

Devuelve si la ejecución de la función ha finalizado.

bool QThreadFunction::isResultAvailable() const

Devuelve si el resultado está listo.

Véase también result().

ResultType QThreadFunction::result() const

Devuelve el ResultType notificado por la función ejecutada en un hilo independiente.

Nota: Asegúrese de que el resultado esté listo llamando a isResultAvailable(), de lo contrario, la llamada a result() podría bloquearse en caso de que el resultado aún no se haya notificado, o incluso provocar un fallo en caso de que la ejecución de la función haya finalizado sin notificar ningún resultado.

Véase también QFutureWatcher::result().

ResultType QThreadFunction::resultAt(int index) const

Devuelve el ResultType indicado por la función ejecutada en un hilo independiente en index.

Véase también result() y QFutureWatcher::resultAt().

QList<ResultType> QThreadFunction::results() const

Devuelve la lista de ResultType generada por la función ejecutada en un hilo independiente.

Véase también result(), resultAt() y QFuture::results().

void QThreadFunction::setAutoDelayedSync(bool on)

Establece la sincronización automática diferida en ` on`.

Por defecto, la sincronización retardada automática está activada, lo que significa que la destrucción del objeto ` QThreadFunction ` en ejecución no esperará de forma bloqueante a que finalice la función que se ejecuta en un hilo independiente. En su lugar, se cancela la llamada a ` QFuture ` asociada y se deja que la función siga ejecutándose hasta que finalice. La cancelación puede ser interceptada por la función que se ejecuta en un hilo independiente a través del argumento ` QPromise `, de modo que pueda finalizar antes de tiempo sin completar su tarea. En caso de que la sincronización diferida automática esté activada, es necesario llamar a ` QThreadFunctionBase::syncAll()` al cerrar la aplicación, con el fin de sincronizar todas las funciones que puedan estar ejecutándose en hilos independientes.

Cuando la sincronización diferida automática está desactivada, la sincronización se produce al destruirse QThreadFunction, lo que puede bloquear el hilo de llamada durante un tiempo considerable.

La sincronización automática solo se utiliza cuando QThreadFunction se ha ejecutado desde el hilo principal.

Véase también ` syncAll()` y ` isAutoDelayedSync()`.

template <typename Function, typename... Args> void QThreadFunction::setThreadFunctionData(Function &&function, Args &&... args)

Establece que la función ` function ` se ejecute con el objeto ` args ` pasado en un hilo independiente cuando se llame a `start()`.

Véase también QtConcurrent::run().

void QThreadFunction::setThreadPool(QThreadPool *pool)

Establece el objeto ` QThreadPool ` pool que se utilizará al ejecutar la llamada. Si el objeto ` pool ` pasado es nullptr, se utiliza la función ` QThreadPool::globalInstance()`.

Véase también threadPool().

ResultType QThreadFunction::takeResult() const

Obtiene (recoge) el ResultType devuelto por la función ejecutada en un hilo independiente.

Nota: Asegúrate de que el resultado esté listo llamando a isResultAvailable(); de lo contrario, la llamada a takeResult() podría bloquearse si el resultado aún no se ha notificado, o incluso provocar un fallo si la ejecución de la función ha finalizado sin notificar ningún resultado.

Véase también ` QFuture::takeResult()`.

QThreadPool *QThreadFunction::threadPool() const

Devuelve el grupo de subprocesos que se utiliza al ejecutar la llamada. Si se devuelve « nullptr », se utiliza « QThreadPool::globalInstance()».

Véase también setThreadPool().

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