namespace ara::log

Die Enumeration ara::log::ClientState bildet den aktuellen Verbindungsstatus eines externen Clients zum DLT-Backend ab [SWS_LOG_00098]. Sie basiert auf dem Datentyp std::int8_t und wird über die Header-Datei #include "ara/log/common.h" bzw. den Forwarding-Header #include "ara/log/log_fwd.h" eingebunden [SWS_LOG_00098].

Zustände und Semantik

Die Aufzählung definiert drei diskrete Verbindungszustände [SWS_LOG_00098]:

• kUnknown (-1): Das DLT-Backend ist noch nicht betriebsbereit; der tatsächliche Verbindungsstatus kann zu diesem Zeitpunkt nicht bestimmt werden [SWS_LOG_00098].
• kNotConnected: Es wurde kein externer Client erkannt [SWS_LOG_00098].
• kConnected: Ein entfernter Client ist erfolgreich verbunden [SWS_LOG_00098].

Zusammenspiel und Nebenläufigkeit

Die Enumeration dient vor allem als Übergabeparameter für den Funktions-Callback ConnectionStateHandler (definiert als std::function<void(ClientState)>), welcher über ara::log::RegisterConnectionStateHandler registriert wird [SWS_LOG_00265]. Dieser Handler ist als threadsicher deklariert [SWS_LOG_00265]. Interpretation: Registrierte Handler dürften asynchron aufgerufen werden, sobald das DLT-Backend Zustandswechsel des externen Clients feststellt. Frage Q-b78ef73772a658a2 (offen)

Der Typ-Alias ConnectionStateHandler spezifiziert die Signatur für Callback-Funktionen zur Überwachung des Verbindungsstatus im Modul log [SWS_LOG_00265]. Er ist im Namensraum ara::log deklariert und erfordert das Einbinden der Header-Datei ara/log/logger.h [SWS_LOG_00265]. Als Funktionshülle std::function<void(ClientState)> nimmt die Callback-Routine den eingetretenen Verbindungszustand über den Parameter vom Typ ClientState entgegen und liefert keinen Rückgabewert [SWS_LOG_00265].

Die Verwendung erfolgt über die Registrierungsfunktion RegisterConnectionStateHandler [SWS_LOG_00205]. Für das Zusammenspiel und den Lebenszyklus des Handlers gelten folgende Vorgaben:

• Aufrufzeitpunkt: Die registrierte Callback-Funktion wird jedes Mal aufgerufen, wenn sich der Verbindungsstatus des Clients ändert [SWS_LOG_00205].
• Exklusivität: Es kann zu jedem Zeitpunkt nur ein einziger Handler aktiv registriert sein [SWS_LOG_00205]. Wurde zuvor bereits ein Callback registriert, ersetzt die neu übergebene Funktion diesen vollständig, sodass fortan ausschließlich der neue Handler aufgerufen wird [SWS_LOG_00205].
• Ausnahmesicherheit: Die Registrierungsfunktion RegisterConnectionStateHandler ist mit noexcept spezifiziert, sodass die Übergabe des Funktions-Callbacks ausnahmesicher erfolgt [SWS_LOG_00205].

Hinsichtlich Nebenläufigkeit ist das Spezifikationselement als threadsicher gekennzeichnet [SWS_LOG_00265]. Interpretation: Da Statuswechsel durch die Logging-Infrastruktur potentiell asynchron signalisiert werden, dürfte die im Handler bereitgestellte Anwendungslogik reentrant ausgelegt sein müssen und keine blockierenden Operationen ausführen, um den Kommunikationskontext nicht zu behindern. Frage Q-ca507d992cc31284 (offen)

Verwendung

Die Funktion CreateLogger im Namespace ara::log dient der Erstellung und Registrierung eines Logger-Objekts, welches den jeweiligen Kontext innerhalb des Logging-Frameworks verwaltet [SWS_LOG_00021]. Beim Aufruf werden die Kontext-Kennung ctxId, die textuelle Beschreibung ctxDescription sowie der Standard-Log-Level ctxDefLogLevel übergeben [SWS_LOG_00021]. Steht kein Modell zur Verfügung, leitet das Framework die Ausgaben standardmäßig auf die Konsole als Senke um [SWS_LOG_00021].

Die Funktion gibt eine Referenz Logger & auf die intern verwaltete Instanz zurück. Die Eigentümerschaft (Ownership) verbleibt dabei vollständig im Logging-Framework [SWS_LOG_00021].

Nebenläufigkeit und Ausführungssicherheit

Die Schnittstelle ist als noexcept deklariert und sowohl als ausnahmesicher (exception safe) als auch threadsicher (thread-safe) spezifiziert [SWS_LOG_00021]. Sie kann somit sicher aus mehreren nebenläufigen Threads aufgerufen werden.

Zusammenspiel und Alternativen

Für unterschiedliche Konfigurationsansätze stehen verwandte Schnittstellen bereit:

• Eine alternative Überladung erlaubt die Instanziierung nur über ctxId und ctxDescription [SWS_LOG_00263], wobei als Standard-Log-Level implizit Warning verwendet wird [SWS_LOG_00021].
• Zudem kann ein Logger modellbasiert über einen ara::core::InstanceSpecifier aus dem Manifest abgeleitet werden [SWS_LOG_00256]. Dabei prüft die Plattform Fehler wie InstanceSpecifierMappingIntegrityViolation oder PortInterfaceMappingViolation [SWS_LOG_00256].

Die synchrone Funktion CreateLogger erzeugt bzw. liefert eine Referenz auf ein intern verwaltetes Logger-Objekt basierend auf den Modelldaten des Manifests [SWS_LOG_00256]. Als Aufrufparameter dient eine Referenz auf einen ara::core::InstanceSpecifier, welcher das gewünschte Modellelement im Kontext des laufenden Prozesses identifiziert [SWS_LOG_00256].

Die Funktion ist als noexcept deklariert, gilt als ausnahmesicher (exception safe) und ist threadsicher spezifiziert, sodass Aufrufe reentrant und nebenläufig erfolgen können [SWS_LOG_00256]. Für fehlerhafte Konfigurationen oder ungültige Modellkontexte definiert die Spezifikation mehrere Verletzungen (Violations) [SWS_LOG_00256]:

• InstanceSpecifierMappingIntegrityViolation: Tritt auf, wenn der InstanceSpecifier im Kontext der Executable nicht aufgelöst werden kann oder auf ein anderes Element als einen PortPrototype verweist [SWS_LOG_00256].
• PortInterfaceMappingViolation: Wird ausgelöst, falls der Mapping-Typ nicht dem erwarteten Typ der Port-Schnittstelle entspricht [SWS_LOG_00256].
• ProcessMappingViolation: Greift, wenn zwar eine passende InstanceRef existiert, jedoch kein modellierter Prozess zum Laufzeitprozess passt [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation: Signalisiert, dass ein Konstruktor im Framework mit einem Bezeichner aufgerufen wurde, der in diesem Prozess bereits verwendet wird [SWS_LOG_00256].

Im Vergleich zu den Überladungen [SWS_LOG_00021] und [SWS_LOG_00263], welche Logger programmatisch über Kontext-IDs und Beschreibungsstrings initialisieren und mangels Modell standardmäßig die Konsole als Senke nutzen, erfolgt die Konfiguration hier vollständig manifestgetrieben. Bei allen Varianten verbleibt die Eigentümerschaft der Instanz innerhalb des Logging-Frameworks [SWS_LOG_00263].

Die Funktion CreateLogger im Namensraum ara::log ([SWS_LOG_00263]) dient der Erzeugung und Registrierung eines Kontext-gebundenen Logger-Objekts innerhalb des Logging-Frameworks von AUTOSAR Adaptive.

Verwendung

Über die Header-Datei ara/log/logger.h nimmt die Funktion die Kontextkennung ctxId sowie die ausführliche Beschreibung ctxDescription jeweils als Typ ara::core::StringView entgegen [SWS_LOG_00263]. Als Rückgabewert liefert der Aufruf eine Referenz Logger & auf die intern verwaltete Instanz des erzeugten Logger-Objekts zurück [SWS_LOG_00263]. Das Eigentum (Ownership) an dieser Instanz verbleibt dauerhaft beim Logging-Framework und wird nicht an den Aufrufer übertragen [SWS_LOG_00263]. Falls im System kein Modell verfügbar ist, fungiert die Konsole standardmäßig als Senke (Sink) für alle Logging-Ausgaben [SWS_LOG_00263].

Fehlerbehandlung und Nebenläufigkeit

Für den Aufruf sind keine spezifischen Fehlercodes definiert und es werden keine C++-Ausnahmen ausgelöst, da die Funktion mit noexcept spezifiziert und als ausnahmesicher (exception safe) ausgewiesen ist [SWS_LOG_00263]. In Bezug auf die Nebenläufigkeit ist CreateLogger threadsicher (thread-safe), sodass die Funktion ohne externe Synchronisation nebenläufig aus mehreren Threads aufgerufen werden kann [SWS_LOG_00263].

Zusammenspiel

Das Logging-Framework bietet eng verwandte Überladungen an: Neben dieser zweiparametrigen Signatur gestattet eine Überladung die zusätzliche Konfiguration eines Standard-Log-Levels über ctxDefLogLevel ([SWS_LOG_00021]). Eine weitere Signatur ermöglicht die Erzeugung eines Logger-Objekts über einen ara::core::InstanceSpecifier direkt aus dem Manifest ([SWS_LOG_00256]).

Verwendung

Die Funktion ara::log::EngFloatMax() aus der Header-Datei ara/log/logger.h erzeugt synchron eine Instanz des Typs Format [SWS_LOG_00220]. Das zurückgegebene Objekt enthält den Formatierungshinweis Fmt::kEngFloat zur Ausgabe von Gleitkommazahlen in technischer Notation sowie eine Genauigkeit, die für eine vollständige Hin- und Rückkonvertierung („full round-trip safety“) ausreicht [SWS_LOG_00220]. Die Funktion erwartet keine Parameter.

Fehlerbehandlung

Die Funktion ist mit dem Spezifizierer noexcept versehen und als ausnahmesicher (exception safe) definiert [SWS_LOG_00220]. Es existieren keine spezifischen Fehlercodes, und es werden weder Exceptions geworfen noch Fehler an Diagnose- oder Fehlermeldeinstanzen übermittelt. Der Aufruf schlägt im regulären Betrieb nicht fehl.

Nebenläufigkeit und Einschränkungen

Die Spezifikation kennzeichnet die Funktion als threadsicher (thread-safe) [SWS_LOG_00220]. Dank der Kennzeichnung als constexpr kann der Aufruf bereits zur Übersetzungszeit evaluiert werden. Interpretation: Da die Spezifikation keine Vorbedingungen definiert und die Funktion zustandslos ist, dürften weder Einschränkungen hinsichtlich des Aufrufkontexts noch Abhängigkeiten von einer vorherigen Initialisierung der Logging-Infrastruktur bestehen. Frage Q-90c67bfad5b19641 (offen)

Die Hilfsfunktion HexFloat dient der Erstellung eines Formatierungsobjekts für Gleitkommazahlen zur Ausgabe im Hexadezimalformat gemäß [SWS_LOG_00221]. Sie instanziiert ein Objekt vom Typ Format, das mit dem Formatierungshinweis Fmt::kHexFloat sowie einer vorgegebenen Genauigkeit versehen ist.

Verwendung und Parameter

Die Funktion steht im Namespace ara::log über den Header #include "ara/log/logger.h" bereit [SWS_LOG_00221]:

• Parameter: Als Eingabeparameter wird precision vom Typ std::uint16_t übergeben, welcher die gewünschte Ausgabegenauigkeit festlegt [SWS_LOG_00221].
• Rückgabewert: Ein initialisiertes Format-Objekt mit gesetztem Fmt::kHexFloat-Präfix [SWS_LOG_00221].
• Ausführung: Durch die Kennzeichnung als constexpr kann die Konstruktion des Formatierungshinweises synchron zur Laufzeit oder bereits zur Übersetzungszeit erfolgen [SWS_LOG_00221].

Fehlerbehandlung und Nebenläufigkeit

Die Signatur ist mit noexcept deklariert und gilt als vollständig ausnahmesicher (exception safe) [SWS_LOG_00221]. Es werden weder Fehlercodes noch spezifische Fehlermeldungen erzeugt. Die Funktion ist als threadsicher (thread-safe) spezifiziert und kann ohne Synchronisationsaufwand parallel aus beliebigen Kontexten heraus aufgerufen werden [SWS_LOG_00221].

Die Funktion HexFloatMax im Namensraum ara::log dient der Erzeugung einer Format-Instanz für die formatierte Ausgabe von Gleitkommawerten [SWS_LOG_00222]. Sie wird über die Header-Datei #include "ara/log/logger.h" bereitgestellt und nimmt keine Aufrufparameter entgegen [SWS_LOG_00222]. Als synchroner Rückgabewert wird eine Format-Instanz geliefert, die mit dem Formatierungshinweis Fmt::kHexFloat versehen ist und eine Genauigkeit aufweist, welche eine vollständige Round-Trip-Sicherheit sicherstellt [SWS_LOG_00222].

Die Signatur ist als constexpr sowie noexcept deklariert [SWS_LOG_00222]. Dies erlaubt die Auswertung bereits zur Übersetzungszeit und garantiert, dass bei der Ausführung keine Ausnahmen auftreten können. Besondere Fehlerzustände, Fehlercodes oder Mechanismen zur Fehlerbehandlung sind für diesen Aufruf nicht spezifiziert, da die Erzeugung des Formatobjekts stets fehlerfrei erfolgt.

Hinsichtlich des Aufrufkontextes und der Nebenläufigkeit ist die Funktion als ausnahmesicher (exception safe) und threadsicher (thread-safe) spezifiziert [SWS_LOG_00222]. Sie unterliegt keinen sequenziellen Aufrufbeschränkungen und kann gefahrlos und nebenläufig aus beliebigen Threads ohne zusätzliche Synchronisation aufgerufen werden.

Verwendung

Die Funktion ara::log::Oct() dient als Hilfsfunktion zur Erstellung eines Formatierungsobjekts für Logging-Ausgaben im Oktalsystem [SWS_LOG_00213]. Sie nimmt keine Parameter entgegen und gibt synchron ein Objekt vom Typ Format zurück, das mit dem Formatierungshinweis Fmt::kOct sowie einer Standardpräzision konfiguriert ist [SWS_LOG_00213]. Da die Funktion als constexpr deklariert ist, kann die Instanziierung bereits zur Übersetzungszeit erfolgen. Interpretation: Das zurückgegebene Format-Objekt dürfte primär zur Steuerung der Formatierung von Ganzzahlen in Log-Streams vorgesehen sein. Frage Q-3f4fe5ac42de16cb (offen)

Fehlerbehandlung

Die Funktion garantiert Ausnahmesicherheit (exception safe) und ist explizit als noexcept deklariert [SWS_LOG_00213]. Ein Auftreten von Laufzeitfehlern oder das Werfen von Exceptions ist ausgeschlossen. Spezifische Fehlercodes existieren nicht, und es erfolgen keine Benachrichtigungen an DET oder DEM.

Nebenläufigkeit und Einschränkungen

Der Aufruf von Oct() ist uneingeschränkt thread-sicher (thread-safe) [SWS_LOG_00213]. Da keine gemeinsamen Zustände modifiziert werden, unterliegt die Funktion keinen Einschränkungen bezüglich Reentranz oder Aufrufkontext und kann parallel aus mehreren Threads aufgerufen werden.

Zusammenspiel

Definiert ist die Funktion im Namensraum ara::log und wird über die Header-Datei #include "ara/log/logger.h" bereitgestellt [SWS_LOG_00213]. Neben dieser parameterlosen Variante existiert die Überladung Oct(std::uint16_t precision), über welche eine abweichende Stellengenauigkeit festgelegt werden kann [SWS_LOG_00214].

Verwendung

Die Hilfsfunktion ara::log::Oct wird über die Header-Datei #include "ara/log/logger.h" im Namensraum ara::log bereitgestellt [SWS_LOG_00214]. Sie dient dazu, eine Instanz des Typs Format mit dem Formatierungshinweis Fmt::kOct sowie einer vorgegebenen Genauigkeit zu erzeugen [SWS_LOG_00214]. Als Eingabeparameter nimmt die Funktion den vorzeichenlosen 16-Bit-Ganzzahlwert precision entgegen, welcher die anzuwendende Genauigkeit festlegt [SWS_LOG_00214]. Die Funktion arbeitet synchron und gibt die erzeugte Format-Instanz unmittelbar zurück [SWS_LOG_00214].

Fehlerbehandlung und Nebenläufigkeit

Die Funktion ist als noexcept deklariert und ausdrücklich als ausnahmesicher (exception safe) spezifiziert [SWS_LOG_00214]. Es existieren weder spezifische Fehlercodes noch Benachrichtigungen über DET oder DEM im Fehlerfall. Hinsichtlich des Aufrufkontexts und der Nebenläufigkeit ist die Funktion als threadsicher (thread-safe) klassifiziert [SWS_LOG_00214]. Da sie zudem als constexpr definiert ist, kann die Erzeugung der Formatierungsanweisung bereits zur Übersetzungszeit erfolgen [SWS_LOG_00214].

Zusammenspiel

Innerhalb des Moduls log ergänzt die Funktion die verwandte Überladung Oct() [SWS_LOG_00213]. Während die parameterlose Variante eine Format-Instanz mit Standardgenauigkeit (default precision) konstruiert [SWS_LOG_00213], erlaubt die vorliegende Funktion die explizite Konfiguration einer anwenderspezifischen Genauigkeit für die oktale Formatierung [SWS_LOG_00214].

Die Funktion RegisterConnectionStateHandler im Namensraum ara::log dient dazu, eine anwendungsseitige Callback-Funktion zu registrieren, die bei jeder Änderung des Verbindungsstatus aufgerufen wird [SWS_LOG_00205]. Deklariert ist sie im Header ara/log/logger.h [SWS_LOG_00205]. Als Parameter wird ein Funktionsobjekt callback vom Typ ConnectionStateHandler übergeben [SWS_LOG_00205], welcher als Typalias für std::function<void(ClientState)> spezifiziert ist [SWS_LOG_00265]. Ein Rückgabewert ist nicht vorhanden (void) [SWS_LOG_00205].

Hinsichtlich des Lebenszyklus und der Reihenfolge ist festgelegt, dass zu jedem Zeitpunkt nur ein einziger Zustands-Handler installiert sein kann [SWS_LOG_00205]. Wurde bereits zuvor eine Callback-Funktion registriert, überschreibt jeder erneute Aufruf die bestehende Instanz vollständig, sodass ab diesem Zeitpunkt ausschließlich der zuletzt übergebene Handler ausgeführt wird [SWS_LOG_00205].

Die Funktion ist mit noexcept deklariert und als ausnahmesicher („exception safe“) spezifiziert [SWS_LOG_00205]. Spezifische Fehlercodes, Fehlerwerte oder Benachrichtigungen an Fehler- oder Diagnosemonitore sind in der Spezifikation nicht definiert [SWS_LOG_00205].

In Bezug auf die Nebenläufigkeit ist RegisterConnectionStateHandler ausdrücklich als nicht threadsicher („not thread-safe“) eingestuft [SWS_LOG_00205]. Die Registrierung darf daher nicht ungeschützt nebenläufig aus mehreren Threads aufgerufen werden und sollte idealerweise während der Initialisierungsphase erfolgen. Im Gegensatz dazu ist der Typalias ConnectionStateHandler als threadsicher spezifiziert [SWS_LOG_00265]. Interpretation: Daraus dürfte folgen, dass der registrierte Callback durch die interne Logging-Laufzeitumgebung potenziell aus nebenläufigen Kontexten heraus bei Statuswechseln aufgerufen werden kann. Frage Q-59eae7980ba48666 (offen)