En esta página

Tarea concurrente

QtConcurrent::task ofrece una interfaz alternativa para ejecutar una tarea en un hilo independiente. El valor de retorno de la función está disponible a través de la API « QFuture ».

Si solo quieres ejecutar una función en un hilo independiente sin ajustar ningún parámetro, utiliza QtConcurrent::run, ya que te permite escribir menos código. La función QtConcurrent::task está diseñada para aquellos casos en los que sea necesario realizar pasos de configuración adicionales.

Esta función forma parte del Qt Concurrent marco de trabajo.

Optimizar las inclusiones

Si incluyes el encabezado <QtConcurrent>, se incluirá todo el módulo Qt Concurrent junto con todo el módulo Qt Core, lo que puede aumentar los tiempos de compilación y el tamaño de los binarios. Para utilizar la función QtConcurrent::task(), puedes incluir un encabezado más específico:

#include <QtConcurrentTask>

Interfaz fluida

La función ` QtConcurrent::task ` devuelve una instancia de una clase auxiliar llamada ` QtConcurrent::QTaskBuilder`. Normalmente, no es necesario crear una instancia de esta clase manualmente. El módulo ` QtConcurrent::QTaskBuilder ` proporciona una interfaz para ajustar diferentes parámetros de las tareas de forma encadenada. Este enfoque se conoce como «interfaz fluida».

Basta con establecer los parámetros necesarios y, a continuación, iniciar una tarea. Para finalizar la configuración de una tarea, debes invocar QtConcurrent::QTaskBuilder::spawn. Esta función es no bloqueante (es decir, devuelve un objeto «future» inmediatamente), pero no se garantiza que la tarea se inicie de inmediato. Puedes utilizar las clases « QFuture » y « QFutureWatcher » para supervisar el estado de la tarea.

Consulta más ejemplos y explicaciones a continuación.

Ejecutar una tarea en un hilo independiente

Para ejecutar una función en otro hilo, utiliza ` QtConcurrent::QTaskBuilder::spawn`:

QtConcurrent::task([]{ qDebug("Hello, world!"); }).spawn();

Esto ejecutará una función lambda en un hilo independiente obtenido del QThreadPool predeterminado.

Pasar argumentos a la tarea

Para invocar una función con argumentos, hay que pasárselos a ` QtConcurrent::QTaskBuilder::withArguments`:

auto task = [](const QString &s){ qDebug() << ("Hello, " + s); };
QtConcurrent::task(std::move(task))
    .withArguments("world!")
    .spawn();

Se crea una copia de cada argumento en el momento en que se llama a ` QtConcurrent::QTaskBuilder::withArguments `, y estos valores se pasan al hilo cuando este comienza a ejecutar la tarea. Los cambios realizados en los argumentos tras llamar a ` QtConcurrent::QTaskBuilder::withArguments ` no son visibles para el hilo.

Si deseas ejecutar una función que acepte argumentos por referencia, debes utilizar las funciones auxiliares std::ref/cref. Estas funciones crean envoltorios ligeros alrededor de los argumentos pasados:

QString s("Hello, ");
QtConcurrent::task([](QString &s){ s.append("world!"); })
    .withArguments(std::ref(s))
    .spawn();

Asegúrate de que todos los objetos envueltos tengan una vida útil lo suficientemente larga. Es posible que se produzca un comportamiento indefinido si una tarea sobrevive al objeto envuelto por std::ref/cref.

Devolución de valores desde la tarea

Puedes obtener el resultado de una tarea con la API QFuture:

auto future = QtConcurrent::task([]{ return 42; }).spawn();
auto result = future.result(); // result == 42

Ten en cuenta que QFuture::result() es una llamada bloqueante, es decir, espera a que el resultado esté disponible. Utiliza QFutureWatcher para recibir una notificación cuando la tarea haya finalizado su ejecución y el resultado esté disponible.

Si desea pasar un resultado a otra tarea asíncrona, puede utilizar QFuture::then() para crear una cadena de tareas dependientes. Consulte la documentación de QFuture para obtener más detalles.

Funcionalidades adicionales de la API

Uso de diferentes tipos de objetos invocables

En sentido estricto, puede utilizar cualquier tipo de tarea y argumento que cumpla la siguiente condición:

std::is_invocable_v<std::decay_t<Task>, std::decay_t<Args>...>

Puedes utilizar una función libre:

QVariant value(42);
auto result = QtConcurrent::task([](const QVariant &var){return qvariant_cast<int>(var);})
                  .withArguments(value)
                  .spawn()
                  .result(); // result == 42

Se puede utilizar una función miembro:

QString result("Hello, world!");

QtConcurrent::task(&QString::chop)
    .withArguments(&result, 8)
    .spawn()
    .waitForFinished(); // result == "Hello"

Se puede utilizar un objeto invocable con un operador ():

auto result = QtConcurrent::task(std::plus<int>())
                  .withArguments(40, 2)
                  .spawn()
                  .result() // result == 42

Si quieres utilizar un objeto invocable ya existente, debes copiarlo o moverlo a un QtConcurrent::task, o bien envolverlo con std::ref o cref:

struct CallableWithState
{
    void operator()(int newState) { state = newState; }

    // ...
};

// ...

CallableWithState object;

QtConcurrent::task(std::ref(object))
   .withArguments(42)
   .spawn()
   .waitForFinished(); // The object's state is set to 42

Uso de un grupo de subprocesos personalizado

Puedes especificar un grupo de subprocesos personalizado:

QThreadPool pool;
QtConcurrent::task([]{ return 42; }).onThreadPool(pool).spawn();

Establecer la prioridad de una tarea

Puedes establecer la prioridad de una tarea:

QtConcurrent::task([]{ return 42; }).withPriority(10).spawn();

Si no necesitas un objeto «future», puedes llamar a ` QtConcurrent::QTaskBuilder::spawn` (`QtConcurrent::FutureResult::Ignore`):

QtConcurrent::task([]{ qDebug("Hello, world!"); }).spawn(FutureResult::Ignore);

Se puede acceder al objeto «promise» asociado a la tarea definiendo un argumento adicional de tipo « QPromise<T> & » dentro de la función. Este argumento adicional debe ser el primer argumento pasado a la función y, al igual que en el modo «Ejecución concurrente con promise», se espera que la función devuelva el tipo «void». La notificación de resultados se realiza a través de la API de « QPromise »:

void increment(QPromise<int> &promise, int i)
{
    promise.addResult(i + 1);
}

int result = QtConcurrent::task(&increment).withArguments(10).spawn().result(); // result == 11

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