klasse ara::per::SharedHandle

De templateklasse ara::per::SharedHandle dient als smart-pointer-abstractie voor bestands- en sleutel-waarde-opslagen om thread-safe toegang over threadgrenzen heen mogelijk te maken. Na ontvangst via factory-functies moet de geldigheidstoestand van de handle via operator bool() [SWS_PER_00398] worden gecontroleerd, omdat het aanroepen van andere operators op een lege of door move-operaties geïnvalideerde handle tot ongedefinieerd gedrag leidt. Terwijl het derefereren naar het ingekapselde object thread-safe is, vereisen toewijzingen en de vernietiging van de handle [SWS_PER_00568] op dezelfde instantie externe synchronisatie.

meer ›

Context

De templateklasse ara::per::SharedHandle vormt in de module per (Persistency) van het AUTOSAR Adaptive Platform een smart-pointer-abstractie voor persistente opslagbronnen. Deze dient als gestandaardiseerd retourtype van de factory-functies OpenFileStorage() en OpenKeyValueStorage(). De hoofdverantwoordelijkheid van de klasse is het coördineren van de toegang tot bestands- en sleutel-waarde-opslagen over threadgrenzen heen en het bieden van de vereiste inkapseling om een thread-safe implementatie van de routines voor het openen van en toegang krijgen tot opslag mogelijk te maken. Interactiepartners zijn applicatie-threads, het persistentiebeheer en de telkens ingekapselde opslagbron T.

Levenscyclus

Een SharedHandle ontstaat typisch bij het openen van een opslaginstantie via de factory-interfaces van per. Via de copy constructor [SWS_PER_00369] en de copy assignment operator [SWS_PER_00370] kan de handle worden gedupliceerd, waardoor meerdere handle-instanties gedeelde toegang tot hetzelfde doelobject krijgen. Wordt een handle overgedragen via move constructor [SWS_PER_00367] of move assignment [SWS_PER_00368], dan gaat de bron-handle over naar een geïnvalideerde toestand en mag deze niet meer worden gebruikt voor opslagtoegang.

De actuele status van de handle wordt bepaald door de expliciete conversie-operator operator bool() [SWS_PER_00398]: deze levert true op als een geldige opslaginstantie wordt gerefereerd, en false als de handle leeg is. De vrijgave van de handle-resources vindt plaats via de destructor ~SharedHandle() [SWS_PER_00568]. Interpretatie: de onderliggende opslagbron wordt vermoedelijk vrijgegeven zodra de laatste refererende SharedHandle wordt vernietigd. Vraag Q-00a1798cf43e0ee6 (open)

Wat betreft concurrency zijn de toegangen tot de ingekapselde resource via operator* ([SWS_PER_00402], [SWS_PER_00403]) en operator-> ([SWS_PER_00363], [SWS_PER_00364]) evenals het opvragen van de status via operator bool() [SWS_PER_00398] thread-safe. Toewijzingsbewerkingen op dezelfde handle ([SWS_PER_00368], [SWS_PER_00370]) en de destructie daarvan [SWS_PER_00568] zijn daarentegen niet thread-safe en vereisen bij gedeeld gebruik van de handle externe synchronisatie.

Toestandsdiagram: levenscyclus en toestandsovergangen van ara::per::SharedHandle tussen geldige en lege toestand. Bronnen: [SWS_PER_00367], [SWS_PER_00368], [SWS_PER_00369], [SWS_PER_00370], [SWS_PER_00398], [SWS_PER_00568]

Gebruikspad

Het typische gebruik van ara::per::SharedHandle omvat het gecontroleerd verkrijgen, valideren en benaderen van opslagstructuren:

1. Verkrijgen van de handle: De applicatie roept OpenFileStorage() of OpenKeyValueStorage() aan en ontvangt een SharedHandle<T>.
2. Geldigheidscontrole: Voorafgaand aan elke toegang controleert de applicatie de toestand van de handle via operator bool() [SWS_PER_00398].
3. Resourcetoegang: Het aanroepen van opslagfuncties vindt plaats door dereferentie via operator-> ([SWS_PER_00363], [SWS_PER_00364]) of operator* ([SWS_PER_00402], [SWS_PER_00403]).
4. Doorgifte: De handle kan desgewenst aan andere threads worden overgedragen via een kopie ([SWS_PER_00369], [SWS_PER_00370]) of via move ([SWS_PER_00367], [SWS_PER_00368]).
5. Einde van de levenscyclus: Bij het verlaten van de scope ruimt de destructor [SWS_PER_00568] de handle op.

Sequentiediagram: verloop van verkrijging, geldigheidscontrole, methode-aanroep en opruiming van een SharedHandle. Bronnen: [SWS_PER_00363], [SWS_PER_00398], [SWS_PER_00568]

Foutscenario's

Kritieke fouttoestanden treden primair op bij niet-toegestane bewerkingen op lege of geïnvalideerde handles. Volgens [SWS_PER_00398] leidt het aanroepen van willekeurige operators behalve operator bool() op een lege handle direct tot ongedefinieerd gedrag (Undefined Behavior). Dit betreft met name bron-handles na een move-constructie [SWS_PER_00367] of een move-toewijzing [SWS_PER_00368], aangezien deze worden geïnvalideerd en niet verder mogen worden gebruikt.

Om ongedefinieerd gedrag te voorkomen, vereist de specificatie bindend dat de handle-toestand via operator bool() wordt gecontroleerd alvorens verdere operators ([SWS_PER_00367], [SWS_PER_00368]) aan te roepen. Alle constructors, assignment operators, toegangsoperators en de destructor zijn gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig („exception safe”) ([SWS_PER_00367], [SWS_PER_00368], [SWS_PER_00369], [SWS_PER_00370], [SWS_PER_00363], [SWS_PER_00364], [SWS_PER_00402], [SWS_PER_00403], [SWS_PER_00398], [SWS_PER_00568]). Een ongeldige toestand triggert daarom geen exceptie, maar moet door de aanroeper verplicht worden afgevangen via de retourwaarde van operator bool().