classe ara::core::Promise

La classe ara::core::Promise fait office de point de terminaison d'écriture asynchrone pour transférer des valeurs, des erreurs ou des résultats entre threads dans un état partagé [SWS_CORE_00341]. L'accès en lecture s'effectue via un Future récupérable exactement une seule fois, qui est libéré lors de la mise à disposition du résultat [SWS_CORE_00344]. Comme la classe n'est pas copiable, l'état reste strictement en possession exclusive via la sémantique de déplacement, une affectation multiple du résultat ou une récupération multiple du future conduisant à des violations standardisées.

plus ›

Contexte

La classe ara::core::Promise représente la déclinaison spécifique à l'Adaptive Platform du concept std::promise issu du standard C++. Elle est définie dans l'en-tête ara/core/future.h en tant que template Promise<T, E = ErrorCode> et sert de point de terminaison d'écriture asynchrone d'un état partagé (shared state). Par ce canal, un producteur transmet entre threads soit une valeur de sortie calculée, soit une erreur, soit un ara::core::Result agrégé. Le côté récepteur correspondant accède au résultat via un ara::core::Future associé, qui est récupéré via la méthode d'instance get_future [SWS_CORE_00344]. À la différence du mécanisme standard C++, reposant principalement sur les exceptions, AUTOSAR Adaptive ancre le paradigme typé par les erreurs : si le type d'erreur E choisi est différent de ara::core::ErrorCode, la spécification force une erreur de compilation.

Cycle de vie

Une instance est régulièrement créée via le constructeur par défaut sans paramètre, qui se comporte comme le constructeur correspondant de std::promise, est sûr vis-à-vis des threads et établit un nouvel état partagé [SWS_CORE_00341]. Afin de garantir des rapports de possession univoques sur cet état, les opérations de copie sont totalement proscrites : le constructeur de copie [SWS_CORE_00350] ainsi que l'opérateur d'affectation par copie [SWS_CORE_00351] sont déclarés comme supprimés (delete).

La classe prend toutefois en charge la sémantique de déplacement (move). Le constructeur de déplacement prend en charge l'état partagé de l'instance source [SWS_CORE_00342]. Lors d'une affectation par déplacement, l'instance cible abandonne son état partagé précédent et prend en charge l'état de l'objet transmis de manière analogue à une opération d'échange [SWS_CORE_00343]. De plus, la méthode swap permet d'échanger l'état interne avec une autre instance [SWS_CORE_00352]. Lors de la destruction via le destructeur, un état partagé encore détenu est libéré ou quitté [SWS_CORE_00349]. Alors que le constructeur par défaut est conçu pour être sûr vis-à-vis des threads [SWS_CORE_00341], les opérations de déplacement, les affectations, le swap et la destruction ne sont pas sûrs vis-à-vis des threads ([SWS_CORE_00342], [SWS_CORE_00343], [SWS_CORE_00352], [SWS_CORE_00349]).

Diagramme d'états : cycle de vie et transitions d'état de l'état partagé dans une instance de Promise. Sources : [SWS_CORE_00341], [SWS_CORE_00342], [SWS_CORE_00343], [SWS_CORE_00344], [SWS_CORE_00345], [SWS_CORE_00349], [SWS_CORE_00353], [SWS_CORE_00355]

Parcours d'utilisation

Un déroulement typique de mise à disposition comprend les étapes suivantes :

1. Création : le producteur instancie un ara::core::Promise<T, E> [SWS_CORE_00341].
2. Récupérer le future : avant le démarrage du traitement asynchrone, le producteur appelle get_future() [SWS_CORE_00344]. Comme un seul Future associé est autorisé par promise, cet appel ne doit être effectué qu'exactement une fois. Le Future renvoyé est transmis au thread consommateur.
3. Définir le résultat : à l'issue de l'opération asynchrone, le producteur transfère le résultat dans l'état partagé et fait passer celui-ci à l'état ready. Des surcharges sûres vis-à-vis des threads sont disponibles pour les opérations de copie et de déplacement :
   • Valeur réussie : appel de set_value ([SWS_CORE_00345], [SWS_CORE_00346]).
   • État d'erreur : appel de SetError ([SWS_CORE_00353], [SWS_CORE_00354]).
   • Résultat combiné : appel de SetResult ([SWS_CORE_00355], [SWS_CORE_00356]).

Diagramme de séquence : séquence d'appels et de synchronisation entre producteur, promise, shared state et consommateur. Sources : [SWS_CORE_00341], [SWS_CORE_00344], [SWS_CORE_00345], [SWS_CORE_00353], [SWS_CORE_00355]

Scénarios d'erreur

La spécification définit des préconditions strictes pour toutes les interactions avec l'état partagé, dont le non-respect conduit à des violations standardisées (Violations) :

• Récupération multiple du future : si get_future() est appelé plus d'une fois pour le même état partagé, la violation IsoStdFutureErrcFutureAlreadyRetrievedViolation survient [SWS_CORE_00344].
• Shared state manquant : si l'instance appelée ne possède pas d'état partagé — par exemple après l'exécution d'une opération de déplacement —, get_future() conduit à IsoStdFutureErrcNoStateViolation [SWS_CORE_00344]. Dans ce cas, les méthodes set_value, SetError et SetResult déclenchent la violation PromiseNoSharedStateToSetViolation ([SWS_CORE_00345], [SWS_CORE_00353], [SWS_CORE_00355]).
• État déjà satisfait : si l'état partagé a déjà été pourvu d'une valeur, d'une erreur ou d'un résultat, chaque nouvel appel de set_value ([SWS_CORE_00345], [SWS_CORE_00346]), SetError ([SWS_CORE_00353], [SWS_CORE_00354]) ou SetResult ([SWS_CORE_00355], [SWS_CORE_00356]) conduit à la violation IsoStdFutureErrcPromiseAlreadySatisfiedViolation.
• Sécurité vis-à-vis des exceptions : les méthodes set_value, SetError et SetResult sont sécurisées vis-à-vis des exceptions sous condition (conditionally exception safe). Elles ne lèvent aucune exception pourvu que les constructeurs des types T et E soient déclarés comme nothrow ([SWS_CORE_00345], [SWS_CORE_00353], [SWS_CORE_00355]).

Interprétation : l'abandon de l'état partagé lors de la destruction de l'instance sans affectation préalable de valeur ([SWS_CORE_00349]) devrait, de manière analogue au comportement standard C++ de std::promise, conduire un Future associé à enregistrer un événement d'erreur correspondant lors d'une tentative de lecture. Question Q-fd013bb17a591af9 (ouverte)