namespace ara::log

De enumeratie ara::log::ClientState geeft de actuele verbindingsstatus weer van een externe client met de DLT-backend [SWS_LOG_00098]. Deze is gebaseerd op het datatype std::int8_t en wordt via het headerbestand #include "ara/log/common.h" respectievelijk de forwarding-header #include "ara/log/log_fwd.h" ingevoegd [SWS_LOG_00098].

Toestanden en semantiek

De enumeratie definieert drie discrete verbindingstoestanden [SWS_LOG_00098]:

• kUnknown (-1): De DLT-backend is nog niet operationeel; de werkelijke verbindingsstatus kan op dit moment niet worden bepaald [SWS_LOG_00098].
• kNotConnected: Er is geen externe client gedetecteerd [SWS_LOG_00098].
• kConnected: Een externe client is met succes verbonden [SWS_LOG_00098].

Interactie en gelijktijdigheid

De enumeratie dient vooral als doorgifteparameter voor de functie-callback ConnectionStateHandler (gedefinieerd als std::function<void(ClientState)>), die via ara::log::RegisterConnectionStateHandler wordt geregistreerd [SWS_LOG_00265]. Deze handler is gedeclareerd als thread-veilig [SWS_LOG_00265]. Interpretatie: Geregistreerde handlers worden vermoedelijk asynchroon aangeroepen zodra de DLT-backend toestandsveranderingen van de externe client vaststelt. Vraag Q-b78ef73772a658a2 (open)

De type-alias ConnectionStateHandler specificeert de signatuur voor callback-functies voor het monitoren van de verbindingsstatus in de module log [SWS_LOG_00265]. Deze is gedeclareerd in de namespace ara::log en vereist het insluiten van het headerbestand ara/log/logger.h [SWS_LOG_00265]. Als function wrapper std::function<void(ClientState)> ontvangt de callback-routine de opgetreden verbindingstoestand via de parameter van het type ClientState en levert deze geen retourwaarde op [SWS_LOG_00265].

Het gebruik vindt plaats via de registratiefunctie RegisterConnectionStateHandler [SWS_LOG_00205]. Voor de interactie en de levenscyclus van de handler gelden de volgende voorschriften:

• Tijdstip van aanroep: De geregistreerde callback-functie wordt telkens aangeroepen wanneer de verbindingsstatus van de client verandert [SWS_LOG_00205].
• Exclusiviteit: Er kan op elk moment slechts één enkele handler actief geregistreerd zijn [SWS_LOG_00205]. Als er al eerder een callback is geregistreerd, vervangt de nieuw meegegeven functie deze volledig, zodat voortaan uitsluitend de nieuwe handler wordt aangeroepen [SWS_LOG_00205].
• Exceptieveiligheid: De registratiefunctie RegisterConnectionStateHandler is gespecificeerd met noexcept, zodat de overdracht van de functie-callback exceptieveilig verloopt [SWS_LOG_00205].

Met betrekking tot gelijktijdigheid is het specificatie-element aangemerkt als thread-safe [SWS_LOG_00265]. Interpretatie: Aangezien statuswijzigingen door de logging-infrastructuur potentieel asynchroon worden gesignaleerd, moet de in de handler voorziene applicatielogica vermoedelijk re-entrant zijn ontworpen en geen blokkerende operaties uitvoeren om de communicatiecontext niet te belemmeren. Vraag Q-ca507d992cc31284 (open)

Gebruik

De functie CreateLogger in de namespace ara::log dient voor het aanmaken en registreren van een Logger-object, dat de betreffende context binnen het logging-framework beheert [SWS_LOG_00021]. Bij de aanroep worden de context-identificatie ctxId, de tekstuele beschrijving ctxDescription en het standaard-log-level ctxDefLogLevel meegegeven [SWS_LOG_00021]. Is er geen model beschikbaar, dan leidt het framework de uitvoer standaard om naar de console als sink [SWS_LOG_00021].

De functie retourneert een referentie Logger & naar de intern beheerde instantie. Het eigenaarschap (ownership) blijft daarbij volledig binnen het logging-framework [SWS_LOG_00021].

Gelijktijdigheid en uitvoeringsveiligheid

De interface is gedeclareerd als noexcept en zowel als uitzonderingsveilig (exception safe) als thread-veilig (thread-safe) gespecificeerd [SWS_LOG_00021]. Zij kan zodoende veilig vanuit meerdere gelijktijdige threads worden aangeroepen.

Interactie en alternatieven

Voor verschillende configuratiebenaderingen staan verwante interfaces ter beschikking:

• Een alternatieve overbelasting staat de instantiëring toe uitsluitend via ctxId en ctxDescription [SWS_LOG_00263], waarbij als standaard-log-level impliciet Warning wordt gebruikt [SWS_LOG_00021].
• Bovendien kan een Logger modelgebaseerd via een ara::core::InstanceSpecifier uit het manifest worden afgeleid [SWS_LOG_00256]. Daarbij controleert het platform op fouten zoals InstanceSpecifierMappingIntegrityViolation of PortInterfaceMappingViolation [SWS_LOG_00256].

De synchrone functie CreateLogger creëert respectievelijk levert een referentie naar een intern beheerd Logger-object gebaseerd op de modelgegevens van het manifest [SWS_LOG_00256]. Als aanroepparameter dient een referentie naar een ara::core::InstanceSpecifier, die het gewenste modelelement in de context van het lopende proces identificeert [SWS_LOG_00256].

De functie is gedeclareerd als noexcept, geldt als uitzonderingsveilig (exception safe) en is gespecificeerd als thread-veilig, zodat aanroepen re-entrant en gelijktijdig kunnen plaatsvinden [SWS_LOG_00256]. Voor foutieve configuraties of ongeldige modelcontexten definieert de specificatie meerdere schendingen (violations) [SWS_LOG_00256]:

• InstanceSpecifierMappingIntegrityViolation: Doet zich voor wanneer de InstanceSpecifier in de context van de executable niet kan worden opgelost of naar een ander element dan een PortPrototype verwijst [SWS_LOG_00256].
• PortInterfaceMappingViolation: Wordt geactiveerd indien het mapping-type niet overeenkomt met het verwachte type van de port-interface [SWS_LOG_00256].
• ProcessMappingViolation: Treedt in werking wanneer er weliswaar een passende InstanceRef bestaat, maar geen gemodelleerd proces bij het runtime-proces past [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation: Signaleert dat een constructor in het framework is aangeroepen met een identifier die al in dit proces wordt gebruikt [SWS_LOG_00256].

In vergelijking met de overbelastingen [SWS_LOG_00021] en [SWS_LOG_00263], die loggers programmatisch initialiseren via context-ID's en beschrijvingsstrings en bij gebrek aan een model standaard de console als sink gebruiken, vindt de configuratie hier volledig manifestgestuurd plaats. Bij alle varianten blijft het eigenaarschap van de instantie binnen het logging-framework [SWS_LOG_00263].

De functie CreateLogger in de namespace ara::log ([SWS_LOG_00263]) dient voor het aanmaken en registreren van een contextgebonden Logger-object binnen het logging-framework van AUTOSAR Adaptive.

Gebruik

Via het headerbestand ara/log/logger.h accepteert de functie de contextidentifier ctxId en de uitgebreide beschrijving ctxDescription telkens als type ara::core::StringView [SWS_LOG_00263]. Als retourwaarde levert de aanroep een referentie Logger & naar de intern beheerde instantie van het aangemaakte Logger-object op [SWS_LOG_00263]. Het eigendom (ownership) van deze instantie blijft permanent bij het logging-framework en wordt niet overgedragen aan de aanroeper [SWS_LOG_00263]. Indien er in het systeem geen model beschikbaar is, fungeert de console standaard als sink voor alle logging-uitvoer [SWS_LOG_00263].

Foutafhandeling en gelijktijdigheid

Voor de aanroep zijn geen specifieke foutcodes gedefinieerd en er worden geen C++-excepties geworpen, aangezien de functie met noexcept gespecificeerd is en als exceptieveilig (exception safe) is aangemerkt [SWS_LOG_00263]. Wat betreft gelijktijdigheid is CreateLogger thread-safe, zodat de functie zonder externe synchronisatie gelijktijdig vanuit meerdere threads kan worden aangeroepen [SWS_LOG_00263].

Samenspel

Het logging-framework biedt nauw verwante overbelastingen aan: naast deze signatuur met twee parameters maakt een overbelasting de aanvullende configuratie van een standaard-logniveau via ctxDefLogLevel mogelijk ([SWS_LOG_00021]). Een verdere signatuur maakt het aanmaken van een Logger-object via een ara::core::InstanceSpecifier rechtstreeks vanuit het manifest mogelijk ([SWS_LOG_00256]).

Gebruik

De functie ara::log::EngFloatMax() uit het headerbestand ara/log/logger.h creëert synchroon een instantie van het type Format [SWS_LOG_00220]. Het geretourneerde object bevat de formatteringsinstructie Fmt::kEngFloat voor de weergave van floating-pointgetallen in technische notatie en een precisie die toereikend is voor een volledige heen-en-terugconversie (“full round-trip safety”) [SWS_LOG_00220]. De functie verwacht geen parameters.

Foutafhandeling

De functie is voorzien van de specificator noexcept en gedefinieerd als exceptieveilig (exception safe) [SWS_LOG_00220]. Er bestaan geen specifieke foutcodes en er worden noch exceptions geworpen, noch fouten overgedragen aan diagnose- of foutmeldingsinstanties. De aanroep mislukt bij regulier gebruik niet.

Gelijktijdigheid en beperkingen

De specificatie markeert de functie als thread-safe (thread-safe) [SWS_LOG_00220]. Dankzij de markering als constexpr kan de aanroep al tijdens compileertijd worden geëvalueerd. Interpretatie: Aangezien de specificatie geen randvoorwaarden definieert en de functie toestandloos is, bestaan er vermoedelijk noch beperkingen wat betreft de aanroepcontext, noch afhankelijkheden van een eerdere initialisatie van de logging-infrastructuur. Vraag Q-90c67bfad5b19641 (open)

De hulpfunctie HexFloat dient voor het creëren van een formatteerobject voor drijvende-kommagetallen voor uitvoer in hexadecimaal formaat conform [SWS_LOG_00221]. Deze instantieert een object van het type Format dat is voorzien van de formatteeraanwijzing Fmt::kHexFloat en een vooraf opgegeven precisie.

Gebruik en parameters

De functie is beschikbaar in de namespace ara::log via de header #include "ara/log/logger.h" [SWS_LOG_00221]:

• Parameter: Als invoerparameter wordt precision van het type std::uint16_t doorgegeven, die de gewenste uitvoerprecisie vastlegt [SWS_LOG_00221].
• Retourwaarde: Een geïnitialiseerd Format-object met ingesteld Fmt::kHexFloat-voorvoegsel [SWS_LOG_00221].
• Uitvoering: Door de aanduiding als constexpr kan de constructie van de formatteeraanwijzing synchroon tijdens runtime of reeds tijdens compileertijd plaatsvinden [SWS_LOG_00221].

Foutafhandeling en gelijktijdigheid

De signatuur is gedeclareerd met noexcept en geldt als volledig uitzonderingsveilig (exception safe) [SWS_LOG_00221]. Er worden noch foutcodes noch specifieke foutmeldingen gegenereerd. De functie is gespecificeerd als thread-safe (thread-safe) en kan zonder synchronisatie-overhead parallel vanuit willekeurige contexten worden aangeroepen [SWS_LOG_00221].

De functie HexFloatMax in de namespace ara::log dient voor het creëren van een Format-instantie voor de geformatteerde uitvoer van floating-pointwaarden [SWS_LOG_00222]. Ze wordt beschikbaar gesteld via het headerbestand #include "ara/log/logger.h" en accepteert geen aanroepparameters [SWS_LOG_00222]. Als synchrone retourwaarde wordt een Format-instantie geleverd die is voorzien van de formatteringsinstructie Fmt::kHexFloat en een precisie bezit die een volledige round-trip-veiligheid garandeert [SWS_LOG_00222].

De signatuur is gedeclareerd als constexpr en noexcept [SWS_LOG_00222]. Dit staat evaluatie al tijdens compileertijd toe en garandeert dat er bij de uitvoering geen excepties kunnen optreden. Bijzondere fouttoestanden, foutcodes of mechanismen voor foutafhandeling zijn voor deze aanroep niet gespecificeerd, aangezien het creëren van het format-object altijd foutloos plaatsvindt.

Wat betreft de aanroepcontext en de gelijktijdigheid is de functie gespecificeerd als exceptieveilig (exception safe) en thread-safe (thread-safe) [SWS_LOG_00222]. Ze is niet onderhevig aan sequentiële aanroepbeperkingen en kan veilig en gelijktijdig vanuit willekeurige threads zonder aanvullende synchronisatie worden aangeroepen.

Gebruik

De functie ara::log::Oct() dient als hulpfunctie voor het aanmaken van een opmaakobject voor logging-uitvoer in het octale stelsel [SWS_LOG_00213]. Deze accepteert geen parameters en retourneert synchroon een object van het type Format, dat is geconfigureerd met de opmaakaanwijzing Fmt::kOct en een standaardprecisie [SWS_LOG_00213]. Aangezien de functie is gedeclareerd als constexpr, kan de instantiëring al tijdens compileertijd plaatsvinden. Interpretatie: Het geretourneerde Format-object is vermoedelijk primair bedoeld voor het regelen van de opmaak van gehele getallen in logstreams. Vraag Q-3f4fe5ac42de16cb (open)

Foutafhandeling

De functie garandeert uitzonderingsveiligheid (exception safe) en is expliciet gedeclareerd als noexcept [SWS_LOG_00213]. Het optreden van runtime-fouten of het werpen van excepties is uitgesloten. Er bestaan geen specifieke foutcodes en er vinden geen meldingen aan DET of DEM plaats.

Gelijktijdigheid en beperkingen

De aanroep van Oct() is onbeperkt thread-veilig (thread-safe) [SWS_LOG_00213]. Aangezien er geen gedeelde toestanden worden gewijzigd, is de functie niet onderhevig aan beperkingen wat betreft re-entrantie of aanroepcontext en kan deze parallel vanuit meerdere threads worden aangeroepen.

Samenspel

De functie is gedefinieerd in de namespace ara::log en wordt beschikbaar gesteld via het headerbestand #include "ara/log/logger.h" [SWS_LOG_00213]. Naast deze parameterloze variant bestaat de overload Oct(std::uint16_t precision), waarmee een afwijkende nauwkeurigheid kan worden vastgelegd [SWS_LOG_00214].

Gebruik

De hulpfunctie ara::log::Oct wordt via het headerbestand #include "ara/log/logger.h" in de namespace ara::log beschikbaar gesteld [SWS_LOG_00214]. Deze dient ertoe een instantie van het type Format met de formatteeraanwijzing Fmt::kOct en een vooraf opgegeven precisie te creëren [SWS_LOG_00214]. Als invoerparameter accepteert de functie de niet-ondertekende 16-bits geheelgetalwaarde precision, die de toe te passen precisie vastlegt [SWS_LOG_00214]. De functie werkt synchroon en retourneert de gecreëerde Format-instantie direct [SWS_LOG_00214].

Foutafhandeling en gelijktijdigheid

De functie is gedeclareerd als noexcept en uitdrukkelijk gespecificeerd als uitzonderingsveilig (exception safe) [SWS_LOG_00214]. Er bestaan noch specifieke foutcodes noch meldingen via DET of DEM bij fouten. Met betrekking tot de aanroepcontext en gelijktijdigheid is de functie geclassificeerd als thread-safe (thread-safe) [SWS_LOG_00214]. Aangezien deze bovendien is gedefinieerd als constexpr, kan het aanmaken van de formatteerinstructie reeds tijdens compileertijd plaatsvinden [SWS_LOG_00214].

Samenspel

Binnen de module log vult de functie de verwante overload Oct() aan [SWS_LOG_00213]. Terwijl de parameterloze variant een Format-instantie met standaardprecisie (default precision) construeert [SWS_LOG_00213], maakt de onderhavige functie de expliciete configuratie mogelijk van een gebruikersspecifieke precisie voor de octale formattering [SWS_LOG_00214].

De functie RegisterConnectionStateHandler in de namespace ara::log dient ertoe een callback-functie aan applicatiezijde te registreren die bij elke wijziging van de verbindingsstatus wordt aangeroepen [SWS_LOG_00205]. Ze is gedeclareerd in de header ara/log/logger.h [SWS_LOG_00205]. Als parameter wordt een functie-object callback van het type ConnectionStateHandler doorgegeven [SWS_LOG_00205], dat als type-alias voor std::function<void(ClientState)> is gespecificeerd [SWS_LOG_00265]. Er is geen retourwaarde aanwezig (void) [SWS_LOG_00205].

Wat betreft levenscyclus en volgorde is vastgelegd dat op elk moment slechts één enkele status-handler geïnstalleerd kan zijn [SWS_LOG_00205]. Als er al eerder een callback-functie is geregistreerd, overschrijft elke nieuwe aanroep de bestaande instantie volledig, zodat vanaf dat moment uitsluitend de als laatste doorgegeven handler wordt uitgevoerd [SWS_LOG_00205].

De functie is gedeclareerd met noexcept en gespecificeerd als uitzonderingsveilig („exception safe”) [SWS_LOG_00205]. Specifieke foutcodes, foutwaarden of notificaties aan fout- of diagnosemonitors zijn in de specificatie niet gedefinieerd [SWS_LOG_00205].

Wat betreft gelijktijdigheid is RegisterConnectionStateHandler uitdrukkelijk geclassificeerd als niet-thread-safe („not thread-safe”) [SWS_LOG_00205]. De registratie mag daarom niet onbeschermd gelijktijdig vanuit meerdere threads worden aangeroepen en dient bij voorkeur tijdens de initialisatiefase plaats te vinden. Daarentegen is de type-alias ConnectionStateHandler gespecificeerd als thread-safe [SWS_LOG_00265]. Interpretatie: hieruit volgt vermoedelijk dat de geregistreerde callback door de interne logging-runtimeomgeving potentieel vanuit gelijktijdige contexten bij statusovergangen kan worden aangeroepen. Vraag Q-59eae7980ba48666 (open)