classe <SI-Namespace>::skeleton::fields::<Field>

Utilisation

La méthode RegisterGetHandler est appelée côté serveur sur l'objet de champ d'un skeleton ([SWS_CM_00114]). Elle n'existe dans le code généré que si un getter a été configuré pour le champ concerné dans la description d'interface (Field.hasGetter == TRUE) (EXP ARAComAPI §5.4.8.1 « Registering Getters »). Un callback handler de type std::function<ara::core::Future<FieldType>()> est transmis, lequel est appelé par l'implémentation de liaison lors d'une requête Get() entrante d'un proxy.

L'enregistrement d'un tel gestionnaire est totalement facultatif (EXP ARAComAPI §5.4.8.1 « Registering Getters »). Habituellement, l'implémentation du service ne requiert pas de gestionnaire de getter, car le Communication Management met en cache la dernière valeur définie via Update() et répond de manière autonome aux requêtes de proxy. Un gestionnaire s'avère particulièrement pertinent lorsque la détermination de la valeur du champ nécessite beaucoup de temps ou de ressources de calcul et ne doit donc être effectuée de manière asynchrone via le modèle Promise/Future qu'en cas de besoin réel.

Gestion des erreurs et conditions limites

La fonction ne possède aucune valeur de retour, est déclarée comme noexcept et est sûre vis-à-vis des exceptions (exception safe) ([SWS_CM_00114]). Si le callable transmis n'existe pas ou vaut null, l'erreur InvalidHandlerViolation est présente ([SWS_CM_00114]).

Interaction

Contrairement à RegisterSetHandler, dont l'appel est obligatoire en présence d'un setter (EXP ARAComAPI §5.4.8.2 « Registering Setters »), RegisterGetHandler demeure purement facultatif. Si le gestionnaire doit être traité de manière asynchrone dans un contexte d'exécution spécifique, la fonction modèle surchargée avec ExecutorT est disponible en complément ([SWS_CM_11360]).

Utilisation

La méthode RegisterGetHandler dans l'espace de noms <SI-Namespace>::skeleton::fields::<Field> enregistre un rappel côté application (handler) qui est appelé par la liaison de communication lors d'un appel Get() entrant provenant d'un proxy ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 « Registering Getters »). Contrairement à la surcharge de base sans paramètre [SWS_CM_00114], la méthode accepte un contexte d'exécution executor de type ExecutorT, dans lequel l'exécution du rappel s'effectue de manière asynchrone ([SWS_CM_11360]). L'exécuteur peut être le ara::core::Executor standardisé ou un type spécifique à l'utilisateur présentant la même interface ([SWS_CM_11360]).

Le gestionnaire enregistré renvoie un ara::core::Future<FieldType>, ce qui permet de découpler le calcul de la valeur du champ par l'intermédiaire du modèle Promise/Future ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 « Registering Getters »). L'enregistrement est entièrement facultatif : si aucun gestionnaire n'est enregistré, le Communication Management répond aux requêtes de manière autonome avec la dernière valeur définie via Update() (EXP ARAComAPI §5.4.8.1 « Registering Getters »). Un gestionnaire de lecture (getter) est principalement adapté à la détermination à la demande de valeurs de champ complexes ou chronophages (EXP ARAComAPI §5.4.8.1 « Registering Getters »).

Restrictions et traitement des erreurs

La méthode existe dans le squelette exclusivement si un getter a été configuré pour le champ dans l'IDL (Field.hasGetter == TRUE, [SWS_CM_00114], EXP ARAComAPI §5.4.8.1 « Registering Getters »). RegisterGetHandler est déclaré comme noexcept ; toutefois, si un objet appelable non valide ou vide est transmis, il s'agit d'une InvalidHandlerViolation ([SWS_CM_11360]). Interprétation : l'exécuteur transmis devrait devoir rester valide pendant toute la durée d'utilisation du gestionnaire, étant donné que les requêtes entrantes sont acheminées de manière asynchrone dans son contexte. Question Q-c58eb22b06a8c27c (ouverte)

Utilisation

La méthode RegisterSetHandler sert, côté serveur (squelette), à enregistrer une fonction de rappel appelée lors de la réception d'une requête Set() émise par un client pour un champ [SWS_CM_00116]. La méthode existe exclusivement lorsque le champ proposé est configuré avec prise en charge d'un setter (Field.hasSetter == TRUE) [SWS_CM_00116]. Contrairement à l'enregistrement du getter, l'appel de RegisterSetHandler est obligatoire car l'implémentation du serveur doit valider au préalable les nouvelles valeurs de champ ou les valeurs mises à jour provenant de clients anonymes EXP ARAComAPI §5.4.8.2 « Registering Setters ».

Le gestionnaire enregistré reçoit la nouvelle valeur en argument et renvoie un ara::core::Future<FieldType> contenant la valeur effective, le cas échéant corrigée [SWS_CM_00116], EXP ARAComAPI §5.4.8.2 « Registering Setters ». Cette valeur effective est implicitement reprise par la gestion de la communication et publiée auprès des clients ; un appel explicite de Update() au sein du gestionnaire est donc superflu EXP ARAComAPI §5.4.8.2 « Registering Setters ».

Gestion des erreurs et conditions limites

La fonction est définie comme noexcept et est sûre vis-à-vis des exceptions [SWS_CM_00116]. Si un callable inexistant ou invalide (null) est transmis, il s'agit d'une violation de spécification sous la forme d'une InvalidHandlerViolation [SWS_CM_00116]. Interprétation : l'enregistrement devrait devoir s'effectuer avant la mise à disposition du service via OfferService() afin de pouvoir accepter les requêtes clientes entrantes dès le début. Question Q-d45be0a899ddb6dd (ouverte)

Interaction

Outre la méthode de base, il existe une surcharge de modèle [SWS_CM_11362] permettant de lier l'exécution du gestionnaire à un contexte d'exécution spécifique (ExecutorT selon [SWS_CM_11360]) EXP ARAComAPI.

La fonction template RegisterSetHandler enregistre, au niveau serveur ou skeleton d'un champ, une fonction de callback qui est appelée dès qu'un client transmet une requête Set() ([SWS_CM_11362], [SWS_CM_00116]). L'interface n'existe que si le champ de service configuré prévoit la prise en charge d'un setter (Field.hasSetter == TRUE) ([SWS_CM_00116]). À la différence de l'enregistrement de Get, l'enregistrement d'un gestionnaire Set est obligatoire, car l'implémentation serveur doit systématiquement valider les nouvelles valeurs de champ provenant de clients anonymes (EXP ARAComAPI §5.4.8.2 « Registering Setters »).

Par rapport à l'enregistrement standard selon [SWS_CM_00116], cette surcharge accepte en outre un contexte d'exécution executor de type ExecutorT&& ([SWS_CM_11362], [SWS_CM_11360]). Interprétation : le executor devrait contrôler dans quel contexte de thread ou d'ordonnanceur de tâches le callback est exécuté. Question Q-6dec4c0005c388dd (ouverte) Le gestionnaire transmis possède la signature std::function<ara::core::Future<FieldType>(<SFieldDerivedType> value)> ; il reçoit la valeur définie par le client et renvoie de manière asynchrone via ara::core::Future la valeur effective – le cas échéant validée ou corrigée ([SWS_CM_11362], EXP ARAComAPI §5.4.8.2 « Registering Setters »).

Communication Management reprend implicitement la valeur effective renvoyée par le gestionnaire comme si l'application serveur avait elle-même appelé Update() ; un appel manuel de Update() au sein du gestionnaire est par conséquent superflu (EXP ARAComAPI §5.4.8.2 « Registering Setters », EXP ARAComAPI §4.6 « Data Type Abstractions »).

Traitement des erreurs et concurrence :

• Sécurité vis-à-vis des exceptions : La fonction est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) ([SWS_CM_11362]).
• Violations : Si le callable setHandler transmis n'existe pas ou est nullptr, la violation InvalidHandlerViolation est présente ([SWS_CM_11362]).
• Contexte : La méthode garantit que l'exécution du gestionnaire a lieu dans le contexte fourni du executor ([SWS_CM_11362]).

La fonction SetTransportFaultConditionHandler sert à enregistrer un gestionnaire d'erreurs de type ara::com::e2e::TransportFaultConditionHandler pour les requêtes Get et Set d'un champ au niveau du skeleton dans l'espace de noms <SI-Namespace>::skeleton::fields::<Field> [SWS_CM_00096]. L'appel est exécuté de manière synchrone, ne possède aucune valeur de retour (void) et garantit la sécurité vis-à-vis des exceptions grâce à sa spécification en tant que noexcept [SWS_CM_00096]. Pour les scénarios dans lesquels l'exécution du gestionnaire doit être déléguée à un contexte d'exécution explicite, la surcharge de modèle avec un objet exécuteur ExecutorT&& executor est disponible [SWS_CM_00097].

La violation InvalidHandlerViolation est définie comme condition d'erreur ; elle se produit lorsque le callable transmis handler n'existe pas ou est nul [SWS_CM_00096]. Tandis que, côté client, les erreurs lors des requêtes de méthode et de champ sont signalées via ComErrc::kCommunicationFailure dans les instances ara::core::Future respectives [SWS_CM_00090], cette fonction permet à l'instance serveur de réceptionner les erreurs de transport lors d'appels Get et Set entrants [SWS_CM_00096].

Le concept correspond aux mécanismes d'enregistrement équivalents pour toutes les méthodes d'une instance de service de skeleton [SWS_CM_00093] ainsi qu'aux gestionnaires côté proxy pour les événements [SWS_CM_00099], les déclencheurs [SWS_CM_00106] et les notificateurs de champ [SWS_CM_00109]. Interprétation : l'enregistrement du gestionnaire devrait judicieusement avoir lieu pendant la phase d'initialisation avant la mise à disposition du skeleton, afin de pouvoir intercepter de manière transparente les erreurs lors des accès initiaux aux champs. Question Q-627229896b666532 (ouverte)

La fonction SetTransportFaultConditionHandler dans l’espace de noms <SI-Namespace>::skeleton::fields::<Field> enregistre un gestionnaire d’erreurs pour les perturbations de transport lors des requêtes Get et Set d’un champ au niveau du Skeleton [SWS_CM_00097]. Elle est incluse via l’en-tête <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h [SWS_CM_00097].

Utilisation et paramètres

L’appel s’effectue de manière synchrone et ne possède aucune valeur de retour (void) [SWS_CM_00097]. Sont transmis en paramètres le rappel d’erreur appelable handler de type ara::com::e2e::TransportFaultConditionHandler ainsi qu’une référence de transfert executor de type générique ExecutorT&& [SWS_CM_00097]. Le paramètre executor désigne l’objet d’exécution dans le contexte duquel d’éventuels calculs asynchrones sont exécutés [SWS_CM_00097].

Gestion des erreurs et concurrence

La méthode est déclarée comme noexcept et garantit une sécurité totale vis-à-vis des exceptions (exception safe) [SWS_CM_00097]. Si le callable handler transmis n’existe pas ou vaut null, un InvalidHandlerViolation est déclenché [SWS_CM_00097]. Interpretation : l’objet executor transmis permet vraisemblablement de déterminer dans quel contexte de thread ou de tâche la notification asynchrone est traitée lors d’erreurs de transport. Question Q-4101faaa8d6a3130 (ouverte)

Interaction

La méthode enrichit l’enregistrement standard [SWS_CM_00096] d’un contexte d’exécution dédié pour les champs du Skeleton [SWS_CM_00097]. Des surcharges correspondantes avec exécuteur existent également pour les méthodes du Skeleton ([SWS_CM_00094]) ainsi que, du côté client ou Proxy, pour les événements ([SWS_CM_00100]) et les notificateurs de champs ([SWS_CM_00110]).

La fonction UnsetTransportFaultConditionHandler sert, côté squelette d'une interface de service, à supprimer un ara::com::e2e::TransportFaultConditionHandler précédemment enregistré pour les requêtes Get et Set d'un champ ([SWS_CM_00098]). Elle est définie dans l'espace de noms <SI-Namespace>::skeleton::fields::<Field> et intégrée via l'en-tête <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h (AUTOSAR_AP_SWS_CommunicationManagement §8.4.3.2.1.3 « UnsetTransportFaultConditionHandler »). L'appel s'effectue de manière synchrone, n'accepte aucun paramètre d'entrée et ne renvoie aucune valeur de retour (void).

Cette suppression désactive le callback spécifique à l'application pour les états d'erreur de transport lors de requêtes sur les champs (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 « End-to-end communication protection for SOMEIP »). L'interface est déclarée comme noexcept et garantit la sécurité vis-à-vis des exceptions (exception safe) ([SWS_CM_00098]). Aucun code d'erreur ni message d'erreur spécifique via DET ou DEM n'est spécifié ; l'opération est conçue pour se terminer sans erreur.

Concernant la concurrence et la réentrance, la spécification ne contient pas d'exigences particulières. En conséquence, la désinscription devrait de préférence avoir lieu pendant les phases de désinitialisation ou en dehors des traitements concurrents de Get/Set, afin d'éviter toute incohérence lors d'opérations de communication en cours. Question Q-06bc8d90f1891904 (ouverte)

L'opération fait partie de la sécurisation de la communication de bout en bout pour les instances de service (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 « End-to-end communication protection for SOMEIP »). Elle constitue le pendant associé aux champs de [SWS_CM_00095], qui désinscrit le gestionnaire pour toutes les méthodes d'un squelette. Côté proxy, elle correspond aux désinscriptions équivalentes pour les événements ([SWS_CM_00105]), les déclencheurs ([SWS_CM_00108]) et les notificateurs de champ ([SWS_CM_00126]).

La méthode Update() est appelée côté serveur dans le scope <SI-Namespace>::skeleton::fields::<Field> afin de mettre à jour la valeur interne d'un champ et d'initier la transmission des nouvelles données aux clients abonnés ([SWS_CM_00119], AUTOSAR_AP_EXP_ARAComAPI §4.6 « Data Type Abstractions »). Une notification est envoyée aux abonnés si hasNotifier == TRUE est configuré pour le champ ([SWS_CM_00119], [SWS_CM_00120], [SWS_CM_00162]). Le paramètre value est transmis par référence ; l'implémentation de liaison crée pendant l'appel une copie, typiquement sérialisée, de sorte que les données d'application puissent être modifiées ou libérées côté appelant après le retour de l'appel (AUTOSAR_EXP_ARAComAPI « UpdateRate Class »).

La fonction est définie comme noexcept ainsi que exception safe et renvoie de manière synchrone un ara::core::Result<void> ([SWS_CM_00119]). En cas d'erreur, le résultat contient un code d'erreur issu de ara::com::ComErrc ([SWS_CM_00119], [SWS_CM_10432]). Concrètement, ComErrc::kMinimumSendIntervalViolationError est renvoyé avec une sémantique de rollback si des demandes d'envoi surviennent plus rapidement que ce qui est imposé par l'intervalle d'envoi minimal configuré ServiceInterfaceDeploymentElement.minimumSendInterval ([SWS_CM_00119]).

Dans le cycle de vie du service, un appel initial de Update() est requis avant de proposer le service : si OfferService() est appelé avant que la valeur du champ n'ait été initialisée, la mise à disposition échoue avec ComErrc::kFieldValueNotInitialized ([SWS_CM_00101], [SWS_CM_00128]). En l'absence de garantie explicite de réentrance dans le standard, les appels simultanés sur la même instance de champ devraient probablement être synchronisés côté application. Question Q-67b174ef05867989 (ouverte)