En esta página

QtFuture Namespace

Contiene diversos identificadores utilizados por la clase ` QFuture `. Más...

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

Clases

(since 6.3) struct WhenAnyResult

Tipos

(since 6.0) enum class Launch { Sync, Async, Inherit }

Funciones

QFuture<QtFuture::ArgsType<Signal>> connect(Sender *sender, Signal signal)
(since 6.1) QFuture<T> makeExceptionalFuture(const QException &exception)
(since 6.1) QFuture<T> makeExceptionalFuture(std::__exception_ptr::exception_ptr exception)
(since 6.6) QFuture<QtFuture::ContainedType<Container>> makeReadyRangeFuture(Container &&container)
(since 6.6) QFuture<ValueType> makeReadyRangeFuture(std::initializer_list<ValueType> values)
(since 6.6) QFuture<std::decay_t<T>> makeReadyValueFuture(T &&value)
(since 6.6) QFuture<void> makeReadyVoidFuture()
(since 6.3) QFuture<OutputSequence> whenAll(Futures &&... futures)
(since 6.3) QFuture<OutputSequence> whenAll(InputIt first, InputIt last)
(since 6.3) QFuture<std::variant<std::decay_t<Futures>...>> whenAny(Futures &&... futures)
(since 6.3) QFuture<QtFuture::WhenAnyResult<T>> whenAny(InputIt first, InputIt last)

Descripción detallada

Clases

clase WhenAnyResult

QtFuture::WhenAnyResult se utiliza para representar el resultado de ` QtFuture::whenAny()`. Más...

Documentación del tipo

[since 6.0] enum class QtFuture::Launch

Representa las políticas de ejecución para ejecutar una continuación de tipo « QFuture ».

ConstanteValorDescripción
QtFuture::Launch::Sync0La continuación se iniciará en el mismo hilo que cumple la promesa asociada al futuro al que se adjuntó la continuación o, si ya ha finalizado, la continuación se invocará inmediatamente en el hilo que ejecuta then().
QtFuture::Launch::Async1La continuación se iniciará en un hilo independiente tomado del QThreadPool global.
QtFuture::Launch::Inherit2La continuación heredará la política de ejecución o el grupo de subprocesos del futuro al que está vinculada.

Sync se utiliza como política de ejecución por defecto.

Esta enumeración se introdujo en Qt 6.0.

Véase también ` QFuture::then()` y ` QThreadPool::globalInstance()`.

Documentación de la función

template < typename Sender, typename Signal, typename = QtPrivate::EnableIfInvocable<Sender, Signal> > QFuture<QtFuture::ArgsType<Signal>> QtFuture::connect(Sender *sender, Signal signal)

Crea y devuelve un ` QFuture `, que estará disponible cuando el ` sender ` emita el ` signal`. Si el ` signal ` no toma ningún argumento, se devuelve un ` QFuture` de tipo `<void>`. Si el ` signal ` toma un único argumento, el ` QFuture ` resultante se rellenará con el valor del argumento de la señal. Si el ` signal ` toma varios argumentos, el ` QFuture ` resultante se rellenará con un `std::tuple` que almacena los valores de los argumentos de la señal. Si el ` sender ` se destruye antes de que se emita el ` signal `, el ` QFuture ` resultante se cancelará.

Por ejemplo, supongamos que tenemos el siguiente objeto:

class Object : public QObject
{
    Q_OBJECT
    //...
signals:
    void noArgSignal();
    void singleArgSignal(int value);
    void multipleArgs(int value1, double value2, const QString &value3);
};

Podemos conectar sus señales a objetos ` QFuture ` de la siguiente manera:

Object object;
QFuture<void> voidFuture = QtFuture::connect(&object, &Object::noArgSignal);
QFuture<int> intFuture = QtFuture::connect(&object, &Object::singleArgSignal);

using Args = std::tuple<int, double, QString>;
QFuture<Args> tupleFuture = QtFuture::connect(&object, &Object::multipleArgs);

También podemos encadenar continuaciones para que se ejecuten cuando se emita una señal:

QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) {
    // do something with the value
});

También puedes iniciar la continuación en un nuevo hilo o en un grupo de hilos personalizado utilizando las políticas de QtFuture::Launch. Por ejemplo:

QtFuture::connect(&object, &Object::singleArgSignal).then(QtFuture::Launch::Async, [](int value) {
    // this will run in a new thread
});

Lanzar una excepción desde una ranura invocada por la conexión de señal-ranura de Qt se considera un comportamiento indefinido, si no se gestiona dentro de la ranura. Pero con QFuture::connect(), puedes lanzar y gestionar excepciones desde las continuaciones:

QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) {
    //...
    throw std::exception();
    //...
}).onFailed([](const std::exception &e) {
    // handle the exception
}).onFailed([] {
    // handle other exceptions
});

Nota: El futuro conectado solo se cumplirá una vez, cuando se emita la señal por primera vez.

Véase también QFuture y QFuture::then().

[since 6.1] template <typename T = void> QFuture<T> QtFuture::makeExceptionalFuture(const QException &exception)

Crea y devuelve un objeto ` QFuture ` que ya contiene una excepción ` exception`.

QException e;
auto f = QtFuture::makeExceptionalFuture<int>(e);
...
try {
    f.result(); // throws QException
} catch (QException &) {
    // handle exception here
}

Esta función se introdujo en Qt 6.1.

Véase también « QFuture» , « QException », « QtFuture::makeReadyVoidFuture()» y « QtFuture::makeReadyValueFuture()».

[since 6.1] template <typename T = void> QFuture<T> QtFuture::makeExceptionalFuture(std::__exception_ptr::exception_ptr exception)

Crea y devuelve un objeto ` QFuture ` que ya contiene una excepción ` exception`.

struct TestException
{
};
...
auto exception = std::make_exception_ptr(TestException());
auto f = QtFuture::makeExceptionalFuture<int>(exception);
...
try {
    f.result(); // throws TestException
} catch (TestException &) {
    // handle exception here
}

Se trata de una función sobrecargada.

Esta función se introdujo en Qt 6.1.

Véase también QFuture, QException, QtFuture::makeReadyVoidFuture() y QtFuture::makeReadyValueFuture().

[since 6.6] template <typename Container> requires if_container_with_input_iterators<Container> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

Toma un contenedor de entrada container y devuelve un QFuture con varios resultados de tipo ContainedType inicializados a partir de los valores de container.

const std::vector<int> values{1, 2, 3};
auto f = QtFuture::makeReadyRangeFuture(values);
    ...
const int count = f.resultCount(); // count == 3
const auto results = f.results(); // results == { 1, 2, 3 }

Restricciones

Participa en la resolución de sobrecargas únicamente si el Container tiene iteradores de entrada.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.6.

Véase también QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() y QtFuture::makeExceptionalFuture().

[since 6.6] template <typename ValueType> QFuture<ValueType> QtFuture::makeReadyRangeFuture(std::initializer_list<ValueType> values)

Devuelve un objeto de tipo ` QFuture ` con varios resultados de tipo ` ValueType `, inicializados a partir de la lista de inicializadores de entrada ` values`.

auto f = QtFuture::makeReadyRangeFuture({1, 2, 3});
    ...
const int count = f.resultCount(); // count == 3
const auto results = f.results(); // results == { 1, 2, 3 }

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.6.

Véase también QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() y QtFuture::makeExceptionalFuture().

[since 6.6] template <typename T> QFuture<std::decay_t<T>> QtFuture::makeReadyValueFuture(T &&value)

Crea y devuelve un objeto ` QFuture ` que ya contiene un resultado ` value`. El objeto ` QFuture ` devuelto es de tipo `std::decay_t<T>`, donde `T` no es `void`. El objeto ` QFuture ` devuelto ya se encontrará en estado «finished».

auto f = QtFuture::makeReadyValueFuture(std::make_unique<int>(42));
//...
const int result = *f.takeResult(); // result == 42

Esta función se introdujo en Qt 6.6.

Véase también QFuture, QtFuture::makeReadyRangeFuture(), QtFuture::makeReadyVoidFuture() y QtFuture::makeExceptionalFuture().

[since 6.6] QFuture<void> QtFuture::makeReadyVoidFuture()

Crea y devuelve un objeto ` QFuture` de tipo `void`. Dicho objeto ` QFuture ` no puede almacenar ningún resultado. Se puede utilizar para consultar el estado del cálculo. El objeto ` QFuture ` devuelto ya se encontrará en el estado «finalizado».

auto f = QtFuture::makeReadyVoidFuture();
//...
const bool started = f.isStarted(); // started == true
const bool running = f.isRunning(); // running == false
const bool finished = f.isFinished(); // finished == true

Esta función se introdujo en Qt 6.6.

Véase también QFuture, QFuture::isStarted(), QFuture::isRunning(), QFuture::isFinished(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture() y QtFuture::makeExceptionalFuture().

[since 6.3] template <typename OutputSequence, typename... Futures> QFuture<OutputSequence> QtFuture::whenAll(Futures &&... futures)

Devuelve un nuevo ` QFuture ` que se resuelve con éxito cuando se completan todos los ` futures ` que empaquetan tipos arbitrarios. ` OutputSequence ` es una secuencia de futuros completados. El tipo de sus entradas es ` std::variant<Futures...>`. Para cada ` QFuture<T> ` pasado a ` whenAll()`, la entrada en la posición correspondiente de ` OutputSequence ` será un ` std::variant ` que contenga ese ` QFuture<T>`, en su estado completado. Si no se especifica el tipo de ` OutputSequence `, los futuros resultantes se devolverán en un ` QList ` de tipo ` std::variant<Futures...>`. Por ejemplo:

QFuture<int> intFuture /*...*/;
QFuture<QString> stringFuture /*...*/;
QFuture<void> voidFuture /*...*/;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

// whenAll has type QFuture<QList<FuturesVariant>>
auto whenAll = QtFuture::whenAll(intFuture, stringFuture, voidFuture);

// whenAllVector has type QFuture<std::vector<FuturesVariant>>
auto whenAllVector =
        QtFuture::whenAll<std::vector<FuturesVariant>>(intFuture, stringFuture, voidFuture);

Nota: La secuencia de salida debe admitir el acceso aleatorio y la operación resize().

El «future» devuelto siempre se completa con éxito una vez que se hayan completado todos los «futures» especificados. No importa si alguno de estos «futures» se completa con un error o se cancela. Puedes utilizar .then() para procesar los «futures» completados después de que el «future» devuelto por whenAll() se haya completado con éxito:

QFuture<int> intFuture /*...*/;
QFuture<QString> stringFuture /*...*/;
QFuture<void> voidFuture /*...*/;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

QtFuture::whenAll(intFuture, stringFuture, voidFuture)
        .then([](const QList<FuturesVariant> &results) {
            //...
            for (auto result : results)
            {
                // assuming handleResult() is overloaded based on the QFuture type
                std::visit([](auto &&future) { handleResult(future); }, result);
            }
            //...
        });

Nota: Si los futuros de entrada se completan en hilos diferentes, el futuro devuelto por este método se completará en el hilo en el que se complete el último futuro. Por lo tanto, las continuaciones asociadas al futuro devuelto por whenAll() no siempre pueden dar por sentado en qué hilo se ejecutarán. Utiliza la sobrecarga de .then() que toma un objeto de contexto si deseas controlar en qué hilo se invocan las continuaciones.

Esta función se introdujo en Qt 6.3.

[since 6.3] template <typename OutputSequence, typename InputIt> QFuture<OutputSequence> QtFuture::whenAll(InputIt first, InputIt last)

Devuelve un nuevo objeto ` QFuture ` que se considera completado cuando se hayan completado todos los futuros de ` first ` a ` last `. ` first ` y ` last ` son iteradores de una secuencia de futuros que contienen el tipo ` T`. ` OutputSequence ` es una secuencia que contiene todos los futuros completados de ` first ` a ` last`, que aparecen en el mismo orden que en la entrada. Si no se especifica el tipo de ` OutputSequence `, los futuros resultantes se devolverán en una secuencia ` QList ` del tipo ` QFuture<T>`. Por ejemplo:

QList<QFuture<int>> inputFutures {/*...*/};

// whenAll has type QFuture<QList<QFuture<int>>>
auto whenAll = QtFuture::whenAll(inputFutures.begin(), inputFutures.end());

// whenAllVector has type QFuture<std::vector<QFuture<int>>>
auto whenAllVector =
        QtFuture::whenAll<std::vector<QFuture<int>>>(inputFutures.begin(), inputFutures.end());

Nota: La secuencia de salida debe admitir el acceso aleatorio y la operación resize().

Si first es igual a last, esta función devuelve un QFuture listo que contiene un OutputSequence vacío.

El «future» devuelto siempre se completa con éxito una vez que se han completado todos los «futures» especificados. No importa si alguno de estos «futures» se completa con un error o se cancela. Puedes utilizar ` .then() ` para procesar los «futures» completados después de que el «future» devuelto por ` whenAll() ` se haya completado con éxito:

QList<QFuture<int>> inputFutures {/*...*/};

QtFuture::whenAll(inputFutures.begin(), inputFutures.end())
        .then([](const QList<QFuture<int>> &results) {
            for (auto future : results) {
                if (future.isCanceled())
                {
                    // handle the cancellation (possibly due to an exception)
                }
                else
                {
                    // do something with the result
                }
            }
        });

Nota: Si los futuros de entrada se completan en hilos diferentes, el futuro devuelto por este método se completará en el hilo en el que se complete el último futuro. Por lo tanto, las continuaciones asociadas al futuro devuelto por ` whenAll() ` no siempre pueden dar por sentado en qué hilo se ejecutarán. Utiliza la sobrecarga de ` .then() ` que toma un objeto de contexto si deseas controlar en qué hilo se invocan las continuaciones.

Esta función se introdujo en Qt 6.3.

[since 6.3] template <typename... Futures> QFuture<std::variant<std::decay_t<Futures>...>> QtFuture::whenAny(Futures &&... futures)

Devuelve un nuevo objeto ` QFuture ` que se resuelve con éxito cuando se completa cualquiera de los ` futures `. ` futures ` puede contener tipos arbitrarios. El `future` devuelto contiene el valor de tipo ` std::variant<Futures...> `, que a su vez contiene el primer ` QFuture ` completado de ` futures`. Puedes utilizar `std::variant::index()` para averiguar el índice del `future` en la secuencia de ` futures ` que se completó en primer lugar.

El «future» devuelto siempre se completa con éxito una vez que se haya completado el primer «future» de entre los «futures» especificados. No importa si el primer «future» se completa con un error o se cancela. Puedes utilizar ` .then() ` para procesar el resultado una vez que el «future» devuelto por ` whenAny() ` haya finalizado con éxito:

QFuture<int> intFuture /*...*/;
QFuture<QString> stringFuture /*...*/;
QFuture<void> voidFuture /*...*/;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

QtFuture::whenAny(intFuture, stringFuture, voidFuture).then([](const FuturesVariant &result) {
    //...
    // assuming handleResult() is overloaded based on the QFuture type
    std::visit([](auto &&future) { handleResult(future); }, result);
    //...
});

Nota: Si los futuros de entrada se completan en hilos diferentes, el futuro devuelto por este método se completará en el hilo en el que se complete el primer futuro. Por lo tanto, las continuaciones asociadas al «future» devuelto por whenAny() no siempre pueden dar por sentado en qué hilo se ejecutarán. Utiliza la sobrecarga de .then() que toma un objeto de contexto si deseas controlar en qué hilo se invocan las continuaciones.

Esta función se introdujo en Qt 6.3.

[since 6.3] template <typename T, typename InputIt> QFuture<QtFuture::WhenAnyResult<T>> QtFuture::whenAny(InputIt first, InputIt last)

Devuelve un nuevo objeto ` QFuture ` que se resuelve con éxito cuando se completa cualquiera de los futuros desde ` first ` hasta ` last `. ` first ` y ` last ` son iteradores de una secuencia de futuros que contienen objetos de tipo ` T`. El futuro devuelto contiene un valor de tipo ` QtFuture::WhenAnyResult<T> `, que a su vez contiene el índice del primer ` QFuture ` completado y el propio ` QFuture `. Si first es igual a last, esta función devuelve un QFuture listo que tiene -1 para el campo index de la estructura QtFuture::WhenAnyResult y un QFuture<T> construido por defecto para el campo future. Ten en cuenta que un QFuture construido por defecto es un «future» completado en estado cancelado.

El futuro devuelto siempre se completa con éxito una vez que se completa el primer futuro de entre los futuros especificados. No importa si el primer futuro se completa con un error o si se cancela. Puedes utilizar .then() para procesar el resultado una vez que el futuro devuelto por whenAny() se haya completado con éxito:

QList<QFuture<int>> inputFutures /*...*/;

QtFuture::whenAny(inputFutures.begin(), inputFutures.end())
        .then([](const QtFuture::WhenAnyResult<int> &result) {
            qsizetype index = result.index;
            QFuture<int> future = result.future;
            //...
        });

Nota: Si los futuros de entrada se completan en hilos diferentes, el futuro devuelto por este método se completará en el hilo en el que se complete el primer futuro. Por lo tanto, las continuaciones asociadas al «future» devuelto por ` whenAny() ` no siempre pueden dar por sentado en qué hilo se ejecutarán. Utiliza la sobrecarga de ` .then() ` que toma un objeto de contexto si deseas controlar en qué hilo se invocan las continuaciones.

Esta función se introdujo en Qt 6.3.

Véase también QtFuture::WhenAnyResult.

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