QtFuture Namespace

Documentación de funciones

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 argumentos, se devuelve un QFuture<void>. Si signal recibe un único argumento, el resultado QFuture se rellenará con el valor del argumento de la señal. Si signal toma múltiples argumentos, el resultado QFuture se rellena con std::tuple almacenando los valores de los argumentos de la señal. Si sender se destruye antes de que se emita signal, el resultado QFuture 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 podemos iniciar la continuación en un nuevo hilo o en un pool 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 un slot invocado por la conexión signal-slot de Qt se considera un comportamiento indefinido, si no se maneja dentro del slot. Pero con QFuture::connect(), se pueden lanzar y manejar 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
});

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 QFuture que ya tiene 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 QFuture que ya tiene 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
}

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, QtFuture::if_container_with_input_iterators<Container> = true> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

Toma un contenedor de entrada container y devuelve un QFuture con múltiples resultados de tipo ContainedType inicializados a partir de los valores del 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 sólo si Container tiene iteradores de entrada.

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 QFuture con múltiples 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 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 QFuture que ya tiene un resultado value. El QFuture devuelto tiene un tipo std::decay_t<T>, donde T no es void. El QFuture devuelto ya estará en el estado terminado.

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 vacío QFuture. Este tipo de QFuture no puede almacenar ningún resultado. Se puede utilizar para consultar el estado del cálculo. El QFuture devuelto ya estará 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.

Ver 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 tiene éxito cuando todos los futures envases de tipos arbitrarios se completan. OutputSequence es una secuencia de futuros completados. El tipo de sus entradas es std::variant<Futures...>. Por cada QFuture<T> pasado a whenAll(), la entrada en la posición correspondiente en 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 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);

El futuro devuelto siempre se completa con éxito después de que se completen todos los futuros especificados. No importa si alguno de estos futuros se completa con error o se cancela. Puede utilizar .then() para procesar los futuros completados después de que el futuro devuelto por whenAll() tenga é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);
            }
            //...
        });

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 QFuture que tiene éxito cuando todos los futuros de first a last se completan. first y last son iteradores a una secuencia de futuros empaquetados de 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 un QList de 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());

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

El futuro devuelto siempre se completa con éxito después de que se completen todos los futuros especificados. No importa si alguno de estos futuros se completa con error o se cancela. Puede utilizar .then() para procesar los futuros completados después de que el futuro devuelto por whenAll() tenga é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
                }
            }
        });

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 QFuture que tiene éxito cuando se completa cualquiera de los futures. futures puede empaquetar tipos arbitrarios. El futuro devuelto empaqueta el valor del tipo std::variant<Futures...> que a su vez empaqueta el primer QFuture completado de futures. Puede utilizar std::variant::index() para averiguar el índice del futuro en la secuencia de futures que terminó primero.

El futuro devuelto siempre se completa con éxito después de que se complete el primer futuro de los futuros especificados. No importa si el primer futuro finaliza con error o se cancela. Puedes utilizar .then() para procesar el resultado después de que el futuro devuelto por whenAny() tenga é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);
    //...
});

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 QFuture que tiene éxito cuando se completa cualquiera de los futuros de first a last. first y last son iteradores a una secuencia de futuros que empaquetan el tipo T. El futuro devuelto empaqueta un valor de tipo QtFuture::WhenAnyResult<T> que a su vez empaqueta 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 en la estructura QtFuture::WhenAnyResult y un QFuture<T> construido por defecto para el campo future. Nótese que un QFuture construido por defecto es un futuro completado en un estado cancelado.

El futuro devuelto siempre se completa con éxito después de que se complete el primer futuro de los futuros especificados. No importa si el primer futuro se completa con error o se cancela. Puedes utilizar .then() para procesar el resultado después de que el futuro devuelto por whenAny() tenga é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;
            //...
        });

Esta función se introdujo en Qt 6.3.

Véase también QtFuture::WhenAnyResult.