class ara::per::KeyValueStorage

Usage and Semantics

The synchronous member function DiscardPendingChanges of class ara::per::KeyValueStorage ([SWS_PER_00365]) is provided via header ara/per/key_value_storage.h. It takes no parameters and returns a ara::core::Result<void>. Its purpose is to discard all pending changes to the key-value storage instance that have accumulated since the last call to SyncToStorage or since opening via OpenKeyValueStorage() [SWS_PER_00365].

Interaction and Transaction Behavior

Writing operations such as SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047], and RemoveAllKeys [SWS_PER_00048] are subject to transaction semantics. Their changes are written permanently to the physical storage medium only upon calling SyncToStorage [SWS_PER_00049]. Through DiscardPendingChanges, these unsaved modifications are rolled back, so that queries via GetCurrentValueSize also reflect the previous transactional initial state again [SWS_PER_00554].

Error Handling and Concurrency

In case of an error, the result contains a vendor-specific error or an error code from PerErrc with defined rollback semantics [SWS_PER_00365]:

• PerErrc::kIllegalWriteAccess: if the storage is read-only or, in a write-only-once configuration, the key already exists.
• PerErrc::kPhysicalStorageFailure: if access to the physical storage medium fails.
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed: in case of loss of integrity, validation errors, decryption errors, or failed MAC verification.

The method is declared as noexcept, exception-safe, and thread-safe [SWS_PER_00365]. However, execution may be delayed if calls to SyncToStorage, SetValue, RemoveKey, RemoveAllKeys, ResetKey, or RecoverKey are active in parallel in other threads [SWS_PER_00365] [SWS_PER_00426] [SWS_PER_00427].

The synchronous method KeyExists of class ara::per::KeyValueStorage checks whether a specific key-value pair exists in storage [SWS_PER_00043]. The key to be checked, key of type ara::core::StringView, is passed as the input parameter [SWS_PER_00043]. The return value is a ara::core::Result<bool> containing true if the key could be located, and false otherwise [SWS_PER_00043]. The function is declared as const and noexcept and is exception-safe (exception safe) [SWS_PER_00043].

Regarding semantics and concurrency, KeyExists operates in a transaction-based manner: It reflects the current state of the transaction and not necessarily the physical storage [SWS_PER_00043]. Although execution is thread-safe (thread-safe), the returned result is accurate only as long as key-value pairs are not simultaneously added or removed [SWS_PER_00043]. If, for example, the pair is removed in another thread immediately after true is returned, the result loses its validity [SWS_PER_00043].

In case of an error, Result contains a specific error code [SWS_PER_00043]:

• StorageFailure: Error accessing physical storage [SWS_PER_00043].
• PerErrc::kIntegrityCorrupted: Stored data cannot be read due to violated structural integrity [SWS_PER_00043].
• PerErrc::kValidationFailed: The validity of the stored data cannot be ensured [SWS_PER_00043].
• PerErrc::kEncryptionFailed: Decryption of data fails [SWS_PER_00043].
• PerErrc::kAuthenticationFailed: Verification of the MAC fails [SWS_PER_00043].
• Vendor-specific errors (vendor specific error) can also be returned [SWS_PER_00043].

The synchronous method RecoverKey of class ara::per::KeyValueStorage serves to recover an individual key-value pair on a best-effort basis when internal redundancy checks fail [SWS_PER_00427]. It accepts the identifier of the key via parameter key as ara::core::StringView and reports success or error via a ara::core::Result<void> [SWS_PER_00427]. After recovery, the pair may exhibit outdated content or initial values, or be lost entirely [SWS_PER_00427].

If an error occurs, the result returns specific error codes from PerErrc or vendor-specific errors [SWS_PER_00427]:

• kKeyNotFound: The specified key does not exist in storage [SWS_PER_00427].
• kIllegalWriteAccess: The storage is configured as read-only [SWS_PER_00427].
• kPhysicalStorageFailure: Access to physical storage failed [SWS_PER_00427].
• kIntegrityCorrupted: Structural integrity damage prevents data from being written [SWS_PER_00427].
• kEncryptionFailed or kAuthenticationFailed: Encryption, decryption, or MAC validation fails [SWS_PER_00427].
• kOutOfStorageSpace or kQuotaExceeded: Available physical storage is insufficient or the configured maximum size is exceeded [SWS_PER_00427].

The operation is specified as thread-safe and exception-safe [SWS_PER_00427]. However, calls may be delayed if storage-wide actions such as RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049], or DiscardPendingChanges [SWS_PER_00365] are being executed in parallel [SWS_PER_00427]. Likewise, concurrent calls to SetValue [SWS_PER_00046], GetValue [SWS_PER_00044], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426], or another RecoverKey for the same key lead to delays [SWS_PER_00427]. In contrast to ResetKey [SWS_PER_00426], which resets the entry to its delivery state, RecoverKey attempts data rescue [SWS_PER_00427].

Usage and transaction semantics

The method RemoveAllKeys of class ara::per::KeyValueStorage removes all key-value pairs and their associated contents from storage [SWS_PER_00048]. The function is called synchronously, takes no input parameters, and is specified with noexcept [SWS_PER_00048]. The operation is subject to transactional semantics: Deletion of all keys only becomes permanently effective in physical storage once SyncToStorage [SWS_PER_00049] is subsequently called [SWS_PER_00048]. Within the running transaction, read operations such as GetValue [SWS_PER_00332] or size queries via GetCurrentValueSize [SWS_PER_00554] directly reflect the cleared state [SWS_PER_00044].

Error handling

ara::core::Result<void> serves as the return value [SWS_PER_00048]. If an error occurs, rollback semantics are applied [SWS_PER_00048]. Possible errors include:

• Access violation with storage configured as read-only (interpretation: this is likely to correspond to error code PerErrc::kIllegalWrite) [SWS_PER_00048], Question Q-a820d779e19ac5c9 (open)
• PerErrc::kPhysicalStorageFailure in case of errors when accessing the physical storage medium [SWS_PER_00048],
• PerErrc::kIntegrityCorrupted in the event of corrupted structural data integrity [SWS_PER_00048],
• PerErrc::kEncryptionFailed as well as PerErrc::kAuthenticationFailed in the event of encryption/decryption or MAC verification failures [SWS_PER_00048], as well as vendor-specific errors.

Concurrency and Interaction

The method is classified as thread-safe and exception safe [SWS_PER_00048]. However, execution may be delayed if calls to RemoveAllKeys, SyncToStorage [SWS_PER_00049], SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426], or RecoverKey [SWS_PER_00427] are active concurrently in another thread [SWS_PER_00048].

The synchronous member function RemoveKey of class ara::per::KeyValueStorage serves to remove a key and the associated value from the Key-Value Storage [SWS_PER_00047]. It accepts the identifier of the key to be removed as ara::core::StringView via parameter key and returns a ara::core::Result<void> [SWS_PER_00047].

The operation is subject to transactional semantics: Changes do not become persistent in physical storage immediately, but only take effect when SyncToStorage is explicitly called [SWS_PER_00047], which synchronizes modified key-value pairs [SWS_PER_00049]. Pending changes can be discarded before synchronization with DiscardPendingChanges [SWS_PER_00365]. Reading accesses such as GetValue [SWS_PER_00044], [SWS_PER_00332], or GetCurrentValueSize [SWS_PER_00554] also operate on the transaction state and immediately reflect the erasure.

Regarding concurrency, the method is specified as thread-safe (thread-safe) and exception safe (exception safe) [SWS_PER_00047]. A call can be delayed if RemoveAllKeys, SyncToStorage, or DiscardPendingChanges are executed concurrently in another thread, or if operations such as SetValue, GetValue, GetCurrentValueSize, RemoveKey, RecoverKey, or ResetKey access the same key-value pair simultaneously [SWS_PER_00047].

If an error occurs during execution, rollback semantics take effect and the returned result object contains an error code [SWS_PER_00047]:

• PerErrc::kKeyNotFound: The specified key does not exist in storage [SWS_PER_00047].
• PerErrc::kIllegalWriteAccess: Key-value storage is configured read-only [SWS_PER_00047].
• PerErrc::kPhysicalStorageFailure: Access to the physical storage medium failed [SWS_PER_00047].
• PerErrc::kIntegrityCorrupted: Writing fails due to corrupted structural integrity [SWS_PER_00047].
• PerErrc::kEncryptionFailed or PerErrc::kAuthenticationFailed: Encryption or decryption fails, or MAC calculation/verification is erroneous [SWS_PER_00047].

use

The synchronous method ResetKey resets an individual key-value pair in an instance of ara::per::KeyValueStorage to its initial value [SWS_PER_00426]. The identifier key is passed as a parameter as ara::core::StringView [SWS_PER_00426]. If the key is not currently present in storage, it is newly created. In both cases, the state of the entry subsequently corresponds to that of a new installation from the current Target Configuration [SWS_PER_00426]. The function is declared as noexcept and returns a ara::core::Result<void> [SWS_PER_00426].

Error handling

If an error occurs during execution, the Result object returns a corresponding error code [SWS_PER_00426]:

• PerErrc::kInitValueNotAvailable: If an initial value for the key is defined neither in the Application Design nor in the Target Configuration (rollback semantics) [SWS_PER_00426].
• kIllegalWrite: If the Key-Value Storage is configured as read-only [SWS_PER_00426].
• PerErrc::kPhysicalStorageFailure or PerErrc::kOutOfStorageSpace: In case of physical storage access errors or insufficient storage space (without rollback semantics) [SWS_PER_00426].
• PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed, or PerErrc::kQuotaExceeded: In case of integrity violations, crypto and authentication errors, or exceeding the configured AllowedSize (each with rollback semantics) [SWS_PER_00426].

Concurrency and Interaction

The function is thread-safe and exception-safe [SWS_PER_00426]. However, the call may be delayed if storage-wide operations such as RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049], or DiscardPendingChanges [SWS_PER_00365] are active in parallel from another thread. Likewise, concurrent accesses to the same key via SetValue [SWS_PER_00046], GetValue [SWS_PER_00044] [SWS_PER_00332], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], RecoverKey [SWS_PER_00427], or another ResetKey lead to delays [SWS_PER_00426].

The synchronous method SyncToStorage of class ara::per::KeyValueStorage writes modified key-value pairs from the memory buffer permanently to physical storage [SWS_PER_00049]. It takes no parameters and returns a ara::core::Result<void>, is declared as noexcept, and is specified as exception safe and thread-safe [SWS_PER_00049].

Interaction and transactional semantics

Modifying operations such as SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047], and RemoveAllKeys [SWS_PER_00048] use transactional semantics. Their changes only take effect upon calling SyncToStorage [SWS_PER_00046]. If pending modifications are to be discarded before writing, DiscardPendingChanges can alternatively be called [SWS_PER_00365].

Concurrency

Although the function is thread-safe, execution can be delayed if operations such as SetValue, RemoveKey, RemoveAllKeys, DiscardPendingChanges, RecoverKey, or ResetKey are active concurrently in another thread [SWS_PER_00049].

Error handling

If synchronization fails, the Result returns an error code [SWS_PER_00049]:

• Errors with rollback semantics (changes are rolled back): PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed, PerErrc::kQuotaExceeded, as well as PerErrc::kIllegalWrite [SWS_PER_00049].
• Errors without rollback semantics: PerErrc::kPhysicalStorageFailure on physical access errors and PerErrc::kOutOfStorageSpace on insufficient storage space [SWS_PER_00049].
• Configuration errors: Error code Access if storage is configured as read-only or, in case of write-only-once, the key already exists [SWS_PER_00049].