namespace ara::log

L'énumération ara::log::ClientState représente l'état de connexion actuel d'un client externe au backend DLT [SWS_LOG_00098]. Elle repose sur le type de données std::int8_t et est intégrée via le fichier d'en-tête #include "ara/log/common.h" ou l'en-tête de transmission #include "ara/log/log_fwd.h" [SWS_LOG_00098].

États et sémantique

L'énumération définit trois états de connexion discrets [SWS_LOG_00098] :

• kUnknown (-1) : le backend DLT n'est pas encore opérationnel ; l'état de connexion effectif ne peut pas être déterminé à ce moment [SWS_LOG_00098].
• kNotConnected : aucun client externe n'a été détecté [SWS_LOG_00098].
• kConnected : un client distant est connecté avec succès [SWS_LOG_00098].

Interaction et concurrence

L'énumération sert principalement de paramètre de transmission pour le rappel de fonction ConnectionStateHandler (défini comme std::function<void(ClientState)>), qui est enregistré via ara::log::RegisterConnectionStateHandler [SWS_LOG_00265]. Ce gestionnaire est déclaré comme thread-safe [SWS_LOG_00265]. Interprétation : les gestionnaires enregistrés devraient être appelés de manière asynchrone dès que le backend DLT détecte des changements d'état du client externe. Question Q-b78ef73772a658a2 (ouverte)

Utilisation

La fonction CreateLogger dans l'espace de noms ara::log sert à créer et à enregistrer un objet Logger qui gère le contexte respectif au sein du framework de journalisation [SWS_LOG_00021]. Lors de l'appel, l'identifiant de contexte ctxId, la description textuelle ctxDescription ainsi que le niveau de log par défaut ctxDefLogLevel sont transmis [SWS_LOG_00021]. Si aucun modèle n'est disponible, le framework redirige par défaut les sorties vers la console comme puits [SWS_LOG_00021].

La fonction renvoie une référence Logger & vers l'instance gérée en interne. La propriété (ownership) demeure ici intégralement au sein du framework de journalisation [SWS_LOG_00021].

Concurrence et sécurité d'exécution

L'interface est déclarée comme noexcept et spécifiée à la fois comme sûre face aux exceptions (exception safe) et sûre au niveau des threads (thread-safe) [SWS_LOG_00021]. Elle peut ainsi être appelée en toute sécurité depuis plusieurs threads concurrents.

Interaction et alternatives

Des interfaces apparentées sont disponibles pour différentes approches de configuration :

• Une surcharge alternative permet l'instanciation uniquement via ctxId et ctxDescription [SWS_LOG_00263], Warning étant implicitement utilisé comme niveau de log par défaut [SWS_LOG_00021].
• De plus, un Logger peut être dérivé d'après le modèle via un ara::core::InstanceSpecifier issu du manifeste [SWS_LOG_00256]. La plateforme vérifie alors des erreurs telles que InstanceSpecifierMappingIntegrityViolation ou PortInterfaceMappingViolation [SWS_LOG_00256].

La fonction synchrone CreateLogger crée ou renvoie une référence vers un objet Logger géré en interne, sur la base des données de modèle du manifeste [SWS_LOG_00256]. Une référence vers un ara::core::InstanceSpecifier, qui identifie l'élément de modèle souhaité dans le contexte du processus en cours d'exécution, sert de paramètre d'appel [SWS_LOG_00256].

La fonction est déclarée comme noexcept, est considérée comme sûre face aux exceptions (exception safe) et est spécifiée comme thread-safe, de sorte que les appels peuvent être réentrants et concurrents [SWS_LOG_00256]. Pour les configurations erronées ou les contextes de modèle invalides, la spécification définit plusieurs violations (Violations) [SWS_LOG_00256] :

• InstanceSpecifierMappingIntegrityViolation : survient lorsque l'InstanceSpecifier ne peut pas être résolu dans le contexte de l'exécutable ou renvoie vers un élément autre qu'un PortPrototype [SWS_LOG_00256].
• PortInterfaceMappingViolation : est déclenché si le type de mappage ne correspond pas au type attendu de l'interface de port [SWS_LOG_00256].
• ProcessMappingViolation : s'applique si une InstanceRef correspondante existe bien, mais qu'aucun processus modélisé ne correspond au processus d'exécution [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation : signale qu'un constructeur dans le framework a été appelé avec un identifiant qui est déjà utilisé dans ce processus [SWS_LOG_00256].

Par comparaison avec les surcharges [SWS_LOG_00021] et [SWS_LOG_00263], qui initialisent les loggers par programmation via des ID de contexte et des chaînes de description et utilisent par défaut la console comme puits en l'absence de modèle, la configuration est ici entièrement pilotée par le manifeste. Dans toutes les variantes, la propriété de l'instance demeure au sein du framework de journalisation [SWS_LOG_00263].

La fonction CreateLogger dans l'espace de noms ara::log ([SWS_LOG_00263]) sert à la création et à l'enregistrement d'un objet Logger lié à un contexte au sein du framework de journalisation d'AUTOSAR Adaptive.

Utilisation

Via le fichier d'en-tête ara/log/logger.h, la fonction reçoit l'identifiant de contexte ctxId ainsi que la description détaillée ctxDescription chacun en tant que type ara::core::StringView [SWS_LOG_00263]. En guise de valeur de retour, l'appel renvoie une référence Logger & vers l'instance gérée en interne de l'objet Logger créé [SWS_LOG_00263]. La propriété (ownership) sur cette instance demeure en permanence auprès du framework de journalisation et n'est pas transférée à l'appelant [SWS_LOG_00263]. Si aucun modèle n'est disponible dans le système, la console fait office par défaut de puits (sink) pour toutes les sorties de journalisation [SWS_LOG_00263].

Gestion des erreurs et concurrence

Aucun code d'erreur spécifique n'est défini pour l'appel et aucune exception C++ n'est levée, car la fonction est spécifiée avec noexcept et désignée comme sûre face aux exceptions (exception safe) [SWS_LOG_00263]. En ce qui concerne la concurrence, CreateLogger est thread-safe, de sorte que la fonction peut être appelée de manière concurrente depuis plusieurs threads sans synchronisation externe [SWS_LOG_00263].

Interaction

Le framework de journalisation propose des surcharges étroitement apparentées : outre cette signature à deux paramètres, une surcharge permet la configuration supplémentaire d'un niveau de log par défaut via ctxDefLogLevel ([SWS_LOG_00021]). Une autre signature permet la création d'un objet Logger via un ara::core::InstanceSpecifier directement à partir du manifeste ([SWS_LOG_00256]).

Utilisation

La fonction ara::log::EngFloatMax() du fichier d’en-tête ara/log/logger.h crée de manière synchrone une instance du type Format [SWS_LOG_00220]. L’objet renvoyé contient l’indication de formatage Fmt::kEngFloat pour l’affichage de nombres à virgule flottante en notation d’ingénieur ainsi qu’une précision suffisante pour une conversion aller-retour complète (« full round-trip safety ») [SWS_LOG_00220]. La fonction n’attend aucun paramètre.

Gestion des erreurs

La fonction est dotée du spécificateur noexcept et définie comme sûre vis-à-vis des exceptions (exception safe) [SWS_LOG_00220]. Il n’existe aucun code d’erreur spécifique, et aucune exception n’est levée ni aucune erreur transmise à des entités de diagnostic ou de notification d’erreurs. L’appel n’échoue pas en fonctionnement normal.

Concurrence et restrictions

La spécification caractérise la fonction comme thread-safe (thread-safe) [SWS_LOG_00220]. Grâce à la désignation en tant que constexpr, l’appel peut être évalué dès la compilation. Interprétation : comme la spécification ne définit aucune précondition et que la fonction est sans état, il ne devrait exister ni restrictions quant au contexte d’appel ni dépendances envers une initialisation préalable de l’infrastructure de journalisation. Question Q-90c67bfad5b19641 (ouverte)

La fonction utilitaire HexFloat sert à créer un objet de formatage pour les nombres à virgule flottante en vue d'une sortie au format hexadécimal conformément à [SWS_LOG_00221]. Elle instancie un objet du type Format, pourvu de l'indication de formatage Fmt::kHexFloat ainsi que d'une précision prédéfinie.

Utilisation et paramètres

La fonction est disponible dans l'espace de noms ara::log via l'en-tête #include "ara/log/logger.h" [SWS_LOG_00221] :

• Paramètres : comme paramètre d'entrée, precision de type std::uint16_t est transmis, ce qui définit la précision de sortie souhaitée [SWS_LOG_00221].
• Valeur de retour : un objet Format initialisé avec le préfixe Fmt::kHexFloat défini [SWS_LOG_00221].
• Exécution : grâce à la désignation comme constexpr, la construction de l'indication de formatage peut s'effectuer de manière synchrone au moment de l'exécution ou dès la compilation [SWS_LOG_00221].

Gestion des erreurs et concurrence

La signature est déclarée avec noexcept et est considérée comme totalement sûre vis-à-vis des exceptions (exception safe) [SWS_LOG_00221]. Aucun code d'erreur ni message d'erreur spécifique n'est généré. La fonction est spécifiée comme sûre pour les threads (thread-safe) et peut être appelée en parallèle depuis n'importe quel contexte sans nécessiter de synchronisation [SWS_LOG_00221].

La fonction HexFloatMax dans l’espace de noms ara::log sert à créer une instance de Format pour la sortie formatée de valeurs à virgule flottante [SWS_LOG_00222]. Elle est mise à disposition via le fichier d’en-tête #include "ara/log/logger.h" et ne prend aucun paramètre d’appel [SWS_LOG_00222]. Une instance de Format est fournie comme valeur de retour synchrone, dotée de l’indication de formatage Fmt::kHexFloat et présentant une précision qui garantit une sécurité round-trip complète [SWS_LOG_00222].

La signature est déclarée comme constexpr ainsi que noexcept [SWS_LOG_00222]. Cela permet une évaluation dès la compilation et garantit qu’aucune exception ne peut survenir lors de l’exécution. Aucun état d’erreur particulier, code d’erreur ou mécanisme de traitement des erreurs n’est spécifié pour cet appel, car la création de l’objet de format s’effectue toujours sans erreur.

Concernant le contexte d’appel et la concurrence, la fonction est spécifiée comme sûre vis-à-vis des exceptions (exception safe) et thread-safe (thread-safe) [SWS_LOG_00222]. Elle n’est soumise à aucune restriction d’appel séquentiel et peut être appelée en toute sécurité et de manière concurrente depuis des threads quelconques sans synchronisation supplémentaire.

Utilisation

La fonction ara::log::Oct() sert de fonction utilitaire pour créer un objet de formatage destiné aux sorties de journalisation en système octal [SWS_LOG_00213]. Elle n'accepte aucun paramètre et renvoie de manière synchrone un objet de type Format configuré avec l'indication de formatage Fmt::kOct ainsi qu'une précision par défaut [SWS_LOG_00213]. La fonction étant déclarée comme constexpr, l'instanciation peut s'effectuer dès la compilation. Interprétation : l'objet Format renvoyé devrait être principalement prévu pour contrôler le formatage d'entiers dans les flux de journalisation. Question Q-3f4fe5ac42de16cb (ouverte)

Gestion des erreurs

La fonction garantit la sécurité face aux exceptions (exception safe) et est explicitement déclarée comme noexcept [SWS_LOG_00213]. La survenue d'erreurs d'exécution ou la levée d'exceptions est exclue. Aucun code d'erreur spécifique n'existe et aucune notification n'est transmise à DET ou DEM.

Concurrence et restrictions

L'appel de Oct() est sans restriction sûr pour les threads (thread-safe) [SWS_LOG_00213]. Étant donné qu'aucun état partagé n'est modifié, la fonction n'est soumise à aucune restriction relative à la réentrance ou au contexte d'appel et peut être appelée en parallèle depuis plusieurs threads.

Interaction

La fonction est définie dans l'espace de nommage ara::log et mise à disposition via le fichier d'en-tête #include "ara/log/logger.h" [SWS_LOG_00213]. En plus de cette variante sans paramètre, il existe la surcharge Oct(std::uint16_t precision) permettant de définir une précision de chiffres différente [SWS_LOG_00214].

Utilisation

La fonction utilitaire ara::log::Oct est mise à disposition via le fichier d'en-tête #include "ara/log/logger.h" dans l'espace de noms ara::log [SWS_LOG_00214]. Elle sert à générer une instance du type Format avec l'indication de formatage Fmt::kOct ainsi qu'une précision prédéfinie [SWS_LOG_00214]. Comme paramètre d'entrée, la fonction accepte la valeur entière non signée 16 bits precision, qui définit la précision à appliquer [SWS_LOG_00214]. La fonction opère de manière synchrone et renvoie immédiatement l'instance Format générée [SWS_LOG_00214].

Gestion des erreurs et concurrence

La fonction est déclarée comme noexcept et expressément spécifiée comme sûre vis-à-vis des exceptions (exception safe) [SWS_LOG_00214]. Il n'existe ni codes d'erreur spécifiques ni notifications via DET ou DEM en cas d'erreur. Concernant le contexte d'appel et la concurrence, la fonction est classée comme sûre pour les threads (thread-safe) [SWS_LOG_00214]. Comme elle est en outre définie comme constexpr, la génération de l'instruction de formatage peut avoir lieu dès la compilation [SWS_LOG_00214].

Interaction

Au sein du module log, la fonction complète la surcharge apparentée Oct() [SWS_LOG_00213]. Alors que la variante sans paramètre construit une instance Format avec la précision par défaut (default precision) [SWS_LOG_00213], la présente fonction permet la configuration explicite d'une précision spécifique à l'utilisateur pour le formatage octal [SWS_LOG_00214].

La fonction RegisterConnectionStateHandler dans l’espace de noms ara::log sert à enregistrer une fonction de rappel côté application, qui est appelée à chaque changement de l’état de connexion [SWS_LOG_00205]. Elle est déclarée dans l’en-tête ara/log/logger.h [SWS_LOG_00205]. Un objet fonction callback de type ConnectionStateHandler est transmis en paramètre [SWS_LOG_00205], lequel est spécifié comme alias de type pour std::function<void(ClientState)> [SWS_LOG_00265]. Aucune valeur de retour n’est présente (void) [SWS_LOG_00205].

En ce qui concerne le cycle de vie et l’ordonnancement, il est établi qu’un seul gestionnaire d’état peut être installé à tout moment [SWS_LOG_00205]. Si une fonction de rappel a déjà été enregistrée auparavant, chaque nouvel appel écrase complètement l’instance existante, de sorte qu’à partir de ce moment, seul le dernier gestionnaire transmis est exécuté [SWS_LOG_00205].

La fonction est déclarée avec noexcept et spécifiée comme sûre vis-à-vis des exceptions (« exception safe ») [SWS_LOG_00205]. Aucun code d’erreur spécifique, aucune valeur d’erreur ni aucune notification à des moniteurs d’erreur ou de diagnostic n’est défini dans la spécification [SWS_LOG_00205].

En ce qui concerne la concurrence, RegisterConnectionStateHandler est expressément classée comme non thread-safe (« not thread-safe ») [SWS_LOG_00205]. L’enregistrement ne doit donc pas être appelé de manière concurrente non protégée depuis plusieurs threads et devrait idéalement avoir lieu pendant la phase d’initialisation. À l’inverse, l’alias de type ConnectionStateHandler est spécifié comme thread-safe [SWS_LOG_00265]. Interprétation : il devrait en résulter que le callback enregistré peut potentiellement être appelé depuis des contextes concurrents par l’environnement d’exécution de journalisation interne lors de changements d’état. Question Q-59eae7980ba48666 (ouverte)