klasse ara::log::LogStream

De klasse ara::log::LogStream representeert een formatteerbaar logboekbericht waarvan de interne buffer via streamoperatoren stapsgewijs met gegevens en metagegevens wordt gevuld. Instanties worden typisch tijdelijk via logging-methoden verkregen en sturen de vastgelegde inhoud bij het verlaten van de scope via de destructor automatisch door naar het logging-framework [SWS_LOG_00262]. Voor meerregelige of hergebruikte berichten kan het doorsturen expliciet worden geactiveerd via Flush() [SWS_LOG_00039]. Als centrale randvoorwaarde is de klasse niet thread-safe en voorkomt deze kopieerbewerkingen volledig.

meer ›

Context

De klasse ara::log::LogStream representeert een formatteerbaar logboekbericht in het adaptieve logging-subsysteem. Deze biedt een berichtgebaseerde bufferinterface die via overbelaste streamoperatoren het stapsgewijs toevoegen van heterogene payload aan een interne buffer mogelijk maakt.

In het reguliere toepassingsgeval interageren applicatieprocessen niet rechtstreeks via een expliciete instantiëring met LogStream. In plaats daarvan stelt de hoofd-logging-API (bijvoorbeeld via logging-methoden zoals LogDebug()) tijdelijke instanties van deze klasse beschikbaar, die reeds met het vereiste severity-niveau zijn geïnitialiseerd. De enige beoogde reden voor het vasthouden van een LogStream-object buiten de standaard one-statement-scope is het samenstellen van logboekberichten over meerdere regels code heen. Zodra het object zijn scope verlaat of expliciet wordt geleegd, wordt de bufferinhoud overgedragen aan het logging-framework voor verdere verwerking.

Contextdiagram: Samenspel tussen applicatieproces, logging-API, LogStream en logging-framework. Bronnen: [SWS_LOG_00039], [SWS_LOG_00262]

Levenscyclus

De creatie van LogStream-instanties vindt primair plaats als tijdelijk object via factory-methoden van de hoofd-logging-API. Voor een efficiënte beschikbaarstelling declareert de klasse een move-constructor als noexcept [SWS_LOG_00176]. Deze move-constructor wordt typisch louter gedeclareerd en niet gedefinieerd, wat C++14-conforme compilers toestaat om Return Value Optimization (RVO) te benutten bij het retourneren uit factory-functies [SWS_LOG_00176]. Duplicatie of verplaatsingstoewijzing van instanties is strikt uitgesloten: de copy-constructor [SWS_LOG_00174], de copy-assignment-operator [SWS_LOG_00175] en de move-assignment-operator [SWS_LOG_00177] zijn verwijderd (=delete).

Het einde van de levensduur wordt beheerd door de destructor ~LogStream() [SWS_LOG_00262]. Verlaat het object zijn scope (bijvoorbeeld aan het einde van een functieblok of een statement), dan zorgt de destructor er intern voor dat de bufferinhoud voor verwerking wordt doorgestuurd naar het logging-framework [SWS_LOG_00039], [SWS_LOG_00262].

Wordt een LogStream-instantie in dezelfde scope hergebruikt voor meerdere opeenvolgende berichten, dan moet de lidfunctie Flush() worden aangeroepen [SWS_LOG_00039]. Belangrijk hierbij is dat Flush() de buffer niet leegt, maar de actuele gegevens naar het logging-framework verzendt en onmiddellijk een nieuwe berichtenstroom initieert [SWS_LOG_00039].

Wat betreft concurrency zijn alle lidfuncties als niet thread-safe gespecificeerd ([SWS_LOG_00039], [SWS_LOG_00040], [SWS_LOG_00129]). Een LogStream-exemplaar mag daarom niet zonder externe synchronisatie door meerdere threads parallel worden gebruikt.

Gebruikspad

Een typische logging-cyclus omvat de volgende fasen:

1. Stream-beschikbaarstelling: Het applicatieproces roept een logging-methode aan, die een tijdelijke LogStream-instantie creëert en via RVO retourneert [SWS_LOG_00176].
2. Metagegevensverrijking: Vóór of tijdens de gegevensinvoer kunnen optionele attributen via method chaining worden toegevoegd, waaronder broncodelocaties via WithLocation(file, line) [SWS_LOG_00129], tags via WithTag(tag) [SWS_LOG_00132] of vertrouwelijkheidsniveaus via WithPrivacy(value) [SWS_LOG_00258]. Elk van deze methoden retourneert een referentie naar *this.
3. Gegevens vullen: Via overbelaste operatoren operator<< wordt payload naar de interne buffer geschreven. De interface ondersteunt standaardtypen zoals booleaanse waarden [SWS_LOG_00040], gehele getallen van verschillende breedtes [SWS_LOG_00041], [SWS_LOG_00044], drijvende-kommagetallen [SWS_LOG_00049], tekenreeksen en string views [SWS_LOG_00051], [SWS_LOG_00062], byte-sequenties via core::Span<const core::Byte> [SWS_LOG_00128] evenals gestructureerde argumenten via Argument<T> [SWS_LOG_00203]. Daarnaast kan de operator worden uitgebreid voor gebruikersgedefinieerde typen.
4. Overdracht aan het framework: Bij het verlaten van de scope stuurt de destructor het bericht door [SWS_LOG_00262]. Moet de instantie behouden blijven voor verdere berichten, dan wordt Flush() expliciet aangeroepen [SWS_LOG_00039].

Sequentiediagram: Verloop van een logging-operatie van stream-creatie via metagegevens- en gegevensinvoer tot aan verzending via scope-einde of Flush(). Bronnen: [SWS_LOG_00039], [SWS_LOG_00040], [SWS_LOG_00129], [SWS_LOG_00176], [SWS_LOG_00262]

Foutscenario's

De klasse volgt een strikt no-exception-ontwerp. Alle lidfuncties, inclusief de streamoperatoren ([SWS_LOG_00040] tot [SWS_LOG_00051], [SWS_LOG_00062], [SWS_LOG_00128], [SWS_LOG_00203]), WithLocation() [SWS_LOG_00129], WithTag() [SWS_LOG_00132], WithPrivacy() [SWS_LOG_00258], Flush() [SWS_LOG_00039] en de destructor [SWS_LOG_00262], zijn gedeclareerd als noexcept en zijn exceptieveilig (“exception safe”).

Foutcondities en gebruiksrisico's beperken zich tot de volgende scenario's:

• Typefout bij WithPrivacy: De template WithPrivacy<T> vereist dwingend dat T een geheel getaltype of een opsommingstype is. Wordt de functie met een afwijkend type geïnstantieerd, dan is het programma gebrekkig (ill-formed) en leidt dit tot een compilatiefout [SWS_LOG_00258]. Bovendien worden alleen de laagste 8 bits van de overgedragen waarde gebruikt; hogere bits worden genegeerd [SWS_LOG_00258].
• Ontbrekende thread-safety: Aangezien LogStream als niet thread-safe is gedefinieerd ([SWS_LOG_00039], [SWS_LOG_00040]), leiden concurrerende lees- of schrijfbewerkingen op dezelfde instantie zonder externe synchronisatie vermoedelijk tot inconsistentie van gegevens of bufferbeschadiging (interpretatie). Vraag Q-30a5037999c96fa2 (open)
• Bufferoverdracht bij Flush: Aangezien Flush() de buffer niet fysiek leegt, maar louter de actuele inhoud overdraagt aan het logging-framework [SWS_LOG_00039], moet bij hergebruik in ogenschouw worden genomen dat semantisch een nieuw bericht wordt gestart.