classe ara::shwa::Event

La classe ara::shwa::Event sert à la synchronisation sur l'achèvement de tâches d'accélérateur matériel dans le module shwa [AP_SWS_SHWA_00604]. Après une création par fabrique thread-safe via Create() [AP_SWS_SHWA_00602], l'attente s'effectue de manière bloquante ou limitée dans le temps via des méthodes non thread-safe telles que Wait() ou WaitFor(). Si une erreur survient lors de l'exécution de la tâche, aucune sémantique de retour arrière (rollback) ne s'applique, raison pour laquelle les données utilisées sont considérées comme modifiées involontairement [AP_SWS_SHWA_00604].

plus ›

Contexte

La classe ara::shwa::Event fait office, au sein du module shwa, d'élément de synchronisation central pour les tâches d'accélérateur matériel. Sa responsabilité principale consiste à synchroniser sur l'achèvement de tâches associées ou dépendantes [AP_SWS_SHWA_00604]. Les partenaires d'interaction sont des threads et des composants applicatifs côté appelant qui coordonnent des opérations d'accélérateur asynchrones. Interprétation : l'interface synchronisant les achèvements de tâches, un objet Event individuel devrait encapsuler les signaux d'exécution et de synchronisation d'une exécution matérielle spécifique. Question Q-b4aa1debd356c45c (ouverte)

Cycle de vie

Les instances de ara::shwa::Event sont créées via la méthode de fabrique statique Create(), laquelle renvoie un ara::core::Result<Event> [AP_SWS_SHWA_00602]. Ce chemin de création est thread-safe et ne lève aucune exception (noexcept, exception safe) [AP_SWS_SHWA_00602]. Après la création, l'objet se trouve dans l'état de fonctionnement actif et permet l'interrogation des dépendances ainsi que des opérations de synchronisation.

En matière de concurrence, les composants applicatifs doivent tenir compte du fait que toutes les méthodes d'instance ainsi que les appels de synchronisation sont explicitement spécifiés comme non thread-safe (not thread-safe) [AP_SWS_SHWA_00603], [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605], [AP_SWS_SHWA_00606]. L'accès simultané de plusieurs threads à la même instance d'événement ou à des listes d'événements partagées nécessite par conséquent une synchronisation externe. La destruction de l'objet s'effectue via la durée de vie standard de C++ ; il n'existe aucune méthode explicite de fermeture ou de libération dans l'interface.

Parcours d'utilisation

Le déroulement standard pour la synchronisation se divise en la création de l'objet, l'inspection optionnelle des dépendances et l'attente effective de l'exécution :

1. Instanciation : l'appelant appelle Create() et vérifie le succès du ara::core::Result obtenu [AP_SWS_SHWA_00602].
2. Interroger les dépendances : GetWaitList() permet de lire une liste d'événements dépendants sous forme de ara::core::Vector<Event> [AP_SWS_SHWA_00603]. Vraisemblablement, GetWaitList() fait office d'inspection de tâches en amont dont l'événement dépend en interne pour son achèvement. Question Q-ed01dc595c23ce28 (ouverte)
3. Exécuter la synchronisation : trois variantes sont disponibles pour la synchronisation :
   • L'attente basée sur l'instance via Wait() bloque sur l'achèvement des tâches associées à l'événement [AP_SWS_SHWA_00604].
   • L'attente statique sur un groupe d'événements via Wait(eventList) synchronise sur une collection entière d'objets Event [AP_SWS_SHWA_00605].
   • L'attente statique avec temporisation via WaitFor(ms) limite l'attente à une durée définie en millisecondes [AP_SWS_SHWA_00606].

Diagramme de séquence : déroulement typique, de la création à la synchronisation en passant par l'interrogation des dépendances. Sources : [AP_SWS_SHWA_00602], [AP_SWS_SHWA_00603], [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00606]

Scénarios d'erreur

Toutes les méthodes sont déclarées avec noexcept et signalent les états d'erreur via le type de retour ara::core::Result. À cet égard, des codes d'erreur spécifiques apparaissent :

• ShwaErrorCode::kRuntime : erreur d'exécution générale pouvant survenir lors de la création [AP_SWS_SHWA_00602], de la lecture de la file d'attente [AP_SWS_SHWA_00603] ainsi que lors des appels de synchronisation [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605], [AP_SWS_SHWA_00606].
• ShwaErrorCode::kEventInvalidOperation : opération non valide sur l'événement, par exemple une opération d'attente non autorisée [AP_SWS_SHWA_00603], [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605], [AP_SWS_SHWA_00606].
• ShwaErrorCode::kTaskExecutionFailure : erreur survenue pendant l'exécution de la tâche associée [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605], [AP_SWS_SHWA_00606].
• ShwaErrorCode::kTimedOut : survient exclusivement avec WaitFor(ms) lorsque le délai d'attente spécifié est écoulé avant que la tâche n'ait pu être achevée [AP_SWS_SHWA_00606].

La sémantique de retour arrière (rollback) requiert une attention particulière : pour les opérations d'attente Wait() et Wait(eventList), no_rollback_semantics [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605] s'applique. Si une erreur survient lors de l'exécution de la tâche, les données utilisées par la tâche ayant échoué doivent être considérées comme modifiées de manière non intentionnelle [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605], [AP_SWS_SHWA_00606].

Cette classe représente un événement de synchronisation permettant d'attendre la complétion de tâches asynchrones exécutées par des accélérateurs matériels. Les instances sont obligatoirement créées par la méthode de fabrique Create() [AP_SWS_SHWA_00602]. L'application synchronise l'exécution au moyen de Wait() ou avec temporisation via WaitFor() [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00606]. En cas d'échec de la tâche surveillée, aucune restauration d'état n'est effectuée et les données associées doivent être considérées comme altérées.

plus ›

Contexte

Au sein du module de gestion de l'accélération matérielle (SHWA), la classe ara::shwa::Event fournit un mécanisme d'abstraction et de synchronisation pour suivre l'avancement et l'achèvement de tâches asynchrones exécutées sur des unités de traitement spécialisées. Elle matérialise un événement de synchronisation permettant à une application cliente de coordonner son flux d'instructions avec le matériel sous-jacent. La classe propose des points d'accès statiques et d'instance afin de surveiller un événement isolé ou d'agréger des ensembles d'événements dépendants [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605].

Cycle de vie

L'instanciation d'un événement ne s'effectue pas au moyen d'un constructeur accessible publiquement, mais exclusivement via la méthode de fabrique statique ara::shwa::Event::Create() [AP_SWS_SHWA_00602]. Cette fonction garantit l'innocuité vis-à-vis des exceptions (exception safe) et s'avère sécurisée pour les accès concurrents (thread-safe). Elle encapsule le résultat dans un ara::core::Result<Event>, garantissant une sémantique de retour arrière (rollback semantics) en cas d'anomalie lors de l'initialisation logicielle ou matérielle [AP_SWS_SHWA_00602].

Une fois l'objet créé, les opérations d'interrogation et de synchronisation telles que GetWaitList(), Wait() et WaitFor() ne sont pas sécurisées pour les accès concurrents (not thread-safe) [AP_SWS_SHWA_00603], [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00606]. Il incombe donc à l'application utilisatrice de sérialiser les appels sur une même instance ou sur les collections partagées d'événements. Vraisemblablement, la destruction de l'instance libère les descripteurs sous-jacents alloués par la couche matérielle, sous réserve qu'aucune opération bloquante ne soit active.

Parcours d'utilisation

Le cas d'utilisation canonique débute par la génération d'un ou plusieurs événements via la fabrique statique [AP_SWS_SHWA_00602]. L'application peut ensuite inspecter les dépendances associées à l'instance courante en appelant GetWaitList(), qui renvoie un ara::core::Vector<Event> listant les événements prérequis [AP_SWS_SHWA_00603]. Pour bloquer le fil d'exécution jusqu'à la complétion des tâches associées, l'application invoque soit la méthode d'instance Wait(), soit la variante statique prenant une liste explicite d'événements Wait(eventList) [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00605]. Lorsqu'un temps d'attente maximal doit être garanti, la méthode statique WaitFor(ms) permet de borner la synchronisation à une durée donnée en millisecondes [AP_SWS_SHWA_00606].

Diagramme de séquence : Déroulement type de la synchronisation via des événements SHWA. Sources : [AP_SWS_SHWA_00602], [AP_SWS_SHWA_00603], [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00606].

Scénarios d'erreur

Toutes les fonctions membres signalent les défaillances fonctionnelles au moyen du type ara::core::Result au lieu de lever des exceptions C++ [AP_SWS_SHWA_00602]. Divers codes d'erreur issus de l'énumération ShwaErrorCode peuvent être retournés :

• ShwaErrorCode::kRuntime : Erreur générale d'exécution survenant au cours de l'initialisation ou de la synchronisation [AP_SWS_SHWA_00602], [AP_SWS_SHWA_00604].
• ShwaErrorCode::kEvent (InvalidOperation) : Déclenchée lors d'une manipulation illicite d'un événement, par exemple une attente invalide sur un événement corrompu ou incompatible [AP_SWS_SHWA_00603], [AP_SWS_SHWA_00605].
• ShwaErrorCode::kTask (ExecutionFailure) : Signale un échec franc pendant l'exécution de la tâche matérielle liée à l'événement [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00606].
• ShwaErrorCode::kTimedOut : Renvoyée spécifiquement par WaitFor() lorsque le délai alloué s'est écoulé avant l'achèvement de la tâche [AP_SWS_SHWA_00606].

Une règle essentielle concerne l'intégrité des données : en cas d'erreur de tâche ou d'exécution sur Wait() ou WaitFor(), aucune sémantique de retour arrière (no_rollback_semantics) n'est assurée [AP_SWS_SHWA_00604], [AP_SWS_SHWA_00606]. Les données manipulées par la tâche en échec doivent impérativement être considérées comme altérées de façon involontaire par l'application cliente.