klasse ara::per::KeyValueStorage

Gebruik en semantiek

De synchrone elementfunctie DiscardPendingChanges van de klasse ara::per::KeyValueStorage ([SWS_PER_00365]) wordt beschikbaar gesteld via de header ara/per/key_value_storage.h. Zij neemt geen parameters aan en levert een ara::core::Result<void> op. Haar doel is het verwerpen van alle openstaande wijzigingen aan de Key-Value-Storage-instantie die sinds de laatste aanroep van SyncToStorage of sinds het openen via OpenKeyValueStorage() zijn ontstaan [SWS_PER_00365].

Interactie en transactiegedrag

Schrijfbewerkingen zoals SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047] en RemoveAllKeys [SWS_PER_00048] zijn onderworpen aan transactiesemantiek. De wijzigingen daarvan worden pas door de aanroep van SyncToStorage permanent naar het fysieke opslagmedium geschreven [SWS_PER_00049]. Door DiscardPendingChanges worden deze niet-bewaarde modificaties teruggedraaid, zodat ook opvragingen via GetCurrentValueSize weer de eerdere transactionele begintoestand weerspiegelen [SWS_PER_00554].

Foutafhandeling en gelijktijdigheid

In geval van een fout bevat het resultaat een fabrikantspecifieke fout of een foutcode uit PerErrc met gedefinieerde rollback-semantiek [SWS_PER_00365]:

• PerErrc::kIllegalWriteAccess: wanneer de storage schrijfbeveiligd is of bij een write-only-once-configuratie de sleutel reeds bestaat.
• PerErrc::kPhysicalStorageFailure: wanneer de toegang tot het fysieke opslagmedium mislukt.
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed of PerErrc::kAuthenticationFailed: bij integriteitsverlies, validatiefouten, ontsleutelingsfouten of een mislukte MAC-controle.

De methode is gedeclareerd als noexcept, exceptieveilig (exception safe) en thread-veilig (thread-safe) [SWS_PER_00365]. De uitvoering kan echter worden vertraagd als er parallel in andere threads aanroepen van SyncToStorage, SetValue, RemoveKey, RemoveAllKeys, ResetKey of RecoverKey actief zijn [SWS_PER_00365] [SWS_PER_00426] [SWS_PER_00427].

De synchrone methode KeyExists van de klasse ara::per::KeyValueStorage controleert of een bepaald sleutel-waardepaar aanwezig is in de opslag [SWS_PER_00043]. Als invoerparameter wordt de te controleren sleutel key van het type ara::core::StringView doorgegeven [SWS_PER_00043]. De retourwaarde is een ara::core::Result<bool> die true bevat als de sleutel kon worden gelokaliseerd, en anders false [SWS_PER_00043]. De functie is gedeclareerd als const en noexcept en is uitzonderingsveilig (exception safe) [SWS_PER_00043].

Wat betreft semantiek en gelijktijdigheid werkt KeyExists transactiegebaseerd: deze weerspiegelt de actuele toestand van de transactie en niet noodzakelijkerwijs de fysieke opslag [SWS_PER_00043]. De uitvoering is weliswaar thread-veilig (thread-safe), maar het geleverde resultaat is alleen nauwkeurig wanneer er niet gelijktijdig sleutel-waardeparen worden toegevoegd of verwijderd [SWS_PER_00043]. Wordt bijvoorbeeld direct na de teruggave van true het paar in een andere thread verwijderd, dan verliest het resultaat zijn geldigheid [SWS_PER_00043].

In geval van een fout bevat de Result een specifieke foutcode [SWS_PER_00043]:

• StorageFailure: Fout bij toegang tot de fysieke opslag [SWS_PER_00043].
• PerErrc::kIntegrityCorrupted: Opgeslagen gegevens kunnen vanwege geschonden structurele integriteit niet worden gelezen [SWS_PER_00043].
• PerErrc::kValidationFailed: De geldigheid van de opgeslagen gegevens kan niet worden gewaarborgd [SWS_PER_00043].
• PerErrc::kEncryptionFailed: Ontsleuteling van de gegevens mislukt [SWS_PER_00043].
• PerErrc::kAuthenticationFailed: Verificatie van de MAC mislukt [SWS_PER_00043].
• Fabrikantspecifieke fouten (vendor specific error) kunnen eveneens worden geretourneerd [SWS_PER_00043].

De synchrone methode RecoverKey van de klasse ara::per::KeyValueStorage dient voor het best-effort-herstel van een afzonderlijk sleutel-waardepaar wanneer interne redundantiecontroles mislukken [SWS_PER_00427]. Deze neemt de identifier van de sleutel via de parameter key als ara::core::StringView in ontvangst en meldt het succes of de fout terug via een ara::core::Result<void> [SWS_PER_00427]. Na het herstel kan het paar verouderde inhoud of initiële waarden vertonen, of geheel verloren zijn gegaan [SWS_PER_00427].

Treedt er een fout op, dan levert het resultaat specifieke foutcodes uit PerErrc of fabrikantspecifieke fouten [SWS_PER_00427]:

• kKeyNotFound: De opgegeven sleutel bestaat niet in de storage [SWS_PER_00427].
• kIllegalWriteAccess: de opslag is als alleen-lezen (read-only) geconfigureerd [SWS_PER_00427].
• kPhysicalStorageFailure: De toegang tot het fysieke geheugen is mislukt [SWS_PER_00427].
• kIntegrityCorrupted: structurele integriteitsschade verhindert het schrijven van gegevens [SWS_PER_00427].
• kEncryptionFailed resp. kAuthenticationFailed: de ver- of ontsleuteling of de MAC-validatie mislukt [SWS_PER_00427].
• kOutOfStorageSpace resp. kQuotaExceeded: de beschikbare fysieke opslagruimte is niet toereikend of de geconfigureerde maximale omvang wordt overschreden [SWS_PER_00427].

De operatie is gespecificeerd als thread-safe en exception-safe [SWS_PER_00427]. Aanroepen kunnen echter worden vertraagd wanneer parallel opslagbrede acties zoals RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049] of DiscardPendingChanges [SWS_PER_00365] worden uitgevoerd [SWS_PER_00427]. Eveneens leiden gelijktijdige aanroepen van SetValue [SWS_PER_00046], GetValue [SWS_PER_00044], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426] of opnieuw RecoverKey voor dezelfde sleutel tot vertragingen [SWS_PER_00427]. In tegenstelling tot ResetKey [SWS_PER_00426], die de invoer terugzet naar de uitleveringstoestand, probeert RecoverKey gegevens te redden [SWS_PER_00427].

Gebruik en transactiesemantiek

De methode RemoveAllKeys van de klasse ara::per::KeyValueStorage verwijdert alle sleutel-waardeparen en de bijbehorende inhoud uit het geheugen [SWS_PER_00048]. De functie wordt synchroon aangeroepen, heeft geen overdrachtsparameters en is gespecificeerd met noexcept [SWS_PER_00048]. De bewerking is onderworpen aan een transactiesemantiek: Het wissen van alle sleutels wordt pas permanent in het fysieke geheugen van kracht, zodra aansluitend SyncToStorage [SWS_PER_00049] wordt aangeroepen [SWS_PER_00048]. Binnen de lopende transactie weerspiegelen leesbewerkingen zoals GetValue [SWS_PER_00332] of grootte-opvragingen via GetCurrentValueSize [SWS_PER_00554] onmiddellijk de geleegde toestand [SWS_PER_00044].

Foutafhandeling

Als retourwaarde dient ara::core::Result<void> [SWS_PER_00048]. Treedt er een fout op, dan wordt een rollback-semantiek toegepast [SWS_PER_00048]. Tot de mogelijke fouten behoren:

• toegangsschending bij een als alleen-lezen geconfigureerd geheugen (Interpretation: dit zal vermoedelijk overeenkomen met de foutcode PerErrc::kIllegalWrite) [SWS_PER_00048], Vraag Q-a820d779e19ac5c9 (open)
• PerErrc::kPhysicalStorageFailure bij fouten tijdens de toegang tot het fysieke opslagmedium [SWS_PER_00048],
• PerErrc::kIntegrityCorrupted bij beschadigde structurele gegevensintegriteit [SWS_PER_00048],
• PerErrc::kEncryptionFailed evenals PerErrc::kAuthenticationFailed bij het mislukken van de ver-/ontsleuteling of de MAC-verificatie [SWS_PER_00048] evenals fabrikantspecifieke fouten.

Gelijktijdigheid en wisselwerking

De methode is geclassificeerd als thread-safe en exception safe [SWS_PER_00048]. De uitvoering kan echter worden vertraagd als in een andere thread gelijktijdig aanroepen van RemoveAllKeys, SyncToStorage [SWS_PER_00049], SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426] of RecoverKey [SWS_PER_00427] actief zijn [SWS_PER_00048].

De synchrone memberfunctie RemoveKey van de klasse ara::per::KeyValueStorage dient voor het verwijderen van een sleutel en de bijbehorende waarde uit de Key-Value Storage [SWS_PER_00047]. Zij neemt de identifier van de te verwijderen sleutel als ara::core::StringView via de parameter key in ontvangst en levert een ara::core::Result<void> op [SWS_PER_00047].

De bewerking is onderworpen aan transactiesemantiek: wijzigingen worden niet direct persistent in het fysieke geheugen, maar worden pas van kracht wanneer expliciet SyncToStorage wordt aangeroepen [SWS_PER_00047], wat gewijzigde sleutel-waarde-paren synchroniseert [SWS_PER_00049]. Openstaande wijzigingen kunnen vóór de synchronisatie met DiscardPendingChanges worden verworpen [SWS_PER_00365]. Leesbewerkingen zoals GetValue [SWS_PER_00044], [SWS_PER_00332] of GetCurrentValueSize [SWS_PER_00554] werken eveneens op de transactietoestand en weerspiegelen de verwijdering onmiddellijk.

Wat betreft gelijktijdigheid is de methode gespecificeerd als thread-veilig (thread-safe) en exceptieveilig (exception safe) [SWS_PER_00047]. Een aanroep kan worden vertraagd als parallel in een andere thread RemoveAllKeys, SyncToStorage of DiscardPendingChanges worden uitgevoerd, of als gelijktijdig bewerkingen zoals SetValue, GetValue, GetCurrentValueSize, RemoveKey, RecoverKey of ResetKey toegang hebben tot hetzelfde sleutel-waarde-paar [SWS_PER_00047].

Als er bij de uitvoering een fout optreedt, treedt rollback-semantiek in werking en bevat het geretourneerde Result-object een foutcode [SWS_PER_00047]:

• PerErrc::kKeyNotFound: De opgegeven sleutel bestaat niet in de storage [SWS_PER_00047].
• PerErrc::kIllegalWriteAccess: De Key-Value Storage is geconfigureerd als alleen-lezen (read-only) [SWS_PER_00047].
• PerErrc::kPhysicalStorageFailure: De toegang tot het fysieke opslagmedium is mislukt [SWS_PER_00047].
• PerErrc::kIntegrityCorrupted: Het schrijven mislukt vanwege beschadigde structurele integriteit [SWS_PER_00047].
• PerErrc::kEncryptionFailed respectievelijk PerErrc::kAuthenticationFailed: De ver- respectievelijk ontsleuteling mislukt of de MAC-berekening/-controle is foutief [SWS_PER_00047].

Gebruik

De synchrone methode ResetKey zet een afzonderlijk sleutel-waardepaar in een instantie van ara::per::KeyValueStorage terug naar de initiële waarde ervan [SWS_PER_00426]. Als parameter wordt de identifier key als ara::core::StringView doorgegeven [SWS_PER_00426]. Indien de sleutel momenteel niet in de opslag aanwezig is, wordt deze nieuw aangemaakt. In beide gevallen komt de toestand van de invoer vervolgens overeen met die van een nieuwe installatie vanuit de actuele Target Configuration [SWS_PER_00426]. De functie is gedeclareerd als noexcept en retourneert een ara::core::Result<void> [SWS_PER_00426].

Foutafhandeling

Treedt er bij de uitvoering een fout op, dan levert het Result-object een overeenkomstige foutcode [SWS_PER_00426]:

• PerErrc::kInitValueNotAvailable: wanneer noch in het Application Design noch in de Target Configuration een initiële waarde voor de sleutel is gedefinieerd (rollback-semantiek) [SWS_PER_00426].
• kIllegalWrite: wanneer de Key-Value Storage als alleen-lezen (read-only) is geconfigureerd [SWS_PER_00426].
• PerErrc::kPhysicalStorageFailure of PerErrc::kOutOfStorageSpace: bij fysieke opslagtoegangsfouten of onvoldoende opslagruimte (zonder rollback-semantiek) [SWS_PER_00426].
• PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed of PerErrc::kQuotaExceeded: bij integriteitsschendingen, crypto- en authenticatiefouten of overschrijding van de geconfigureerde AllowedSize (telkens met rollback-semantiek) [SWS_PER_00426].

Gelijktijdigheid en wisselwerking

De functie is thread-safe en exception-safe [SWS_PER_00426]. De aanroep kan echter worden vertraagd wanneer parallel vanuit een andere thread opslagbrede operaties zoals RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049] of DiscardPendingChanges [SWS_PER_00365] actief zijn. Eveneens leiden gelijktijdige toegangen tot dezelfde sleutel via SetValue [SWS_PER_00046], GetValue [SWS_PER_00044] [SWS_PER_00332], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], RecoverKey [SWS_PER_00427] of een verdere ResetKey tot vertragingen [SWS_PER_00426].

De synchrone methode SyncToStorage van de klasse ara::per::KeyValueStorage schrijft gewijzigde sleutel-waarde-paren vanuit de geheugenbuffer permanent naar de fysieke opslag [SWS_PER_00049]. Zij neemt geen parameters aan en retourneert een ara::core::Result<void>, is gedeclareerd als noexcept en gespecificeerd als exceptieveilig en thread-safe [SWS_PER_00049].

Interactie en transactiesemantiek

Modificerende bewerkingen zoals SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047] en RemoveAllKeys [SWS_PER_00048] maken gebruik van transactiesemantiek. Hun wijzigingen worden pas van kracht bij de aanroep van SyncToStorage [SWS_PER_00046]. Indien openstaande modificaties vóór het schrijven moeten worden verworpen, kan als alternatief DiscardPendingChanges worden aangeroepen [SWS_PER_00365].

Concurrency

Hoewel de functie thread-safe is, kan de uitvoering worden vertraagd als er parallel in een andere thread bewerkingen zoals SetValue, RemoveKey, RemoveAllKeys, DiscardPendingChanges, RecoverKey of ResetKey actief zijn [SWS_PER_00049].

Foutafhandeling

Als de synchronisatie mislukt, levert het Result een foutcode op [SWS_PER_00049]:

• Fouten met rollback-semantiek (wijzigingen worden teruggedraaid): PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed, PerErrc::kQuotaExceeded en PerErrc::kIllegalWrite [SWS_PER_00049].
• Fouten zonder rollback-semantiek: PerErrc::kPhysicalStorageFailure bij fysieke toegangsfouten en PerErrc::kOutOfStorageSpace bij onvoldoende opslagruimte [SWS_PER_00049].
• Configuratiefouten: foutcode Access wanneer de storage is geconfigureerd als read-only of bij write-only-once wanneer de sleutel reeds bestaat [SWS_PER_00049].