QFutureWatcher Class

// Instantiate the objects and connect to the finished signal.
MyClass myObject;
QFutureWatcher<int> watcher;
QObject::connect(&watcher, &QFutureWatcher<int>::finished, &myObject, &MyClass::handleFinished);

// Start the computation.
QFuture<int> future = QtConcurrent::run([result](){ /*...*/ return result;});
watcher.setFuture(future);

Documentation sur les fonctions membres

[explicit] QFutureWatcher::QFutureWatcher(QObject *parent = nullptr)

Construit un nouveau QFutureWatcher avec les données parent. Tant qu'un futur n'est pas défini avec setFuture(), les fonctions isStarted(), isCanceled() et isFinished() renvoient true.

[virtual] QFutureWatcher::~QFutureWatcher()

Détruit le site QFutureWatcher.

[slot] void QFutureWatcher::cancel()

Annule le calcul asynchrone représenté par future(). Notez que l'annulation est asynchrone. Utilisez waitForFinished() après avoir appelé cancel() si vous avez besoin d'une annulation synchrone.

Les résultats actuellement disponibles peuvent toujours être consultés sur un site QFuture annulé, mais les nouveaux résultats ne seront pas disponibles après l'appel à cette fonction. En outre, cette fonction QFutureWatcher n'émettra pas de signaux de progression ni de résultats prêts une fois qu'elle aura été annulée. Cela inclut les signaux progressValueChanged(), progressRangeChanged(), progressTextChanged(), resultReadyAt() et resultsReadyAt().

Il faut savoir que tous les calculs asynchrones en cours d'exécution ne peuvent pas être annulés. Par exemple, le signal QFuture renvoyé par QtConcurrent::run() ne peut pas être annulé, mais le signal QFuture renvoyé par QtConcurrent::mappedReduced() peut l'être.

[signal] void QFutureWatcher::canceled()

Ce signal est émis si le futur observé est annulé.

[signal] void QFutureWatcher::finished()

Ce signal est émis lorsque le futur observé se termine.

QFuture<T> QFutureWatcher::future() const

Renvoie le futur observé.

Voir aussi setFuture().

bool QFutureWatcher::isCanceled() const

Renvoie true si le calcul asynchrone a été annulé avec la fonction cancel(), ou si aucun futur n'a été défini ; sinon, renvoie false.

Sachez que le calcul peut toujours être en cours d'exécution même si cette fonction renvoie true. Voir cancel() pour plus de détails.

bool QFutureWatcher::isFinished() const

Renvoie true si le calcul asynchrone représenté par future() est terminé, ou si aucun futur n'a été défini ; sinon, renvoie false.

bool QFutureWatcher::isRunning() const

Renvoie true si le calcul asynchrone représenté par future() est en cours d'exécution ; sinon, renvoie false.

bool QFutureWatcher::isStarted() const

Renvoie true si le calcul asynchrone représenté par future() a été lancé, ou si aucun futur n'a été défini ; sinon, renvoie false.

[since 6.0] bool QFutureWatcher::isSuspended() const

Renvoie true si une suspension du calcul asynchrone a été demandée et qu'elle est effective, ce qui signifie que plus aucun résultat ou changement de progression n'est attendu.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi suspended(), setSuspended(), et isSuspending().

[since 6.0] bool QFutureWatcher::isSuspending() const

Renvoie true si le calcul asynchrone a été suspendu avec la fonction suspend(), mais que le travail n'est pas encore suspendu et que le calcul est toujours en cours. Retourne false dans le cas contraire.

Pour vérifier si la suspension est effective, utilisez plutôt isSuspended().

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setSuspended(), toggleSuspended(), et isSuspended().

int QFutureWatcher::progressMaximum() const

Renvoie le maximum de progressValue().

Voir aussi progressValue() et progressMinimum().

int QFutureWatcher::progressMinimum() const

Renvoie le minimum progressValue().

Voir aussi progressValue() et progressMaximum().

[signal] void QFutureWatcher::progressRangeChanged(int minimum, int maximum)

La plage de progression pour l'avenir surveillé est passée à minimum et maximum.

QString QFutureWatcher::progressText() const

Renvoie la représentation textuelle (facultative) de la progression telle qu'elle est rapportée par le calcul asynchrone.

Attention, tous les calculs ne fournissent pas une représentation textuelle de la progression, et cette fonction peut donc renvoyer une chaîne vide.

[signal] void QFutureWatcher::progressTextChanged(const QString &progressText)

Ce signal est émis lorsque le futur observé rapporte des informations textuelles sur l'état d'avancement, progressText.

int QFutureWatcher::progressValue() const

Renvoie la valeur actuelle de la progression, qui se situe entre progressMinimum() et progressMaximum().

Voir aussi progressMinimum() et progressMaximum().

[signal] void QFutureWatcher::progressValueChanged(int progressValue)

Ce signal est émis lorsque le futur observé fait état d'une progression, progressValue donne la progression actuelle. Afin d'éviter de surcharger la boucle événementielle de l'interface graphique, QFutureWatcher limite le taux d'émission du signal de progression. Cela signifie que les auditeurs connectés à ce slot peuvent ne pas recevoir tous les rapports d'avancement du futur. La dernière mise à jour de la progression (où progressValue est égal à la valeur maximale) sera toujours transmise.

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFutureWatcher::result() const

Renvoie le premier résultat de future(). Si le résultat n'est pas immédiatement disponible, cette fonction se bloque et attend que le résultat soit disponible. Il s'agit d'une méthode de commodité pour appeler resultAt(0).

Voir aussi resultAt().

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFutureWatcher::resultAt(int index) const

Renvoie le résultat à index dans future(). Si le résultat n'est pas immédiatement disponible, cette fonction se bloque et attend que le résultat soit disponible.

Voir aussi result().

[signal] void QFutureWatcher::resultReadyAt(int index)

Ce signal est émis lorsque le futur observé rapporte un résultat prêt à l'adresse index. Si le futur rapporte plusieurs résultats, l'index indiquera de quel résultat il s'agit. Les résultats peuvent être rapportés dans le désordre. Pour obtenir le résultat, appelez resultAt(index) ;

[signal] void QFutureWatcher::resultsReadyAt(int beginIndex, int endIndex)

Ce signal est émis lorsque le futur observé rapporte des résultats prêts. Les résultats sont indexés de beginIndex à endIndex.

[slot] void QFutureWatcher::resume()

Reprend le calcul asynchrone représenté par future(). Il s'agit d'une méthode de commodité qui appelle simplement setSuspended(false).

Voir aussi suspend().

[signal] void QFutureWatcher::resumed()

Ce signal est émis lorsque le futur observé est repris.

void QFutureWatcher::setFuture(const QFuture<T> &future)

Commence à observer le site future.

Si future a déjà démarré, l'observateur émet d'abord des signaux qui informent leurs auditeurs de l'état du futur. Les signaux suivants seront, le cas échéant, émis dans l'ordre indiqué : started(), progressRangeChanged(), progressValueChanged(), progressTextChanged(), resultsReadyAt(), resultReadyAt(), suspending(), suspended(), canceled() et finished(). Parmi ceux-ci, resultsReadyAt() et resultReadyAt() peuvent être émis plusieurs fois pour couvrir tous les résultats disponibles. progressValueChanged() et progressTextChanged() ne seront émis qu'une seule fois pour la dernière valeur de progression et le dernier texte disponibles.

Pour éviter une situation de course, il est important d'appeler cette fonction après avoir effectué les connexions.

Voir aussi future().

void QFutureWatcher::setPendingResultsLimit(int limit)

La fonction setPendingResultsLimit() permet de contrôler l'étranglement. Lorsque le nombre de signaux en attente resultReadyAt() ou resultsReadyAt() dépasse la limite limit, le calcul représenté par le futur est automatiquement interrompu. Le calcul reprendra dès que le nombre de signaux en attente sera inférieur à limit.

[slot, since 6.0] void QFutureWatcher::setSuspended(bool suspend)

Si suspend est vrai, cette fonction suspend le calcul asynchrone représenté par future(). Si le calcul est déjà suspendu, cette fonction ne fait rien. QFutureWatcher ne cesse pas immédiatement de fournir des signaux de progression et de résultat prêt lorsque le futur est suspendu. Au moment de la suspension, il se peut que des calculs soient encore en cours et ne puissent pas être arrêtés. Les signaux relatifs à ces calculs continueront d'être émis.

Si suspend est faux, cette fonction reprend le calcul asynchrone. Si le calcul n'a pas été suspendu auparavant, cette fonction ne fait rien.

Il faut savoir que tous les calculs ne peuvent pas être suspendus. Par exemple, le QFuture renvoyé par QtConcurrent::run() ne peut pas être suspendu ; mais le QFuture renvoyé par QtConcurrent::mappedReduced() peut l'être.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi suspended(), suspend(), resume(), et toggleSuspended().

[signal] void QFutureWatcher::started()

Ce signal est émis lorsque ce QFutureWatcher commence à regarder le futur défini avec setFuture().

[slot, since 6.0] void QFutureWatcher::suspend()

Suspend le calcul asynchrone représenté par ce futur. Il s'agit d'une méthode de commodité qui appelle simplement setSuspended(true).

Cette fonction a été introduite dans Qt 6.0.

Voir aussi resume().

[signal, since 6.0] void QFutureWatcher::suspended()

Ce signal est émis lorsque suspend() a pris effet, ce qui signifie qu'il n'y a plus de calculs en cours. Après avoir reçu ce signal, aucun autre signal de résultat prêt ou de rapport de progression n'est attendu.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setSuspended() et suspend().

[signal, since 6.0] void QFutureWatcher::suspending()

Ce signal est émis lorsque l'état du futur observé est défini comme suspendu.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setSuspended(), suspend(), et suspended().

[slot, since 6.0] void QFutureWatcher::toggleSuspended()

Bascule l'état de suspension du calcul asynchrone. En d'autres termes, si le calcul est en cours de suspension ou suspendu, l'appel à cette fonction le reprend ; si le calcul est en cours d'exécution, il est suspendu. Il s'agit d'une méthode de commodité pour appeler setSuspended( !(isSuspending() || isSuspended())).

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setSuspended(), suspend(), et resume().

void QFutureWatcher::waitForFinished()

Attend que le calcul asynchrone se termine (y compris les calculs cancel()ed), c'est-à-dire jusqu'à ce que isFinished() renvoie true.