klasse ara::log::Logger

De lidfunctie LogDebug van de klasse ara::log::Logger dient voor het genereren van logberichten met de foutklasse Debug en retourneert hiervoor een overeenkomstig geconfigureerd LogStream-object [SWS_LOG_00068]. De declaratie vindt plaats via het headerbestand #include "ara/log/logger.h" [SWS_LOG_00068].

Voor gebruik en semantiek zijn de volgende specificatiekenmerken gedefinieerd:

• Aanroep en retourwaarde: De methode accepteert geen overdrachtsparameters en retourneert direct een LogStream-object met de ernst Debug [SWS_LOG_00068]. De werkwijze komt daarbij overeen met de methode Logger::LogFatal() [SWS_LOG_00068].
• Foutafhandeling: De signatuur is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig (exception safe) [SWS_LOG_00068]. Er worden geen foutmeldingen of foutcodes aangegeven in geval van een fout [SWS_LOG_00068].
• Gelijktijdigheid: De lidfunctie is geclassificeerd als constant (const) en expliciet als thread-safe (thread-safe) [SWS_LOG_00068], zodat parallelle leestoegangen via dezelfde logger-instantie toelaatbaar zijn.

De methode LogError van de klasse ara::log::Logger dient voor de initiatie van een log-item met de ernst Error [SWS_LOG_00065]. De functie wordt via het headerbestand ara/log/logger.h gedeclareerd en accepteert geen parameters [SWS_LOG_00065].

Gebruik en retourwaarde

De synchrone aanroep retourneert een object van het type LogStream met de ernst Error [SWS_LOG_00065]. Het gedrag komt daarbij functioneel overeen met dat van Logger::LogFatal() [SWS_LOG_00065]. Omdat LogError als const is gedeclareerd, modificeert de aanroep de toestand van het logger-object niet en kan deze ook op constante instanties worden uitgevoerd [SWS_LOG_00065].

Concurrentie en exceptieveiligheid

Voor de aanroepcontext gelden vastgelegde garanties [SWS_LOG_00065]:

• Thread-veiligheid: De functie is gespecificeerd als thread-safe [SWS_LOG_00065]. Interpretatie: Aanroepen mogen dus gelijktijdig vanuit meerdere threads op dezelfde instantie plaatsvinden zonder externe synchronisatie. Vraag Q-e55d2b523c5cbcb3 (open)
• Uitzonderingsveiligheid: De methode is gedeclareerd als noexcept en als exception safe [SWS_LOG_00065]; ze werpt tijdens runtime geen exceptions op.

Foutafhandeling

Specifieke foutcodes of meldingen aan DET of DEM zijn voor LogError niet voorzien [SWS_LOG_00065]. Fouttoestanden bij de aanroep worden uitgesloten door de gegarandeerde uitzonderingsveiligheid en de parameterloze interface [SWS_LOG_00065].

Gebruik en levensduur

De methode LogFatal van de klasse ara::log::Logger (beschikbaar gesteld via de header ara/log/logger.h) maakt een LogStream-object aan met de ernstgraad Fatal ([SWS_LOG_00064]). De functie accepteert geen argumenten en retourneert de stream direct. Het geretourneerde LogStream-object accepteert logberichten en parameters sequentieel via de stream-operator << ([SWS_LOG_00064]). In het reguliere toepassingsscenario is de levensduur van de aangemaakte stream beperkt tot één enkele instructie en eindigt deze met de afsluitende puntkomma na de laatst doorgegeven parameter ([SWS_LOG_00064]). Om de levensduur van het stream-object daarnaast te verlengen, kan het worden toegewezen aan een benoemde variabele ([SWS_LOG_00064]).

Foutafhandeling en gelijktijdigheid

De functie is gedeclareerd als noexcept en gespecificeerd als exceptieveilig (exception safe) ([SWS_LOG_00064]). Deze werpt tijdens runtime geen excepties en gebruikt geen specifieke foutcodes. Wat betreft gelijktijdigheid is de methode gespecificeerd als const en volledig thread-veilig (thread-safe), waardoor parallelle aanroepen via dezelfde logger-instantie zijn toegestaan ([SWS_LOG_00064]).

Samenspel

De methode komt qua interface en gedrag overeen met de verwante logging-methoden voor afwijkende ernstgraden binnen ara::log::Logger: LogError ([SWS_LOG_00065]), LogWarn ([SWS_LOG_00066]), LogInfo ([SWS_LOG_00067]), LogDebug ([SWS_LOG_00068]) evenals LogVerbose ([SWS_LOG_00069]).

De lidfunctie LogInfo van de klasse ara::log::Logger ([SWS_LOG_00067]) wordt gedeclareerd via de header ara/log/logger.h. Ze dient voor het genereren van een logbericht met de ernst Info, vereist geen overdrachtsparameters en retourneert synchroon een object van het type LogStream ([SWS_LOG_00067]). Het gedrag komt volgens de specificatie overeen met dat van Logger::LogFatal() ([SWS_LOG_00067]), waarbij de interpretatie is dat de functionaliteit analoog werkt en enkel de ernstclassificatie op Info is vastgelegd.

Wat gelijktijdigheid en aanroepcontext betreft, is de methode gedeclareerd als const en expliciet gespecificeerd als thread-safe (thread-safe) ([SWS_LOG_00067]). Daardoor mag LogInfo te allen tijde parallel door meerdere threads op dezelfde logger-instantie worden aangeroepen, zonder dat applicatieverantwoordelijke synchronisatiemechanismen of locks vereist zijn.

Bij de foutafhandeling is de functie voorzien van de aanduiding noexcept en geclassificeerd als uitzonderingsveilig (exception safe) ([SWS_LOG_00067]). Er worden noch specifieke foutcodes geretourneerd, noch DEM- of DET-foutmeldingen geactiveerd ([SWS_LOG_00067]); een foutsituatie is voor deze aanroep niet gedefinieerd.

In het eisenkader is de interface direct toegewezen aan de upstream-requirements [RS_LT_00003] en [RS_LT_00049] ([SWS_LOG_00067]), die de overkoepelende richtlijnen voor het logging- en tracing-subsysteem definiëren.

De methode LogVerbose() van de klasse ara::log::Logger uit het headerbestand #include "ara/log/logger.h" dient voor het genereren van log-uitvoer met de meest gedetailleerde ernst Verbose [SWS_LOG_00069]. Bij de aanroep worden geen parameters doorgegeven. De functie levert synchroon een LogStream-object op dat expliciet met de severity Verbose is geïnitialiseerd en wordt gebruikt voor het doorgeven van berichtinhoud [SWS_LOG_00069].

De specificatie geeft het gedrag aan als identiek aan Logger::LogFatal() uit [SWS_LOG_00069]; ter interpretatie duidt dit er waarschijnlijk op dat het bufferen en aanbieden van de stream het algemene logmechanisme volgt en zich uitsluitend onderscheidt door de toegewezen ernstgraad. Vraag Q-522523e7a845dc3a (open) Voor foutafhandeling is de methode gespecificeerd als noexcept en exception safe [SWS_LOG_00069]. Er treden bijgevolg geen exceptions op en specifieke foutcodes bestaan niet in de aanroepcontext [SWS_LOG_00069].

Met betrekking tot gelijktijdigheid en interfacecontracten gelden de volgende eigenschappen:

• Thread safety: de methode is geclassificeerd als thread-safe, zodat gelijktijdige aanroepen via dezelfde of verschillende logger-instanties veilig kunnen worden uitgevoerd [SWS_LOG_00069].
• Constancy: de declaratie als const garandeert dat de aanroep de interne toestand van het logger-object niet wijzigt [SWS_LOG_00069].

Gebruik

De lidfunctie LogWarn van de klasse ara::log::Logger wordt via de header ara/log/logger.h beschikbaar gesteld [SWS_LOG_00066]. De aanroep geschiedt parameterloos op een logger-instantie via de signatuur LogStream LogWarn () const noexcept; [SWS_LOG_00066]. Als retourwaarde levert de functie synchroon een object van het type LogStream met de ernstclassificatie Warn (Warn severity) op [SWS_LOG_00066]. Het functionele gedrag komt daarbij overeen met de beschrijving van Logger::LogFatal() [SWS_LOG_00066]. Interpretatie: Het geleverde LogStream-object dient er vermoedelijk toe logberichten van het waarschuwingsniveau samen te stellen voor verdere uitvoer. Vraag Q-02b18df759926020 (open)

Gelijktijdigheid en foutveiligheid

Met betrekking tot de aanroepcontext en de gelijktijdigheid is de methode gespecificeerd als thread-safe [SWS_LOG_00066]. Ze kan zodoende veilig worden aangeroepen vanuit meerdere gelijktijdige threads op dezelfde instantie. De functie garandeert volledige uitzonderingsveiligheid (exception safe) en is gedeclareerd met noexcept [SWS_LOG_00066]. Specifieke foutcodes, foutwaarden of terugmeldsignalen voor runtimefouten zijn voor deze operatie niet gedefinieerd [SWS_LOG_00066]; Interpretatie: Een mislukking van de teruggave is in regulier bedrijf vermoedelijk uitgesloten. Vraag Q-44b264cd97ff8159 (open)

Gebruik

De templatemethode LogWith van de klasse ara::log::Logger dient voor het gestructureerd protocolleren van berichten aan de hand van een identificatie evenals bijbehorende attributen en argumenten [SWS_LOG_00133]. Deze wordt via de header #include "ara/log/logger.h" ingevoegd en synchroon zonder retourwaarde uitgevoerd [SWS_LOG_00133].

De functie accepteert de volgende parameters [SWS_LOG_00133]:

• attrs: een std::tuple met attributen van het bericht (types Attrs...),
• msgId: een implementatiedefinieerde instantie van het type MsgId ter identificatie van het berichtobject,
• params: variadische argumenten (types Params...) die aan het logitem worden toegevoegd.

Gelijktijdigheid en beperkingen

De functie is gespecificeerd als thread-safe en kan gelijktijdig worden uitgevoerd [SWS_LOG_00133]. Deze is gedeclareerd met noexcept en ingedeeld als uitzonderingsveilig (exception safe), waardoor er geen C++-excepties worden geworpen [SWS_LOG_00133]. Specifieke foutcodes of foutmeldingen zijn niet gedefinieerd.

Voor de template-instantiëring geldt: de functie neemt niet deel aan overload resolution als ten minste een van de types in Attrs... geen geldig berichtattribuut vormt [SWS_LOG_00133]. Interpretatie: Aangezien de eis aan het type Attr in de specificatie is gemarkeerd met TBD, hangt de concrete typecontrole vermoedelijk af van de desbetreffende platformimplementatie. Vraag Q-30f5de483410d716 (open)