classe <SI-Namespace>::skeleton:: events::<Event>

La méthode Allocate est appelée au niveau du skeleton pour un événement ([SWS_CM_90438] ; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 « Skeleton Class API’s ») afin d'allouer de la mémoire pour le transfert de données d'événement lorsque Communication Management (ara::com) est responsable de la gestion des données ([SWS_CM_90438]). Elle renvoie une instance de type ara::com::SampleAllocateePtr<SampleType> ([SWS_CM_90438]). Ce type de pointeur se comporte conceptuellement comme un std::unique_ptr<T>, de sorte qu'une seule partie est propriétaire du pointeur à tout instant (ARAComAPI §6 « Event Allocate/Send sample Binding implementer hint »).

Concernant le traitement des erreurs et la sécurité vis-à-vis des exceptions, Allocate est spécifié comme not exception safe ([SWS_CM_90438]). La spécification définit deux violations possibles (Violations) :

• SampleAllocationViolation : Les ressources mémoire disponibles sont insuffisantes pour allouer les données ([SWS_CM_90438]).
• AllocateUsageViolation : L'allocation a été effectuée de manière non autorisée via un allocateur personnalisé ([SWS_CM_90438]).

Le concept sous-jacent à Allocate vise principalement à prendre en charge les mécanismes de « zero-copy », en particulier lors d'un transport IPC basé sur la mémoire partagée, une synchronisation stricte entre lecteurs et rédacteurs étant alors requise (ARAComAPI §6 « Event Allocate/Send sample Binding implementer hint »). Les concepteurs d'implémentation doivent veiller à ce que les exigences de sérialisation puissent anéantir le « zero-copy » si les types de données ne sont pas configurés comme étant binaires-compatibles dans le déploiement ou si une logique de détection l'exclut (ARAComAPI §6 « Event Allocate/Send sample Binding implementer hint »).

En interaction avec l'envoi d'événements, le pointeur de mémoire obtenu via Allocate est transmis à Send(ara::com::SampleAllocateePtr<SampleType> data) ([SWS_CM_90437]). Après l'appel de Send, l'application de service ne doit plus accéder aux données dès que Communication Management transmet les données à toutes les applications abonnées ([SWS_CM_90437]).

La fonction [SWS_CM_00162] sert, côté fournisseur de service au sein de <SI-Namespace>::skeleton::events::<Event>, à transmettre des données d'événement à toutes les applications abonnées. Avec cette variante, la responsabilité de l'allocation des données incombe entièrement à l'application cliente. L'objet de données est transmis via le paramètre data, à la suite de quoi l'implémentation de liaison confectionne une copie interne pendant l'appel (ARAComAPI, Figure 6.17 « BrakeEvent Class »). Après le retour de l'appel de méthode synchrone, l'application peut immédiatement modifier ou libérer la zone de mémoire d'origine.

La méthode est déclarée avec noexcept et spécifiée comme sûre vis-à-vis des exceptions. Elle renvoie un ara::core::Result<void> qui contient void en cas de succès et signale des codes d'erreur issus de [SWS_CM_10432] en cas d'erreur ([SWS_CM_00162]) :

• ComErrc::kServiceNotOffered : survient lorsque l'instance de service n'a pas encore été mise à disposition via OfferService().
• ComErrc::kMinimumSendIntervalViolationError : survient lorsque la demande d'envoi a été émise plus rapidement que l'intervalle d'envoi minimal configuré (ServiceInterfaceDeploymentElement.minimumSendInterval).

Contrairement à l'alternative zero-copy [SWS_CM_90437], qui requiert des pointeurs de type ara::com::SampleAllocateePtr obtenus via Allocate(), cet appel n'exige aucune liaison de mémoire au framework. Le même comportement de transmission et les mêmes conditions d'erreur s'appliquent également à la méthode de mise à jour Update des champs, conformément à [SWS_CM_00119].

Utilisation et contexte d'appel

La méthode Send est appelée sur une instance d'événement dans le squelette de service (<SI-Namespace>::skeleton::events::<Event>) ([SWS_CM_90437]). Elle transmet des données d'événement dont la gestion de la mémoire relève du Communication Management. Le paramètre data de type ara::com::SampleAllocateePtr<SampleType> doit avoir été obtenu au préalable via Allocate() ([SWS_CM_90437]). Ce type de pointeur se comporte sémantiquement comme un std::unique_ptr, ce qui transfère la propriété des données à la couche de communication lors de l'appel (ARAComAPI §6.17 « BrakeEvent Class »). Après le transfert, tout accès ultérieur aux données est interdit à l'application émettrice ([SWS_CM_90437]).

Gestion des erreurs et conditions limites

La fonction est déclarée comme noexcept et renvoie un ara::core::Result<void> ([SWS_CM_90437]). Si l'envoi échoue, le résultat contient un code d'erreur issu de ara::com::ComErrc ([SWS_CM_10432]) :

• ComErrc::kServiceNotOffered : le service correspondant n'a pas encore été mis à disposition au préalable avec OfferService() ([SWS_CM_90437]).
• ComErrc::kMinimumSendIntervalViolationError : l'intervalle minimal d'envoi (minimumSendInterval) configuré pour l'élément de service n'est pas encore écoulé depuis la dernière transmission ([SWS_CM_90437]).

Les deux cas d'erreur possèdent une sémantique de retour arrière ([SWS_CM_90437]). Avant l'appel, le service doit donc impérativement avoir été proposé, et les appels d'envoi successifs doivent respecter l'intervalle minimal configuré.

Interaction et optimisation

Par rapport à la signature [SWS_CM_00162], dans laquelle des données gérées par l'application sont transmises et copiées par le Communication Management, cette variante vise une communication sans copie via mémoire partagée (ARAComAPI §6.18 « Event Allocate/Send sample »). Une synchronisation stricte entre rédacteurs et lecteurs est alors requise, tout en devant prendre en compte d'éventuelles exigences de sérialisation entre les partenaires de communication (ARAComAPI §6.18 « Event Allocate/Send sample »).

Utilisation

La fonction SetSubscriptionStateChangeHandler enregistre dans le scope du skeleton (skeleton::events) un gestionnaire de rappel pour surveiller l'état de souscription d'un événement [SWS_CM_12008]. Le paramètre handler doit être un objet appelable de type SubscriptionStateChangeHandler conformément à [SWS_CM_00311]. La méthode ne renvoie aucune valeur de retour et est spécifiée comme noexcept [SWS_CM_12008].

Le Communication Management appelle le gestionnaire enregistré dès que l'état de souscription de l'événement change [SWS_CM_12012]. Côté skeleton, cela se produit avec l'état kSubscribed dès que le nombre de souscriptions actives devient supérieur à zéro [SWS_CM_12013], ou avec kNotSubscribed lorsqu'il n'y a plus de souscriptions actives [SWS_CM_12014] SWS CommunicationManagement §7.5.4 « Query Service Event Subscription State on Skeleton side ».

Gestion des erreurs et concurrence

L'opération est classée comme exception safe [SWS_CM_12008]. Si le callable transmis est invalide ou nul, il s'agit d'une InvalidHandlerViolation [SWS_CM_12008]. Interprétation : Comme la fonction ne lève aucune exception et ne renvoie aucun code d'erreur, cette violation de spécification devrait être interceptée via des mécanismes d'exécution spécifiques à la plateforme. Question Q-a7b7b54f0d538b40 (ouverte)

Le gestionnaire peut être écrasé au moment de l'exécution [SWS_CM_12012]. Pour l'exécution dans un contexte dédié de thread ou de tâche, il existe la surcharge avec le paramètre de modèle executor [SWS_CM_12009]. Un enregistrement analogue pour les éléments déclencheurs du skeleton est défini par [SWS_CM_01110].

La fonction de modèle SetSubscriptionStateChangeHandler sert, au niveau du skeleton ([SWS_CM_12009]) dans l'espace de noms d'un événement, à enregistrer un rappel pour les changements d'état des abonnements entrants. Par rapport à la fonction de base sans exécuteur ([SWS_CM_12008]), elle accepte en plus un contexte d'exécution (executor) dans lequel le gestionnaire enregistré est exécuté ([SWS_CM_12009]). La fonction ne possède pas de valeur de retour, est déclarée comme noexcept et est considérée comme sûre face aux exceptions ([SWS_CM_12009]).

Concernant le comportement d'erreur, la transmission d'un appelable invalide ou de valeur nulle entraîne une InvalidHandlerViolation ([SWS_CM_12009]). Le gestionnaire enregistré peut à tout moment être écrasé lors de l'exécution de l'application par un nouvel appel ([SWS_CM_12012]).

Le Communication Management appelle le gestionnaire dès que l'état des abonnements pour l'événement respectif change (SWS CommunicationManagement §7.5.4 « Query Service Event Subscription State on Skeleton side », [SWS_CM_12012]) :

• L'appel s'effectue avec l'état kSubscribed lorsque le nombre d'abonnements actifs passe de zéro à plus de zéro ([SWS_CM_12013]).
• Si le nombre d'abonnés actifs redescend à zéro, le gestionnaire est notifié avec kNotSubscribed ([SWS_CM_12014]).

Interprétation : par la transmission de executor, l'exécution du gestionnaire devrait être liée de manière ciblée à des contextes de threads ou de dispatching propres à l'application ([SWS_CM_12009]), afin de séparer proprement la notification concurrente du code de skeleton des threads de communication internes. Question Q-b11f3bc97069f2ec (ouverte)

Au niveau squelette dans l'espace de noms ::skeleton::events::{<event-name>}, la fonction UnsetSubscriptionStateChangeHandler sert à désenregistrer un gestionnaire de changement d'état préalablement enregistré pour le ara::com::SubscriptionState d'un événement [SWS_CM_12010]. La fonction ne prend aucun paramètre d'entrée et ne renvoie aucune valeur de retour (void) [SWS_CM_12010]. L'inclusion s'effectue via l'en-tête #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010].

En ce qui concerne le comportement face aux exceptions, la méthode est déclarée avec noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_CM_12010]. Aucun code d'erreur spécifique n'est renvoyé ni aucune exception C++ levée [SWS_CM_12010]. Interprétation : d'éventuels états d'erreur internes lors du désenregistrement devraient être interceptés en interne par la gestion de la communication, étant donné que la signature ne prévoit aucun retour d'erreur. Question Q-7e986a15e552ca19 (ouverte)

En interaction avec des interfaces apparentées, il existe des fonctions analogues pour le désenregistrement de gestionnaires :

• Au niveau squelette, ::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler fournit le désenregistrement correspondant pour les déclencheurs [SWS_CM_01112].
• Au niveau proxy, il existe des méthodes équivalentes pour désenregistrer les gestionnaires de changement d'état pour les événements [SWS_CM_00334], les champs [SWS_CM_11609] ainsi que les déclencheurs [SWS_CM_01108] au sein de l'espace de noms proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 « Proxy Class API’s ».