Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QPromise Class

template <typename T> class QPromise

La classe QPromise permet de stocker des résultats de calcul accessibles à l'adresse QFuture. Plus...

En-tête : #include <QPromise>
CMake : find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake : QT += core
Depuis : Qt 6.0

Note : Toutes les fonctions de cette classe sont sûres pour les threads.

Fonctions publiques

QPromise()
QPromise(QPromise<T> &&other)
~QPromise()
bool addResult(T &&result, int index = -1)
bool addResult(const T &result, int index = -1)
(since 6.6) bool addResults(const QList<T> &results)
(since 6.6) bool emplaceResult(Args &&... args)
(since 6.6) bool emplaceResultAt(int index, Args &&... args)
void finish()
QFuture<T> future() const
bool isCanceled() const
void setException(const QException &e)
void setException(std::__exception_ptr::exception_ptr e)
void setProgressRange(int minimum, int maximum)
void setProgressValue(int progressValue)
void setProgressValueAndText(int progressValue, const QString &progressText)
void start()
void suspendIfRequested()
void swap(QPromise<T> &other)
QPromise<T> &operator=(QPromise<T> &&other)

Description détaillée

QPromise fournit un moyen simple de communiquer la progression et les résultats du calcul défini par l'utilisateur à QFuture de manière asynchrone. Pour que la communication fonctionne, QFuture doit être construit par QPromise.

Vous pouvez utiliser des charges de travail basées sur QPromise comme alternative au cadre QPromise quand un contrôle fin est nécessaire. Qt Concurrent lorsqu'un contrôle fin est nécessaire ou que la primitive de communication de haut niveau accompagnant QFuture est suffisante.

Le cas le plus simple de collaboration entre la promesse et le futur serait la communication d'un seul résultat :

    QPromise<int> promise;
    QFuture<int> future = promise.future();

    const std::unique_ptr<QThread> thread(QThread::create([] (QPromise<int> promise) {
        promise.start();   // notifies QFuture that the computation is started
        promise.addResult(42);
        promise.finish();  // notifies QFuture that the computation is finished
    }, std::move(promise)));
    thread->start();

    future.waitForFinished();  // blocks until QPromise::finish is called
    future.result();  // returns 42

Par conception, QPromise est un objet qui ne peut être déplacé. Ce comportement permet de s'assurer qu'à chaque fois que la promesse est détruite, l'objet future associé est notifié et n'attendra pas indéfiniment que les résultats soient disponibles. Cependant, cela n'est pas pratique si l'on veut utiliser la même promesse pour rapporter des résultats provenant de différents threads. Il n'y a pas de moyen spécifique pour cela pour le moment, mais des mécanismes connus existent, comme l'utilisation de pointeurs intelligents ou de pointeurs/références bruts. QSharedPointer est un bon choix par défaut si vous voulez copier votre promesse et l'utiliser à plusieurs endroits simultanément. Les pointeurs bruts ou les références sont, dans un sens, plus faciles, et probablement plus performants (puisqu'il n'y a pas besoin de gérer les ressources), mais ils peuvent conduire à des erreurs (dangling).

Voici un exemple de la façon dont une promesse peut être utilisée dans plusieurs threads :

    const auto sharedPromise = std::make_shared<QPromise<int>>();
    QFuture<int> future = sharedPromise->future();

    // ...

    sharedPromise->start();

    // here, QPromise is shared between threads via a smart pointer
    const std::unique_ptr<QThread> threads[] = {
        std::unique_ptr<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(0, 0);  // adds value 0 by index 0
        }, sharedPromise)),
        std::unique_ptr<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(-1, 1);  // adds value -1 by index 1
        }, sharedPromise)),
        std::unique_ptr<QThread>(QThread::create([] (auto sharedPromise) {
            sharedPromise->addResult(-2, 2);  // adds value -2 by index 2
        }, sharedPromise)),
        // ...
    };
    // start all threads
    for (auto& t : threads)
        t->start();

    // ...

    future.resultAt(0);  // waits until result at index 0 becomes available. returns value  0
    future.resultAt(1);  // waits until result at index 1 becomes available. returns value -1
    future.resultAt(2);  // waits until result at index 2 becomes available. returns value -2

    sharedPromise->finish();

Voir aussi QFuture.

Documentation sur les fonctions membres

QPromise::QPromise()

Construit une QPromise avec un état par défaut.

QPromise::QPromise(QPromise<T> &&other)

Move construit une nouvelle QPromise à partir de other.

Voir aussi operator=().

QPromise::~QPromise()

Détruit la promesse.

Note : La promesse passe implicitement à l'état annulé lors de sa destruction, sauf si finish() est appelé au préalable par l'utilisateur.

bool QPromise::addResult(const T &result, int index = -1)

bool QPromise::addResult(T &&result, int index = -1)

Identique à

emplaceResultAt(index, result);            // first overload
emplaceResultAt(index, std::move(result)); // second overload

ou, si index == -1 (par défaut)

emplaceResult(result);            // first overload
emplaceResult(std::move(result)); // second overload

Voir aussi emplaceResultAt(), emplaceResult() et addResults().

[since 6.6] bool QPromise::addResults(const QList<T> &results)

Ajoute results à la fin de la collection de résultats internes.

Retourne true lorsque results est ajouté à la collection.

Retourne false lorsque cette promesse est dans l'état annulé ou terminé.

Cette méthode est plus efficace que le bouclage sur addResult(), car les futures associés ne seront notifiés qu'une seule fois par appel à addResults(), au lieu d'une fois par élément contenu dans results, comme ce serait le cas avec des appels individuels à addResult(). Mais si le calcul de chaque élément prend du temps, le code du destinataire (futur) ne peut pas progresser tant que tous les résultats n'ont pas été notifiés, donc n'utilisez cette fonction que si le calcul d'éléments consécutifs est relativement rapide.

Cette fonction a été introduite dans Qt 6.6.

Voir également addResult().

[since 6.6] template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResultAt(int index, Args &&... args)

[since 6.6] template <typename... Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise::emplaceResult(Args &&... args)

Ajoute un résultat construit à partir de args... à la collection interne de résultats à la position index (emplaceResultAt()) ou à la fin de la collection (emplaceResult()).

Retourne true lorsque le résultat a été ajouté à la collection.

Retourne false lorsque cette promesse est dans l'état annulé ou terminé ou lorsque le résultat a été rejeté. addResult() rejette l'ajout d'un résultat s'il existe déjà un autre résultat dans la collection stocké au même index.

Ces fonctions ne participent aux résolutions de surcharge que si T est constructible à partir de args....

Vous pouvez obtenir un résultat à un index spécifique en appelant QFuture::resultAt().

Remarque : il est possible de spécifier un index arbitraire et de demander un résultat à cet index. Cependant, certaines méthodes QFuture fonctionnent avec des résultats continus. Par exemple, les approches itératives qui utilisent QFuture::resultCount() ou QFuture::const_iterator. Afin d'obtenir tous les résultats disponibles sans se soucier de savoir s'il y a des trous d'index ou non, utilisez QFuture::results().

Ces fonctions ont été introduites dans Qt 6.6.

Voir également addResult() et addResults().

void QPromise::finish()

Signale que le calcul est terminé. Une fois le calcul terminé, aucun nouveau résultat ne sera ajouté lors de l'appel à addResult(). Cette méthode accompagne start().

Voir également QFuture::isFinished(), QFuture::waitForFinished() et start().

QFuture<T> QPromise::future() const

Retourne un futur associé à cette promesse.

bool QPromise::isCanceled() const

Renvoie si le calcul a été annulé avec la fonction QFuture::cancel(). La valeur renvoyée true indique que le calcul doit être terminé et que la fonction finish() doit être appelée.

Remarque : après l'annulation, les résultats actuellement disponibles peuvent encore être consultés par un futur, mais de nouveaux résultats ne seront pas ajoutés lors de l'appel à addResult().

void QPromise::setException(const QException &e)

Définit l'exception e comme étant le résultat du calcul.

Note : Vous pouvez définir au maximum une exception pendant l'exécution du calcul.

Remarque : Cette méthode n'a aucun effet après QFuture::cancel() ou finish().

Voir aussi isCanceled().

void QPromise::setException(std::__exception_ptr::exception_ptr e)

Il s'agit d'une fonction surchargée.

void QPromise::setProgressRange(int minimum, int maximum)

Définit la plage de progression du calcul comme étant comprise entre minimum et maximum.

Si maximum est plus petit que minimum, minimum devient la seule valeur légale.

La valeur de progression est réinitialisée à minimum.

L'utilisation de la plage de progression peut être désactivée en utilisant setProgressRange(0, 0). Dans ce cas, la valeur de progression est également réinitialisée à 0.

Voir aussi QFuture::progressMinimum(), QFuture::progressMaximum() et QFuture::progressValue().

void QPromise::setProgressValue(int progressValue)

Fixe la valeur de progression du calcul à progressValue. Il est possible de n'incrémenter que la valeur de progression. Il s'agit d'une méthode de commodité pour appeler setProgressValueAndText(progressValue, QString()).

Si progressValue sort de la plage de progression, cette méthode n'a aucun effet.

Voir aussi QFuture::progressValue() et setProgressRange().

void QPromise::setProgressValueAndText(int progressValue, const QString &progressText)

Fixe la valeur d'avancement et le texte d'avancement du calcul à progressValue et progressText respectivement. Il est possible de n'incrémenter que la valeur de progression.

Note : Cette fonction n'a aucun effet si la promesse est dans l'état annulé ou terminé.

Voir aussi QFuture::progressValue(), QFuture::progressText(), QFuture::cancel(), et finish().

void QPromise::start()

Signale que le calcul a commencé. Il est important d'appeler cette méthode pour indiquer le début du calcul, car les méthodes QFuture s'appuient sur cette information.

Remarque : une attention particulière est requise lorsque start() est appelé à partir d'un thread nouvellement créé. Dans ce cas, l'appel peut naturellement être retardé en raison des détails d'implémentation de l'ordonnancement des threads.

Voir également QFuture::isStarted(), QFuture::waitForFinished() et finish().

void QPromise::suspendIfRequested()

Suspend conditionnellement le fil d'exécution en cours et attend d'être repris ou annulé par les méthodes correspondantes de QFuture. Cette méthode ne bloque pas, sauf si la suspension du calcul est demandée par QFuture::suspend() ou une autre méthode connexe. Si vous souhaitez vérifier que l'exécution a été suspendue, utilisez QFuture::isSuspended().

Remarque : lors de l'utilisation de la même promesse dans plusieurs threads, QFuture::isSuspended() devient true dès qu'au moins un des threads avec la promesse est suspendu.

Les extraits de code suivants illustrent l'utilisation du mécanisme de suspension :

    // Create promise and future
    QPromise<int> promise;
    QFuture<int> future = promise.future();

    promise.start();
    // Start a computation thread that supports suspension and cancellation
    const std::unique_ptr<QThread> thread(QThread::create([] (QPromise<int> promise) {
        for (int i = 0; i < 100; ++i) {
            promise.addResult(i);
            promise.suspendIfRequested();   // support suspension
            if (promise.isCanceled())       // support cancellation
                break;
        }
        promise.finish();
    }, std::move(promise)));
    thread->start();

QFuture::suspend() demande à la promesse associée de se suspendre :

    future.suspend();

Après que QFuture::isSuspended() est devenu true, vous pouvez obtenir des résultats intermédiaires :

    future.resultCount();  // returns some number between 0 and 100
    for (int i = 0; i < future.resultCount(); ++i) {
        // process results available before suspension
    }

Une fois suspendu, vous pouvez reprendre ou annuler le calcul en attente :

    future.resume();  // resumes computation, this call will unblock the promise
    // alternatively, call future.cancel() to stop the computation

    future.waitForFinished();
    future.results();  // returns all computation results - array of values from 0 to 99

Voir aussi QFuture::resume(), QFuture::cancel(), QFuture::setSuspended() et QFuture::toggleSuspended().

[noexcept] void QPromise::swap(QPromise<T> &other)

Échange cette promesse avec other. Cette opération est très rapide et n'échoue jamais.

[noexcept] QPromise<T> &QPromise::operator=(QPromise<T> &&other)

Move assigne other à cette promesse et renvoie une référence à cette promesse.

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