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 des fonctions membres

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

Crée un nouvel objet `QFutureWatcher` avec l'parent` fournie. Tant qu'aucun `future` n'a été défini à l'aide de ` setFuture()` (), les fonctions ` isStarted()`, ` isCanceled()` et ` isFinished()` renvoient ` true`.

[virtual] QFutureWatcher::~QFutureWatcher()

Supprime l'QFutureWatcher.

[slot] void QFutureWatcher::cancel()

Annule le calcul asynchrone représenté par la fonction ` 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 restent accessibles sur une instance ` QFuture` annulée, mais aucun nouveau résultat ne sera disponible après l’appel de cette fonction. De plus, cette instance ` QFutureWatcher ` n’émettra plus les signaux de progression et de résultat une fois annulée. Cela inclut les signaux ` progressValueChanged()`, ` progressRangeChanged()`, ` progressTextChanged()`, ` resultReadyAt()` et ` resultsReadyAt()`.

Notez que tous les calculs asynchrones en cours d’exécution ne peuvent pas être annulés. Par exemple, l’objet ` QFuture ` renvoyé par `QtConcurrent::run()` ne peut pas être annulé ; en revanche, l’objet ` QFuture ` renvoyé par `QtConcurrent::mappedReduced()` peut l’être.

[signal] void QFutureWatcher::canceled()

Ce signal est émis si le contrat à terme surveillé est annulé.

[signal] void QFutureWatcher::finished()

Ce signal est émis lorsque le contrat à terme suivi arrive à échéance.

QFuture<T> QFutureWatcher::future() const

Renvoie le « future » surveillé.

Voir aussi setFuture().

bool QFutureWatcher::isCanceled() const

Renvoie ` true ` si le calcul asynchrone a été annulé à l’aide de la fonction ` cancel()`, ou si aucun `future` n’a été défini ; sinon, renvoie ` false`.

Notez 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 `future` 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 `future` 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 en vigueur, ce qui signifie qu’aucun résultat ni aucune mise à jour sur l’avancement ne sont attendus.

Cette fonction a été introduite dans Qt 6.0.

Voir également suspended(), setSuspended() et isSuspending().

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

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

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

Cette fonction a été introduite dans Qt 6.0.

Voir également setSuspended(), toggleSuspended() et isSuspended().

int QFutureWatcher::progressMaximum() const

Renvoie la valeur maximale de ` progressValue()`.

Voir également progressValue() et progressMinimum().

int QFutureWatcher::progressMinimum() const

Renvoie la valeur minimale de ` progressValue()`.

Voir également progressValue() et progressMaximum().

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

La plage de progression pour l'avenir surveillé a été modifiée et correspond désormais à minimum et maximum.

QString QFutureWatcher::progressText() const

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

Notez que tous les calculs ne fournissent pas une représentation textuelle de la progression ; par conséquent, cette fonction peut renvoyer une chaîne vide.

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

Ce signal est émis lorsque le contrat à terme surveillé communique des informations textuelles sur l'avancement, progressText.

int QFutureWatcher::progressValue() const

Renvoie la valeur de progression actuelle, comprise entre progressMinimum() et progressMaximum().

Voir également progressMinimum() et progressMaximum().

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

Ce signal est émis lorsque le « future » surveillé signale une avancée ; progressValue indique la progression actuelle. Afin d’éviter de surcharger la boucle d’événements de l’interface graphique, QFutureWatcher limite la fréquence d’émission du signal de progression. Cela signifie que les écouteurs connectés à ce slot risquent de ne pas recevoir tous les rapports de progression générés par le « future ». La dernière mise à jour de progression (lorsque 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 la fonction ` 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 pratique permettant d'appeler la fonction ` resultAt(0)`.

Voir également resultAt().

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

Renvoie le résultat de la requête index via la fonction future(). Si le résultat n'est pas immédiatement disponible, cette fonction se met en attente jusqu'à ce qu'il le soit.

Voir également result().

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

Ce signal est émis lorsque le « future » surveillé renvoie un résultat prêt à l'adresse index. Si le « future » renvoie plusieurs résultats, l'index indiquera de quel résultat il s'agit. Les résultats peuvent être renvoyés dans un ordre aléatoire. Pour obtenir le résultat, appelez resultAt(index) ;

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

Ce signal est émis lorsque le contrat à terme surveillé communique ses résultats. Les résultats sont répertoriés sur beginIndex à endIndex.

[slot] void QFutureWatcher::resume()

Reprend le calcul asynchrone représenté par la méthode ` future()`. Il s'agit d'une méthode de commodité qui se contente d'appeler ` setSuspended(false)`.

Voir également suspend().

[signal] void QFutureWatcher::resumed()

Ce signal est émis lorsque le contrat à terme surveillé reprend son cours.

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

Commence à surveiller l'future spécifiée.

Si future a déjà démarré, l’observateur émettra dans un premier temps des signaux qui informent ses abonnés de l’état actuel 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 celles-ci, resultsReadyAt() et resultReadyAt() peuvent être émises plusieurs fois afin de couvrir tous les résultats disponibles. progressValueChanged() et progressTextChanged() ne seront émises qu'une seule fois pour la dernière valeur de progression et le dernier texte disponibles.

Pour éviter toute condition de concurrence, il est important d’appeler cette fonction après avoir établi les connexions.

Voir également future().

void QFutureWatcher::setPendingResultsLimit(int limit)

La méthode `setPendingResultsLimit()` permet de contrôler la limitation du débit. Lorsque le nombre de signaux en attente provenant des méthodes ` resultReadyAt()` ou ` resultsReadyAt()` dépasse la valeur définie par ` limit`, le calcul représenté par le `future` sera automatiquement limité. Le calcul reprendra dès que le nombre de signaux en attente passera en dessous de la valeur définie par ` 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 cessera pas immédiatement d’émettre les signaux de progression et de résultat prêt lorsque le « future » est suspendu. Au moment de la suspension, il se peut que certains calculs soient encore en cours et ne puissent pas être interrompus. Les signaux relatifs à ces calculs continueront d’être émis.

Si suspend est à « false », cette fonction reprend le calcul asynchrone. Si le calcul n’était pas suspendu auparavant, cette fonction ne fait rien.

Notez que tous les calculs ne peuvent pas être suspendus. Par exemple, l’ QFuture renvoyée par QtConcurrent::run() ne peut pas être suspendue ; en revanche, l’ QFuture renvoyée par QtConcurrent::mappedReduced() peut l’être.

Cette fonction a été introduite dans Qt 6.0.

Voir également suspended(), suspend(), resume() et toggleSuspended().

[signal] void QFutureWatcher::started()

Ce signal est émis lorsque cette instance QFutureWatcher commence à surveiller l'ensemble « future » à l'aide de la méthode setFuture().

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

Suspend le calcul asynchrone représenté par ce « future ». Il s'agit d'une méthode pratique qui se contente d'appeler ` setSuspended(true)`.

Cette fonction a été introduite dans Qt 6.0.

Voir également ` resume()`.

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

Ce signal est émis lorsque la fonction ` suspend()` a pris effet, ce qui signifie qu'il n'y a plus de calculs en cours. Après la réception de ce signal, aucun autre signal indiquant que le résultat est prêt ou faisant état de la progression n'est attendu.

Cette fonction a été introduite dans Qt 6.0.

Voir également setSuspended() et suspend().

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

Ce signal est émis lorsque l'état du « future » surveillé passe à « suspendu ».

Cette fonction a été introduite dans Qt 6.0.

Voir également setSuspended(), suspend() et suspended().

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

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

Cette fonction a été introduite dans Qt 6.0.

Voir également setSuspended(), suspend() et resume().

void QFutureWatcher::waitForFinished()

Attend que le calcul asynchrone soit terminé (y compris les calculs effectués via ` cancel()`), c'est-à-dire jusqu'à ce que ` isFinished()` renvoie ` true`.