En esta página

Ejecución concurrente

La función QtConcurrent::run() ejecuta una función en un hilo independiente. El valor de retorno de la función está disponible a través de la API ` QFuture `.

QtConcurrent::run() es un método sobrecargado. Estas sobrecargas pueden considerarse como modos ligeramente diferentes. En el modo básico, la función pasada a QtConcurrent::run() solo puede comunicar un único resultado de cálculo a quien la invoca. En el modo «ejecución con promesa», la función pasada a QtConcurrent::run() puede hacer uso de la API adicional QPromise, que permite notificar múltiples resultados, informar del progreso, suspender el cálculo cuando lo solicite el llamante o detener el cálculo a petición de este.

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

Optimizar las inclusiones

Si se incluye 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::run(), se puede incluir un encabezado más específico:

#include <QtConcurrentRun>

Ejecución concurrente (modo básico)

La función pasada a QtConcurrent::run() puede informar del resultado a través de su valor de retorno.

Ejecución de una función en un hilo independiente

Para ejecutar una función en otro hilo, utiliza QtConcurrent::run():

extern void aFunction();
QFuture<void> future = QtConcurrent::run(aFunction);

Esto ejecutará aFunction en un hilo independiente obtenido a partir del valor predeterminado QThreadPool. Puede utilizar las clases QFuture y QFutureWatcher para supervisar el estado de la función.

Para utilizar un grupo de subprocesos dedicado, puede pasar ` QThreadPool ` como primer argumento:

extern void aFunction();
QThreadPool pool;
QFuture<void> future = QtConcurrent::run(&pool, aFunction);

Pasar argumentos a la función

Para pasar argumentos a la función, hay que añadirlos a la llamada a QtConcurrent::run() inmediatamente después del nombre de la función. Por ejemplo:

extern void aFunctionWithArguments(int arg1, double arg2, const QString &string);

int integer = ...;
double floatingPoint = ...;
QString string = ...;

QFuture<void> future = QtConcurrent::run(aFunctionWithArguments, integer, floatingPoint, string);

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

Ten en cuenta que ` QtConcurrent::run ` no admite la llamada directa a funciones sobrecargadas. Por ejemplo, el código siguiente no se compilará:

void foo(int arg);
void foo(int arg1, int arg2);
...
QFuture<void> future = QtConcurrent::run(foo, 42);

La solución más sencilla es llamar a la función sobrecargada mediante una lambda:

QFuture<void> future = QtConcurrent::run([] { foo(42); });

O bien, puedes indicar al compilador qué sobrecarga debe elegir utilizando una expresión condicional ( static_cast):

QFuture<void> future = QtConcurrent::run(static_cast<void(*)(int)>(foo), 42);

O bien, « qOverload »:

QFuture<void> future = QtConcurrent::run(qOverload<int>(foo), 42);

Devolución de valores desde la función

Cualquier valor de retorno de la función está disponible a través de ` QFuture`:

extern QString functionReturningAString();
QFuture<QString> future = QtConcurrent::run(functionReturningAString);
...
QString result = future.result();

Si no necesitas el resultado (por ejemplo, porque la función devuelve ` void`), es más eficiente utilizar la sobrecarga de ` QThreadPool::start()` que toma un objeto de función.

Tal y como se ha descrito anteriormente, el paso de argumentos se realiza de la siguiente manera:

extern QString someFunction(const QByteArray &input);

QByteArray bytearray = ...;

QFuture<QString> future = QtConcurrent::run(someFunction, bytearray);
...
QString result = future.result();

Ten en cuenta que la función QFuture::result() se bloquea y espera a que el resultado esté disponible. Utiliza QFutureWatcher para recibir una notificación cuando la función haya finalizado su ejecución y el resultado esté disponible.

Características adicionales de la API

Uso de funciones de miembro

QtConcurrent::run() también admite punteros a funciones miembro. En Qt 6, el primer argumento debe ser el puntero a la función miembro, seguido de una referencia const o de un puntero a una instancia de la clase. Pasar una referencia const resulta útil al llamar a funciones miembro const; pasar un puntero resulta útil para llamar a funciones miembro no const que modifican la instancia.

Por ejemplo, para llamar a ` QByteArray::split()` (una función miembro `const`) en un hilo independiente, se hace así:

// call 'QList<QByteArray>  QByteArray::split(char sep) const' in a separate thread
QByteArray bytearray = "hello world";
QFuture<QList<QByteArray> > future = QtConcurrent::run(&QByteArray::split, bytearray, ' ');
...
QList<QByteArray> result = future.result();

La llamada a una función miembro no const se realiza así:

// call 'void QImage::invertPixels(InvertMode mode)' in a separate thread
QImage image = ...;
QFuture<void> future = QtConcurrent::run(&QImage::invertPixels, &image, QImage::InvertRgba);
...
future.waitForFinished();
// At this point, the pixels in 'image' have been inverted

Uso de funciones lambda

La llamada a una función lambda se realiza de la siguiente manera:

QFuture<void> future = QtConcurrent::run([=]() {
    // Code in this block will run in another thread
});
...

La llamada a una función que modifica un objeto pasado por referencia se realiza de la siguiente manera:

static void addOne(int &n) { ++n; }
...
int n = 42;
QtConcurrent::run(&addOne, std::ref(n)).waitForFinished(); // n == 43

El uso de un objeto ejecutable se realiza de la siguiente manera:

struct TestClass
{
    void operator()(int s1) { s = s1; }
    int s = 42;
};

...

TestClass o;

// Modify original object
QtConcurrent::run(std::ref(o), 15).waitForFinished(); // o.s == 15

// Modify a copy of the original object
QtConcurrent::run(o, 42).waitForFinished(); // o.s == 15

// Use a temporary object
QtConcurrent::run(TestClass(), 42).waitForFinished();

// Ill-formed
QtConcurrent::run(&o, 42).waitForFinished(); // compilation error

Ejecución concurrente con Promise

El modo «Run With Promise» permite un mayor control sobre la tarea en ejecución en comparación con el modo básico de QtConcurrent::run(). Permite informar sobre el progreso de la tarea en ejecución, comunicar múltiples resultados, suspender la ejecución si así se solicita o cancelar la tarea a petición del llamante.

El argumento obligatorio QPromise

Se espera que la función pasada a QtConcurrent::run() en el modo «Run With Promise» tenga un argumento adicional de tipo « QPromise<T> & », donde « T » es el tipo del resultado del cálculo (debe coincidir con el tipo « T » de « QFuture<T>» devuelto por QtConcurrent::run()), como por ejemplo:

extern void aFunction(QPromise<void> &promise);
QFuture<void> future = QtConcurrent::run(aFunction);

El argumento ` promise ` se instancia dentro de la función `QtConcurrent::run()`, y su referencia se pasa a la función ` aFunction` invocada, por lo que el usuario no necesita instanciarlo ni pasarlo explícitamente al llamar a `QtConcurrent::run()` en este modo.

El argumento adicional de tipo ` QPromise ` siempre debe aparecer como primer argumento en la lista de argumentos de la función, como se muestra a continuación:

extern void aFunction(QPromise<void> &promise, int arg1, const QString &arg2);

int integer = ...;
QString string = ...;

QFuture<void> future = QtConcurrent::run(aFunction, integer, string);

Notificación de resultados

A diferencia del modo básico de QtConcurrent::run(), se espera que la función pasada a QtConcurrent::run() en el modo «Run With Promise» devuelva siempre el tipo `void`. La notificación de resultados se realiza a través del argumento adicional de tipo ` QPromise `. También permite la notificación de múltiples resultados, como se muestra a continuación:

void helloWorldFunction(QPromise<QString> &promise)
{
    promise.addResult("Hello");
    promise.addResult("world");
}

QFuture<QString> future = QtConcurrent::run(helloWorldFunction);
...
QList<QString> results = future.results();

Nota: Noes necesario llamar a ` QPromise::start()` ni a ` QPromise::finish()` para indicar el inicio y el final del cálculo (como se haría normalmente al utilizar ` QPromise`). QtConcurrent::run() siempre las llamará antes de iniciar y después de finalizar la ejecución.

Suspender y cancelar la ejecución

La API de QPromise también permite suspender y cancelar el cálculo, si así se solicita:

void aFunction(QPromise<int> &promise)
{
    for (int i = 0; i < 100; ++i) {
        promise.suspendIfRequested();
        if (promise.isCanceled())
            return;

        // computes the next result, may be time consuming like 1 second
        const int res = ... ;
        promise.addResult(res);
    }
}

QFuture<int> future = QtConcurrent::run(aFunction);

... // user pressed a pause button after 10 seconds
future.suspend();

... // user pressed a resume button after 10 seconds
future.resume();

... // user pressed a cancel button after 10 seconds
future.cancel();

La llamada a ` future.suspend() ` solicita a la tarea en ejecución que detenga su ejecución. Tras llamar a este método, la tarea en ejecución se suspenderá tras la siguiente llamada a ` promise.suspendIfRequested() ` en su bucle de iteración. En este caso, la tarea en ejecución se bloqueará en una llamada a ` promise.suspendIfRequested()`. La llamada bloqueada se desbloqueará tras llamar a ` future.resume() `. Tenga en cuenta que, internamente, `suspendIfRequested()` utiliza una condición de espera para desbloquearse, de modo que el hilo en ejecución pasa a un estado inactivo en lugar de malgastar sus recursos cuando está bloqueado, con el fin de comprobar periódicamente si la solicitud de reanudación procede del hilo del autor de la llamada.

La llamada a future.cancel() en la última línea hace que la siguiente llamada a promise.isCanceled() devuelva true y que aFunction se ejecute inmediatamente sin informar de ningún otro resultado.

Nota: Noes necesario llamar a QPromise::finish() para detener el cálculo tras la cancelación (como se haría normalmente al utilizar QPromise). QtConcurrent::run() siempre la llamará tras finalizar la ejecución.

Informes de progreso

También es posible informar del progreso de una tarea independientemente de la notificación de resultados, como por ejemplo:

void aFunction(QPromise<int> &promise)
{
    promise.setProgressRange(0, 100);
    int result = 0;
    for (int i = 0; i < 100;++i) {
       // calcula una parte de la tarea
        const int part =...;
        result+= part;
        promise.setProgressValue(i);
    }
    promise.addResult(result);
}

QFutureWatcher<int> watcher;
QObject::connect(&watcher, &QFutureWatcher::progressValueChanged, [](int progress){
    ...; // actualiza la interfaz gráfica de usuario con el progreso
    qDebug() << "current progress:" << progress;
});
watcher.setFuture(QtConcurrent::run(aFunction));

El llamante instala el QFutureWatcher para el QFuture devuelto por QtConcurrent::run() con el fin de conectarse a su señal progressValueChanged() y actualizar, por ejemplo, la interfaz gráfica de usuario en consecuencia.

Invocación de funciones con el operador sobrecargado ()()

Por defecto, QtConcurrent::run() no admite funtores con el operador () sobrecargado en el modo «Run With Promise ». En el caso de los funtores sobrecargados, el usuario debe especificar explícitamente el tipo de resultado como parámetro de plantilla pasado a QtConcurrent::run(), de la siguiente manera:

struct Functor {
    void operator()(QPromise<int> &) { }
    void operator()(QPromise<double> &) { }
};

Functor f;
run<double>(f); // this will select the 2nd overload
// run(f);      // error, both candidate overloads potentially match

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