class ara::log::Logger

Die Elementfunktion LogDebug der Klasse ara::log::Logger dient dem Erzeugen von Log-Meldungen mit der Fehlerschwere Debug und liefert hierfür ein entsprechend konfiguriertes LogStream-Objekt zurück [SWS_LOG_00068]. Die Deklaration erfolgt über die Header-Datei #include "ara/log/logger.h" [SWS_LOG_00068].

Zur Verwendung und Semantik sind folgende Spezifikationsmerkmale definiert:

• Aufruf und Rückgabewert: Die Methode nimmt keine Übergabeparameter entgegen und gibt direkt ein LogStream-Objekt mit Debug-Schweregrad zurück [SWS_LOG_00068]. Die Funktionsweise entspricht dabei der Methode Logger::LogFatal() [SWS_LOG_00068].
• Fehlerbehandlung: Die Signatur ist als noexcept deklariert und als ausnahmesicher (exception safe) spezifiziert [SWS_LOG_00068]. Es werden keine Fehlermeldungen oder Fehlercodes im Fehlerfall ausgewiesen [SWS_LOG_00068].
• Nebenläufigkeit: Die Elementfunktion ist als konstant (const) sowie explizit als threadsicher (thread-safe) klassifiziert [SWS_LOG_00068], sodass parallele Lesezugriffe über dieselbe Logger-Instanz zulässig sind.

Die Methode LogError der Klasse ara::log::Logger dient der Initiierung eines Log-Eintrags mit dem Schweregrad Error [SWS_LOG_00065]. Die Funktion wird über die Header-Datei ara/log/logger.h deklariert und nimmt keine Parameter entgegen [SWS_LOG_00065].

Verwendung und Rückgabewert

Der synchrone Aufruf liefert ein Objekt vom Typ LogStream mit dem Schweregrad Error zurück [SWS_LOG_00065]. Das Verhalten entspricht dabei funktional dem von Logger::LogFatal() [SWS_LOG_00065]. Da LogError als const deklariert ist, modifiziert der Aufruf den Zustand des Logger-Objekts nicht und kann auch auf konstanten Instanzen ausgeführt werden [SWS_LOG_00065].

Nebenläufigkeit und Ausnahmesicherheit

Für den Aufrufkontext gelten festgelegte Garantien [SWS_LOG_00065]:

• Thread-Sicherheit: Die Funktion ist als thread-safe spezifiziert [SWS_LOG_00065]. Interpretation: Aufrufe dürften somit nebenläufig aus mehreren Threads auf derselben Instanz ohne externe Synchronisation erfolgen. Frage Q-e55d2b523c5cbcb3 (offen)
• Ausnahmesicherheit: Die Methode ist als noexcept sowie als exception safe deklariert [SWS_LOG_00065]; sie löst zur Laufzeit keine Exceptions aus.

Fehlerbehandlung

Spezifische Fehlercodes oder Benachrichtigungen an DET oder DEM sind für LogError nicht vorgesehen [SWS_LOG_00065]. Fehlerzustände beim Aufruf werden durch die zugesicherte Ausnahmesicherheit und die parameterlose Schnittstelle ausgeschlossen [SWS_LOG_00065].

Verwendung und Lebensdauer

Die Methode LogFatal der Klasse ara::log::Logger (bereitgestellt über den Header ara/log/logger.h) erzeugt ein LogStream-Objekt mit dem Schweregrad Fatal ([SWS_LOG_00064]). Die Funktion nimmt keine Argumente entgegen und gibt den Stream direkt zurück. Das zurückgegebene LogStream-Objekt nimmt Lognachrichten und Parameter sequenziell über den Stream-Operator << entgegen ([SWS_LOG_00064]). Im regulären Anwendungsszenario ist die Lebensdauer des erzeugten Streams auf eine einzelne Anweisung beschränkt und endet mit dem abschließenden Semikolon nach dem letzten übergebenen Parameter ([SWS_LOG_00064]). Um die Lebensdauer des Stream-Objekts darüber hinaus zu verlängern, kann es einer benannten Variable zugewiesen werden ([SWS_LOG_00064]).

Fehlerbehandlung und Nebenläufigkeit

Die Funktion ist als noexcept deklariert und als exceptionsicher (exception safe) spezifiziert ([SWS_LOG_00064]). Sie wirft zur Laufzeit keine Exceptions und verwendet keine spezifischen Fehlercodes. Hinsichtlich der Nebenläufigkeit ist die Methode als const sowie vollständig threadsicher (thread-safe) spezifiziert, wodurch parallele Aufrufe über dieselbe Logger-Instanz zulässig sind ([SWS_LOG_00064]).

Zusammenspiel

Die Methode entspricht in Schnittstelle und Verhalten den verwandten Logging-Methoden für abweichende Schweregrade innerhalb von ara::log::Logger: LogError ([SWS_LOG_00065]), LogWarn ([SWS_LOG_00066]), LogInfo ([SWS_LOG_00067]), LogDebug ([SWS_LOG_00068]) sowie LogVerbose ([SWS_LOG_00069]).

Die Elementfunktion LogInfo der Klasse ara::log::Logger ([SWS_LOG_00067]) wird über den Header ara/log/logger.h deklariert. Sie dient dem Erzeugen einer Log-Meldung mit dem Schweregrad Info, erfordert keine Übergabeparameter und gibt synchron ein Objekt vom Typ LogStream zurück ([SWS_LOG_00067]). Das Verhalten entspricht laut Spezifikation dem von Logger::LogFatal() ([SWS_LOG_00067]), wobei Interpretation ist, dass die Funktionalität analog arbeitet und lediglich die Schweregrad-Einstufung auf Info festgelegt ist.

Bezüglich Nebenläufigkeit und Aufrufkontext ist die Methode als const deklariert und explizit als threadsicher (thread-safe) spezifiziert ([SWS_LOG_00067]). Dadurch darf LogInfo jederzeit parallel von mehreren Threads auf derselben Logger-Instanz aufgerufen werden, ohne dass anwendungsverantwortliche Synchronisationsmechanismen oder Sperren erforderlich sind.

In der Fehlerbehandlung ist die Funktion mit dem Bezeichner noexcept versehen und als ausnahmesicher (exception safe) klassifiziert ([SWS_LOG_00067]). Es werden weder spezifische Fehlercodes zurückgegeben noch DEM- oder DET-Fehlermeldungen ausgelöst ([SWS_LOG_00067]); ein Fehlerfall ist für diesen Aufruf nicht definiert.

Im Anforderungsgefüge ist die Schnittstelle direkt den Upstream-Requirements [RS_LT_00003] und [RS_LT_00049] zugeordnet ([SWS_LOG_00067]), welche die übergeordneten Leitlinien für das Logging- und Tracing-Subsystem definieren.

Die Methode LogVerbose() der Klasse ara::log::Logger aus der Header-Datei #include "ara/log/logger.h" dient dem Erzeugen von Log-Ausgaben mit dem detailliertesten Schweregrad Verbose [SWS_LOG_00069]. Beim Aufruf werden keine Parameter übergeben. Die Funktion liefert synchron ein LogStream-Objekt zurück, das explizit mit der Severity Verbose initialisiert ist und zur Weitergabe von Meldungsinhalten genutzt wird [SWS_LOG_00069].

Die Spezifikation weist das Verhalten als identisch zu Logger::LogFatal() aus [SWS_LOG_00069]; als Interpretation dürfte dies bedeuten, dass die Pufferung und Bereitstellung des Streams der allgemeinen Log-Mechanik folgt und sich lediglich durch den zugewiesenen Schweregrad unterscheidet. Frage Q-522523e7a845dc3a (offen) Für die Fehlerbehandlung ist die Methode als noexcept sowie exception safe spezifiziert [SWS_LOG_00069]. Es treten folglich keine Exceptions auf, und spezifische Fehlercodes existieren im Aufrufkontext nicht [SWS_LOG_00069].

In Bezug auf Nebenläufigkeit und Schnittstellenverträge gelten folgende Eigenschaften:

• Thread-Sicherheit: Die Methode ist als thread-safe klassifiziert, sodass konkurrierende Aufrufe über dieselbe oder verschiedene Logger-Instanzen sicher ausgeführt werden können [SWS_LOG_00069].
• Konstanz: Die Deklaration als const garantiert, dass der Aufruf den internen Zustand des Logger-Objekts nicht verändert [SWS_LOG_00069].

Verwendung

Die Elementfunktion LogWarn der Klasse ara::log::Logger wird über den Header ara/log/logger.h bereitgestellt [SWS_LOG_00066]. Der Aufruf erfolgt parameterlos auf einer Logger-Instanz über die Signatur LogStream LogWarn () const noexcept; [SWS_LOG_00066]. Als Rückgabewert liefert die Funktion synchron ein Objekt vom Typ LogStream mit der Schweregrad-Einstufung Warn (Warn severity) zurück [SWS_LOG_00066]. Das funktionale Verhalten entspricht dabei der Beschreibung von Logger::LogFatal() [SWS_LOG_00066]. Interpretation: Das gelieferte LogStream-Objekt dürfte dazu dienen, Protokollnachrichten der Warnstufe für die weitere Ausgabe zusammenzustellen. Frage Q-02b18df759926020 (offen)

Nebenläufigkeit und Fehlersicherheit

Hinsichtlich des Aufrufkontexts und der Nebenläufigkeit ist die Methode als thread-safe spezifiziert [SWS_LOG_00066]. Sie kann somit sicher aus mehreren nebenläufigen Threads auf derselben Instanz aufgerufen werden. Die Funktion garantiert volle Exception-Sicherheit (exception safe) und ist mit noexcept deklariert [SWS_LOG_00066]. Spezifische Fehlercodes, Fehlerwerte oder Rückmeldesignale für Laufzeitfehler sind für diese Operation nicht definiert [SWS_LOG_00066]; Interpretation: Ein Scheitern der Rückgabe dürfte im regulären Betrieb ausgeschlossen sein. Frage Q-44b264cd97ff8159 (offen)

Verwendung

Die Template-Methode LogWith der Klasse ara::log::Logger dient dem strukturierten Protokollieren von Nachrichten anhand einer Kennung sowie zugehöriger Attribute und Argumente [SWS_LOG_00133]. Sie wird über den Header #include "ara/log/logger.h" eingebunden und synchron ohne Rückgabewert ausgeführt [SWS_LOG_00133].

Die Funktion nimmt folgende Parameter entgegen [SWS_LOG_00133]:

• attrs: ein std::tuple mit Attributen der Nachricht (Typen Attrs...),
• msgId: eine implementierungsdefinierte Instanz vom Typ MsgId zur Identifikation des Nachrichtenobjekts,
• params: variadische Argumente (Typen Params...), die dem Protokolleintrag hinzugefügt werden.

Nebenläufigkeit und Einschränkungen

Die Funktion ist als thread-safe spezifiziert und kann nebenläufig ausgeführt werden [SWS_LOG_00133]. Sie ist mit noexcept deklariert und als ausnahmesicher (exception safe) eingestuft, weshalb keine C++-Exceptions geworfen werden [SWS_LOG_00133]. Spezifische Fehlercodes oder Fehlermeldungen sind nicht definiert.

Für die Template-Instanziierung gilt: Die Funktion nimmt nicht an der Überladungsauflösung teil, falls mindestens einer der Typen in Attrs... kein zulässiges Nachrichtenattribut darstellt [SWS_LOG_00133]. Interpretation: Da die Anforderung an den Typ Attr in der Spezifikation mit TBD gekennzeichnet ist, dürfte die konkrete Typprüfung von der jeweiligen Plattform-Implementierung abhängen. Frage Q-30f5de483410d716 (offen)