classe ara::core::Future

Utilisation

La méthode get() récupère de manière synchrone le résultat de type T depuis un ara::core::Future [SWS_CORE_00326]. La fonction se comporte de manière identique à son pendant dans std::future ; si le calcul asynchrone est toujours en cours, l'appel bloque jusqu'à l'achèvement ou jusqu'à l'apparition d'une erreur [SWS_CORE_00336]. Par cet appel, l'objet perd son état, de sorte que le future devient immédiatement invalide (valid() == false) [SWS_CORE_00326]. Un appel non bloquant peut être sécurisé au préalable via is_ready() [SWS_CORE_00332].

Gestion des erreurs

Les échecs sont signalés par des exceptions C++ [SWS_CORE_00326] :

• Si une erreur a été consignée dans le Promise associé via SetError() ou SetResult(), une exception du type d'erreur correspondant est déclenchée [SWS_CORE_00326].
• Si l'état partagé est abandonné prématurément par l'opération asynchrone, cela entraîne l'erreur kBrokenPromise conformément à FutureErrc [SWS_CORE_00326], [SWS_CORE_00400].
• Si l'appel est effectué sur une instance invalide, une FutureException est levée avec le code d'erreur kNoState [SWS_CORE_00326].

Concurrence et restrictions

L'opération n'est ni thread-safe ni sûre vis-à-vis des exceptions (not exception safe) [SWS_CORE_00326]. Des accès simultanés au même future depuis plusieurs threads nécessitent une synchronisation externe. Si les exceptions sont désactivées dans la chaîne d'outils du compilateur, get() ne participe pas à la résolution de surcharge [SWS_CORE_00326] ; pour ce cas, il existe l'alternative sans exceptions GetResult() [SWS_CORE_00336]. Pour les instances sans valeur de retour, la spécialisation Future<void, E>::get() est disponible [SWS_CORE_06226].

La fonction membre then sert à l'enchaînement de calculs asynchrones et enregistre un objet appelable func comme continuation sur une instance de ara::core::Future [SWS_CORE_00331]. Après le retour de l'appel, la Future d'origine est invalide (valid() == false). La cible d'appel reçoit le résultat de l'instance obtenu via GetResult(), transmis en tant que rvalue de type Result<T, E> [SWS_CORE_00331].

Le type de retour de then dépend du type de retour U de la continuation [SWS_CORE_00331] :

• Si func renvoie une Future<T2, E2>, un désencapsulage implicite de future vers Future<T2, E2> a lieu [SWS_CORE_00331].
• Si func renvoie un Result<T2, E2>, un désencapsulage implicite de Result vers Future<T2, E2> a lieu [SWS_CORE_00331].
• Dans tous les autres cas, le type de retour est Future<U, E> [SWS_CORE_00331].

L'exécution de func peut avoir lieu de manière synchrone dans le contexte de l'appel de then, dans le contexte de Promise::set_result ou Promise::SetError, ou dans un autre contexte [SWS_CORE_00331]. L'appel est spécifié comme non thread-safe. La continuation est enregistrée dans la Future renvoyée ; après le retour de son destructeur, plus aucune continuation ne doit être exécutée, tandis qu'une exécution déjà en cours se poursuit jusqu'à la fin [SWS_CORE_00331].

Il n'existe pas de codes d'erreur standardisés [SWS_CORE_00331]. Les erreurs doivent être interceptées par les utilisateurs et transmises comme code d'erreur dans un Result renvoyé ou une Future renvoyée, car les exceptions ne doivent pas quitter la continuation. Un appel sur une Future invalide déclenche FutureInvalidViolation ; si la continuation lève une exception, cela entraîne FutureContinuationHasThrownViolation [SWS_CORE_00331].

Pour des exécutions dans un contexte d'exécution explicite, la surcharge avec executor est disponible [SWS_CORE_00337], tandis que pour les opérations sans valeur de retour, la spécialisation void s'applique [SWS_CORE_06231].

Utilisation et sémantique

La méthode then enregistre une continuation (func), qui est exécutée de manière asynchrone dans le contexte du executor transmis, dès que le résultat de l'instance Future actuelle est disponible [SWS_CORE_00337]. L'entité appelable reçoit le résultat de l'instance sous forme d'expression rvalue de type Result<T,E> [SWS_CORE_00337]. Le type de retour dépend du type de retour U de la continuation :

• Si la continuation retourne un Future<T2,E2>, un déballage implicite en Future<T2,E2> a lieu [SWS_CORE_00337].
• Si la continuation retourne un Result<T2,E2>, celui-ci est également résolu implicitement en Future<T2,E2> [SWS_CORE_00337].
• Dans tous les autres cas, l'appel fournit Future<U,E> [SWS_CORE_00337].

Concurrence et cycle de vie

Immédiatement après le retour de l'appel de méthode, l'instance Future d'origine est invalide (valid() == false) [SWS_CORE_00337]. La fonction est déclarée comme non thread-safe [SWS_CORE_00337]. Les continuations enregistrées sont gérées dans le Future nouvellement retourné. À l'issue de son destructeur, plus aucune continuation ne doit être démarrée ; une exécution déjà en cours est menée à son terme, de sorte que le destructeur peut bloquer [SWS_CORE_00337].

Traitement des erreurs et interaction

Aucun code d'erreur standardisé n'est défini [SWS_CORE_00337]. Un appel sur une instance invalide déclenche la violation FutureInvalidViolation [SWS_CORE_00337]. Si la continuation lève une exception, cela résulte en une FutureContinuationHasThrownViolation ; les exceptions doivent donc être interceptées et transmises en tant qu'erreur via ara::core::Result ou ara::core::Future [SWS_CORE_00337]. Par rapport à la surcharge sans contexte d'exécution [SWS_CORE_00331], cette variante impose l'exécution sur l'exécuteur transmis ; pour les types de résultat void, la spécialisation analogue [SWS_CORE_06237] existe.

La fonction d’interrogation synchrone valid() vérifie sans paramètre si une instance de ara::core::Future possède un état partagé (Shared State) et est donc utilisable [SWS_CORE_00327]. Elle renvoie true si l’objet est prêt à l’emploi, et false si aucun état partagé n’est présent [SWS_CORE_00327]. Le comportement correspond à la fonction standard std::future::valid et s’applique de la même manière à la spécialisation de modèle ara::core::Future<void, E> [SWS_CORE_06227].

La fonction est déclarée comme noexcept, est considérée comme sûre vis-à-vis des exceptions (exception safe) et est expressément spécifiée comme sûre vis-à-vis des threads (thread-safe) [SWS_CORE_00327]. Elle ne déclenche elle-même aucun code d’erreur ni exception et peut donc être utilisée en toute sécurité pour vérifier l’état [SWS_CORE_00327].

Dans l’interaction avec d’autres méthodes de Future, le contrôle de validité est déterminant, car les opérations appelantes telles que wait() [SWS_CORE_00328] ou is_ready() [SWS_CORE_00332] déclenchent une FutureInvalidViolation en cas d’état non valide (valid() == false). Un Future auparavant valide devient automatiquement non valide dès que son résultat est consommé via get() [SWS_CORE_00326] ou GetResult() [SWS_CORE_00336] ou qu’un traitement ultérieur a été enregistré via then() [SWS_CORE_00331], [SWS_CORE_00337].

La fonction membre wait de la classe ara::core::Future bloque le thread appelant de manière synchrone jusqu'à ce qu'une valeur de résultat ou une erreur issue de l'opération asynchrone soit disponible [SWS_CORE_00328]. La fonction ne prend aucun paramètre, ne renvoie aucune valeur et se comporte, selon la spécification, de manière analogue à la fonction correspondante de std::future [SWS_CORE_00328]. Le même comportement s'applique à la spécialisation de modèle ara::core::Future<void, E> [SWS_CORE_06228].

Concernant le traitement des erreurs et la concurrence, les prescriptions suivantes sont définies :

• Condition d'erreur : Si l'objet future n'est pas valide (valid == FALSE), il s'agit d'une FutureInvalidViolation [SWS_CORE_00328], [SWS_CORE_06228]. Néanmoins, la fonction est déclarée comme noexcept et classée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CORE_00328].
• Sécurité des threads : L'appel est explicitement classé comme not thread-safe [SWS_CORE_00328]. Un accès concurrentiel au même objet future sans synchronisation externe n'est pas autorisé.

En interaction avec des interfaces apparentées, il est recommandé de procéder avant l'appel à une vérification au moyen de is_ready [SWS_CORE_00332], [SWS_CORE_06232] : si celle-ci renvoie true, l'appel de wait ne bloquera à coup sûr plus. Si, au lieu d'une attente illimitée, un blocage limité dans le temps est requis, wait_for avec une durée relative [SWS_CORE_00329], [SWS_CORE_06229] ainsi que wait_until avec un instant absolu [SWS_CORE_00330], [SWS_CORE_06230] sont disponibles comme alternatives.

Utilisation

La fonction membre wait_for de la classe ara::core::Future bloque le thread appelant pendant au maximum la durée transmise timeoutDuration ou jusqu'à ce qu'une valeur de résultat ou une erreur soit disponible dans l'état partagé [SWS_CORE_00329]. Son comportement correspond à la fonction correspondante de std::future [SWS_CORE_00329]. Comme valeur de retour, elle fournit un FutureStatus [SWS_CORE_00329], qui indique si l'état partagé est disponible (kReady) ou si le temps d'attente spécifié est écoulé (kTimeout) [SWS_CORE_00361].

Gestion des erreurs et conditions limites

La fonction est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CORE_00329]. Si l'objet Future est invalide (valid == FALSE), il s'agit d'une violation sous la forme de FutureInvalidViolation [SWS_CORE_00329]. Interprétation : étant donné qu'aucune exception C++ ne doit être levée, une telle violation devrait être traitée du côté de la plateforme comme une erreur fatale à l'exécution. Question Q-2f22a07f6e143856 (ouverte)

Concurrence et interaction

L'opération est classée comme not thread-safe [SWS_CORE_00329] ; les accès simultanés à la même instance nécessitent donc une synchronisation externe. La sémantique et la signature s'appliquent à l'identique pour la spécialisation de modèle ara::core::Future<void, E> [SWS_CORE_06229]. Contrairement à std::future_status, il n'existe dans le type énuméré FutureStatus aucune entrée pour deferred [SWS_CORE_00361].

La fonction membre wait_until bloque le thread appelant jusqu'à ce que l'instant absolu spécifié deadline soit atteint ou que le ara::core::Future fournisse un résultat ou une erreur [SWS_CORE_00330]. Le comportement s'aligne sur la fonction correspondante de std::future [SWS_CORE_00330].

Comme valeur de retour, la fonction fournit un FutureStatus [SWS_CORE_00330]. Ce type énuméré signale via l'état kReady que l'état partagé est prêt (valeur ou erreur disponible), ou via kTimeout que le délai est écoulé sans résultat [SWS_CORE_00361]. Un état analogue à std::future_status::deferred n'existe pas dans FutureStatus [SWS_CORE_00361].

En ce qui concerne le traitement des erreurs et la sécurité vis-à-vis des exceptions, la fonction est spécifiée comme sûre vis-à-vis des exceptions (exception safe) et noexcept [SWS_CORE_00330]. Si la fonction est toutefois appelée sur une instance invalide (valid == FALSE), il s'agit d'une violation sous la forme de FutureInvalidViolation [SWS_CORE_00330].

En ce qui concerne la concurrence, wait_until est classée comme non sûre au niveau des threads (not thread-safe) [SWS_CORE_00330]. Les accès parallèles au même objet ara::core::Future doivent donc être synchronisés de manière externe. La même sémantique et la même signature s'appliquent à la spécialisation ara::core::Future<void, E> [SWS_CORE_06230].