Enables persistent storage and management of application data via key-value and file storage.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 9cb072b2740aProvenanceOpen questions (1)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
Enables persistent storage and management of application data via key-value and file storage.
The namespace ara::per provides interfaces for persistent data storage by enabling Adaptive Applications to access file-based and key-value-based storage areas via instance specifiers ([SWS_PER_00052], [SWS_PER_00116]). Applications manage opened storages via shared handles, perform coordinated updates upon manifest changes, and can repair inconsistent data via recovery mechanisms ([SWS_PER_00333], [SWS_PER_00357]). While storage accesses occur concurrently via handles, administrative operations such as updates or storage resets require the absence of competing accesses ([SWS_PER_00311]).
Context
The namespace ara::per provides the interfaces of the persistence functional cluster for the AUTOSAR Adaptive Platform. Its primary responsibility is the durable, memory-surviving storage of application data across system startups and process lifecycles. The module distinguishes two fundamental storage paradigms: KeyValueStorage for structured key-value pairs and FileStorage for file-based storage access. Adaptive Applications access these resources via configured port prototypes using ara::core::InstanceSpecifier ([SWS_PER_00052], [SWS_PER_00116]).
Important interaction partners of the namespace are the Update and Configuration Management (UCM), which can provide updated target configurations (Target Configuration) during runtime ([SWS_PER_00576], [SWS_PER_00577]), and the physical storage medium on which ara::per ensures consistency, redundancy, and data safety ([SWS_PER_00311]).
Access to storage objects is controlled via handle abstractions. Opening a storage via OpenKeyValueStorage or OpenFileStorage creates a SharedHandle ([SWS_PER_00052], [SWS_PER_00116]). Since multiple threads can access the same storage concurrently, the physical resource is not necessarily closed when a single SharedHandle leaves its scope; closing occurs only when all referencing SharedHandle instances have been dismantled ([SWS_PER_00052], [SWS_PER_00116]).
For files within a FileStorage, creation and modification states are tracked in detail. The enumeration FileCreationState indicates whether a file was created during installation (kCreatedDuringInstallation), during an update (kCreatedDuringUpdate), by a reset (kCreatedDuringReset), as a result of recovery (kCreatedDuringRecovery), or by the application itself (kCreatedByApplication) ([SWS_PER_00435]). Analogously, FileModificationState reflects when and by which operation a file was last modified ([SWS_PER_00436]).
To manage initial states, the namespace provides reset functions: ResetKeyValueStorage ([SWS_PER_00334]) and ResetAllFiles ([SWS_PER_00336]) reset individual storages to the values initially defined in the manifest. In contrast, the global operation ResetPersistency ([SWS_PER_00358]) completely empties all key-value and file storages; their recreation occurs upon the next call to OpenFileStorage or OpenKeyValueStorage.
A typical application flow comprises checking for configuration updates, applying data migrations, and subsequent storage access:
Prior to or during regular operation, the application checks via CheckForManifestUpdate whether UCM has installed a new target configuration ([SWS_PER_00576]). If this is the case, the new manifest is read in via ReloadPersistencyManifest ([SWS_PER_00577]). During the subsequent verification phase, the application triggers UpdatePersistency ([SWS_PER_00357]). To control version-specific data migrations, the application registers a callback function in advance via RegisterApplicationDataUpdateCallback, which is informed about older contract versions and performs application-own migration steps ([SWS_PER_00356]). Additionally, element changes can be monitored by means of RegisterDataUpdateIndication ([SWS_PER_00578]). After completion of the update, CleanUpPersistency removes obsolete backups and redundant legacy data ([SWS_PER_00567]).
For regular access, the application opens the target resource via OpenKeyValueStorage ([SWS_PER_00052]) or OpenFileStorage ([SWS_PER_00116]). File accesses in FileStorage are controlled via bitmasks of the enumeration OpenMode (e.g., kAtTheBeginning, kAtTheEnd, kTruncate, kAppend), which are combined using the operators operator| ([SWS_PER_00144]) and operator|= ([SWS_PER_00434]) ([SWS_PER_00147]). Positionings are performed relative to Origin (kBeginning, kCurrent, kEnd) ([SWS_PER_00146]). The currently occupied storage size can be determined at runtime via GetCurrentKeyValueStorageSize ([SWS_PER_00405]) and GetCurrentFileStorageSize ([SWS_PER_00406]).
Errors are signaled in the namespace in a standardized manner via the enumeration PerErrc ([SWS_PER_00311]) in conjunction with PerErrorDomain ([SWS_PER_00352]) and MakeErrorCode ([SWS_PER_00351]). The declared class PerException is likely to serve as a C++ exception type for environments in which errors are not handled via ara::core::Result, but via exceptions (Interpretation). Question Q-263982a4a4dae284 (open)
Key error scenarios include:
Configuration and addressing errors: If the passed InstanceSpecifier does not correspond to any port interface configured in the model, opening fails with PerErrc::kStorageNotFound ([SWS_PER_00052], [SWS_PER_00116], [SWS_PER_00311]). File accesses to non-existent files generate PerErrc::kFileNotFound ([SWS_PER_00311]).
Integrity loss and recovery: In the event of structural damage (PerErrc::kIntegrityCorrupted) or failed redundancy checks (PerErrc::kValidationFailed), ara::per enables a best-effort recovery via RecoverKeyValueStorage ([SWS_PER_00333]) or RecoverAllFiles ([SWS_PER_00335]), respectively. Via RegisterRecoveryReportCallback ([SWS_PER_00433]), safety-relevant applications can automatically log corrective measures based on RecoveryReportKind (e.g., kKeyValueStorageRecovered, kFileRecovered) ([SWS_PER_00432]).
Storage limits and physical errors: If quotas or physical capacities are exceeded, PerErrc::kOutOfStorageSpace, PerErrc::kQuotaExceeded, or PerErrc::kTooManyFiles are reported ([SWS_PER_00311]). Hardware or file system errors result in PerErrc::kPhysicalStorageFailure ([SWS_PER_00311]).
Security and access modes: If cryptographic verifications or computations fail, the module returns PerErrc::kEncryptionFailed or PerErrc::kAuthenticationFailed ([SWS_PER_00311]). Write attempts to read-only storage areas are rejected with PerErrc::kIllegalWriteAccess ([SWS_PER_00311]).
This guide is based exclusively on the specification of AUTOSAR Adaptive R25-11.
KI-gestützte Gruppierung auf Basis der Records und Spezifikationsauszüge; keine Gliederung aus der AUTOSAR-Spezifikation.
Class diagram
Abgerundete Rahmen = Namespace- bzw. Klassen-Scopes; hohle Dreieckspfeile = Vererbung (zeigt zur Basisklasse); graue Boxen = namespace-fremde bzw. externe Basisklassen. Klicken öffnet die jeweilige Klassen- bzw. cppreference-Seite.
Returns the space in bytes currently occupied by a File Storage. The returned size includes all metadata and the space used for redundancy and backups. The returned size is only guaranteed to be accurate if the File Storage is not opened and no other operation on the File Storage takes place at the same time.
Returns the space in bytes currently occupied by a Key-Value Storage. The returned size includes all metadata and the space used for redundancy and backups. The returned size is only guaranteed to be accurate if the Key-Value Storage is not opened and no other operation on the Key-Value Storage takes place at the same time.
Opens a File Storage. OpenFileStorage will fail with kResourceBusy when the File Storage is currently being modified by a call from another thread to UpdatePersistency, CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles. Because multiple threads can access the same File Storage concurrently, the File Storage might not be closed when the SharedHandle returned by this function goes out of scope. It will only be closed when all SharedHandles that refer to the same File Storage went out of scope.
Opens a Key-Value Storage. OpenKeyValueStorage will fail with kResourceBusy when the Key-Value Storage is currently being modified by a call from another thread to UpdatePersistency, CleanUpPersistency, Reset Persistency, RecoverKeyValueStorage, or ResetKeyValueStorage. Because multiple threads can access the same Key-Value Storage concurrently, the Key-Value Storage might not be closed when the SharedHandle returned by this function goes out of scope. It will only be closed when all SharedHandles that refer to the same Key-Value Storage went out of scope.
Defines the errors for Persistency. The enumeration values 0 - 255 are reserved for AUTOSAR assigned errors, the stack provider is free to define additional errors starting from 256.
Recovers a File Storage, including all files. RecoverAllFiles recovers a File Storage when the redundancy checks fail. It will fail with kResourceBusy when the File Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles. This method does a best-effort recovery of all files. After recovery, files might show outdated or initial content, or might be lost.
Recovers a Key-ValueStorage. RecoverKeyValueStorage allows to recover a Key-Value Storage when the redundancy checks fail. It will fail with kResourceBusy when the Key-Value Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, Reset Persistency, RecoverKeyValueStorage, or ResetKeyValueStorage. This method does a best-effort recovery of all key-value pairs. After recovery, keys might show outdated or initial value, or might be lost.
Register a recovery reporting callback with Persistency. This callback can be used in safety-aware Adaptive Applications to detect actions of the Persistency that are related to the correctness of the persisted data and the reliability of the storage.
Checks for updates of the Persistency Target Configuration. This method can be used to detect configuration updates that are installed by UCM while the Adaptive Application that uses Persistency is running. To re-read the updated Target Configuration, the Adaptive Application needs to call ara::per:: ReloadPersistencyManifest.
Registers an application data update callback with Persistency. The provided callback function will be called by Persistency if an update of stored application data might be necessary. This decision is based on the contract versions. The contract version that last accessed Persistency is provided as an argument to the callback, as well as the ara::core::InstanceSpecifier referring to the updated Key- Value Storage or File Storage. Based on this information, the Adaptive Application can decide which updates are actually necessary, e.g. a migration from any older contract version could be supported, with different steps required for each of these. The provided function will be called from the context of ara::per::UpdatePersistency, ara::per::OpenKeyValueStorage, or ara::per::OpenFileStorage.
Registers a data update indication callback with Persistency. The provided callback function will be called by Persistency when an update of stored data happened. It will be called from the context of ara::per::UpdatePersistency, ara:: per::OpenKeyValueStorage, or ara::per::OpenFileStorage.
Re-reads the Target Configuration. This method can be used to prepare for updates of the Key-Value Storages and File Storages of Persistency after a new Target Configuration was installed by UCM while the Adaptive Application that uses Persistency is running. Storages are only updated after closing them, either when they are opened again or by an explicit call to ara:: per::UpdatePersistency.
Resets a File Storage, including all files. ResetAllFiles resets a File Storage to the initial state, containing only the files which were deployed from the Target Configuration, with their initial content. Afterwards, the File Storage will appear as if it was newly installed from the current Target Configuration. It will fail with kResourceBusy when the File Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles.
Resets a Key-Value Storage to the initial state. ResetKeyValueStorage allows to reset a Key-Value Storage to the initial state, containing only key-value pairs which were deployed from the Target Configuration, with their initial values. Afterwards, the Key-Value Storage will appear as if it was newly installed from the current Target Configuration. It will fail with kResourceBusy when the Key-Value Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, Reset Persistency, RecoverKeyValueStorage, or ResetKeyValueStorage.
Resets all Key-Value Storages and File Storages by entirely removing their content. The Key-Value Storages and File Storages will be re-created when ara::per:: OpenFileStorage or ara::per::OpenKeyValueStorage is called next time.
Updates all Persistency Key-Value Storages and File Storages after a new Target Configuration was installed. This method can be used to update the persistent data of the Adaptive Application during verification phase.
Defines the errors for Persistency. The enumeration values 0 - 255 are reserved for AUTOSAR assigned errors, the stack provider is free to define additional errors starting from 256.
=1 The requested Key-Value Storage or File Storage is not configured in the AUTOSAR model.
kKeyNotFound
=2 The provided key cannot be not found in the Key-Value Storage.
kIllegalWriteAccess
=3 The operation could not be performed because the accessed Key-Value Storage or File Storage is configured as read-only or write-only-once.
kPhysicalStorageFailure
=4 An error occurred when accessing the physical storage, e.g. because of a corrupted file system or corrupted hardware, or because of insufficient access rights.
kIntegrityCorrupted
=5 The structural integrity of the Key-Value Storage or File Storage could not be established. This can happen when the internal structure of a Key-Value Storage or the metadata of a File Storage is corrupted.
kValidationFailed
=6 The validation of redundancy measures failed for a single key-value pair, for the whole Key-Value Storage, for a single file, or for the whole File Storage.
kEncryptionFailed
=7 The encryption or decryption failed for a single key-value pair, for the whole Key-Value Storage, for a single file, or for the whole File Storage.
kDataTypeMismatch
=8 The provided data type does not match the stored data type.
kInitValueNotAvailable
=9 The operation could not be performed because no initial value is available.
kResourceBusy
= 10 The operation could not be performed because the resource is currently busy.
kOutOfStorageSpace
= 12 The physical storage space was exceeded.
kFileNotFound
= 13 The requested file name cannot be not found in the File Storage.
kInvalidPosition
= 15 SetPosition tried to move to a position that is not reachable (i.e. which is smaller than zero or greater than the current size of the file).
kEof
= 16 The Persistency user tried to read from the end of the file or from an empty file.
kInvalidOpenMode
= 17 Opening a file failed because the requested combination of Open Modes is invalid.
kInvalidSize
= 18 SetFileSize tried to set a new size that is bigger than the current file size.
kTooManyFiles
= 19 The maximum number of files was exceeded.
kQuotaExceeded
= 20 The allocated storage quota was exceeded.
kAuthenticationFailed
= 21 Calculating or checking of the MAC failed for a single key-value pair, for the whole Key-Value Storage, for a single file, or for the whole File Storage.
Request a governed re-review of this record. The record is not changed immediately.
=1 A Key-Value Storage was corrupted, an insufficient number of valid copies existed. storage contains the short-name path of the Key-Value Storage, reportedElements is empty, reportedInstances contains the indices of the affected Key-Value Storage copies.
kKeyValueStorageRecovered
=2 A Key-Value Storage was corrupted, but a sufficient number of valid copies existed. storage contains the short-name path of the Key-Value Storage, reportedElements is empty, reportedInstances contains the indices of the affected Key-Value Storage copies.
kKeyRecoveryFailed
=3 A set of key-value pairs was corrupted, an insufficient number of valid copies existed. storage contains the short-name path of the Key-Value Storage, reportedElements contains the list of affected keys, reportedInstances contains the indices of the affected Key-Value Storage or key-value pair copies. In general, the nth key in reportedElements corresponds to the nth index in reported Instances, i.e. a key may be reported several times if several copies are broken. In case only one key-value pair is affected, reported Elements may be provided containing just this key.
kKeyRecovered
=4 A set of key-value pairs was corrupted, but a sufficient number of valid copies existed. storage contains the short-name path of the Key-Value Storage, reportedElements contains the list of affected keys, reportedInstances contains the indices of the affected Key-Value Storage or key-value pair copies. In general, the nth key in reportedElements corresponds to the nth index in reported Instances, i.e. a key may be reported several times if several copies are broken. In case only one key-value pair is affected, reported Elements may be provided containing just this key.
kFileStorageRecoveryFailed
=5 A File Storage was corrupted, an insufficient number of valid copies existed. storage contains the short-name path of the File Storage, reportedElements is empty, reportedInstances contains the indices of the affected File Storage copies.
kFileStorageRecovered
=6 A File Storage was corrupted, but a sufficient number of valid copies existed. storage contains the short-name path of the File Storage, reportedElements is empty, reportedInstances contains the indices of the affected File Storage copies.
kFileRecoveryFailed
=7 A set of files was corrupted, an insufficient number of valid copies existed. storage contains the short-name path of the File Storage, reportedElements contains the list of affected file names, reported Instances contains the indices of the affected File Storage or file copies. In general, the nth file name in reportedElements corresponds to the nth index in reportedInstances, i.e. a file name may be reported several times if several copies are broken. In case only one file is affected, reportedElements may be provided containing just this file name.
kFileRecovered
=8 A set of files was corrupted, but a sufficient number of valid copies existed. storage contains the short-name path of the File Storage, reportedElements contains the list of affected file names, reported Instances contains the indices of the affected File Storage or file copies. In general, the nth file name in reportedElements corresponds to the nth index in reportedInstances, i.e. a file name may be reported several times if several copies are broken. In case only one file is affected, reportedElements may be provided containing just this file name.
Request a governed re-review of this record. The record is not changed immediately.
Checks for updates of the Persistency Target Configuration. This method can be used to detect configuration updates that are installed by UCM while the Adaptive Application that uses Persistency is running. To re-read the updated Target Configuration, the Adaptive Application needs to call ara::per:: ReloadPersistencyManifest.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: b1f49db8b33dProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The synchronous function CheckForManifestUpdate from header ara/per/update.h checks in namespace ara::per whether updates to the Persistency Target Configuration are present [SWS_PER_00576]. It serves to detect configuration changes that were applied by the Update and Configuration Management (UCM) while the adaptive application using Persistency is already running [SWS_PER_00576]. The function takes no parameters and returns a ara::core::Result<bool>: true if the configuration has been updated since the last retrieval, or false if it has remained unchanged [SWS_PER_00576].
Error Handling and Concurrency
The function is declared as noexcept and exception-safe (exception safe), but not thread-safe (not thread-safe) [SWS_PER_00576]. In the event of an error, the result contains either vendor-specific errors or one of the following error codes [SWS_PER_00576]:
kPhysicalStorageFailure: Occurs if access to physical storage fails during the check [SWS_PER_00576].
kIntegrityCorrupted: Occurs if stored data cannot be read due to corrupted structural integrity [SWS_PER_00576].
Interaction
If an update is detected (return value true), the application must subsequently call ara::per::ReloadPersistencyManifest in order to actually reload the modified Target Configuration [SWS_PER_00576].
This text was generated by an AI and serves as guidance based on the specification.
A Result containing true if the Target Configuration was updated or false if it is unchanged since the last time the Target Configuration was read. In case of an error, it contains any of the errors defined below, or a vendor specific error.
Fehler
Fehlercode
Beschreibung
kPhysicalStorage-Failure
rollback_semantics Returned if access to the physical storage fails during the checking operation.
kIntegrityCor-rupted
rollback_semantics Returned if stored data cannot be read because the structural integrity is corrupted.
Request a governed re-review of this record. The record is not changed immediately.
Removes backup data and other unused data of all Persistency Key-Value Storages and File Storages.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: ce1bea3039deProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The synchronous function CleanUpPersistency from ara/per/update.h serves to remove backup data and other unused data across all key-value and file storages of an instance [SWS_PER_00567]. It takes no parameters and returns the result via the return type ara::core::Result<void>[SWS_PER_00567].
Concurrency and Limitations
The function is not thread-safe (not thread-safe) and requires exclusive access to all storage resources [SWS_PER_00567]. If a ara::per::SharedHandle of a key-value or file storage is still open, the call fails with kResourceBusy[SWS_PER_00567]. Likewise, concurrent operations such as UpdatePersistency, ResetPersistency, RecoverKeyValueStorage, ResetKeyValueStorage, RecoverAllFiles, or ResetAllFiles lead to error code kResourceBusy[SWS_PER_00567].
Returns the space in bytes currently occupied by a File Storage. The returned size includes all metadata and the space used for redundancy and backups. The returned size is only guaranteed to be accurate if the File Storage is not opened and no other operation on the File Storage takes place at the same time.
Returns the space in bytes currently occupied by a Key-Value Storage. The returned size includes all metadata and the space used for redundancy and backups. The returned size is only guaranteed to be accurate if the Key-Value Storage is not opened and no other operation on the Key-Value Storage takes place at the same time.
Opens a File Storage. OpenFileStorage will fail with kResourceBusy when the File Storage is currently being modified by a call from another thread to UpdatePersistency, CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles. Because multiple threads can access the same File Storage concurrently, the File Storage might not be closed when the SharedHandle returned by this function goes out of scope. It will only be closed when all SharedHandles that refer to the same File Storage went out of scope.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 14078ca86bfbProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The synchronous function ara::per::OpenFileStorage opens a file storage for persistent data and provides it via a shared access handle [SWS_PER_00116]. As a parameter, it expects a reference to a ara::core::InstanceSpecifier, which specifies the shortName path of a port prototype typed by an PersistencyFileStorageInterface. The return value is an ara::core::Result<ara::core::SharedHandle<FileStorage>>[SWS_PER_00116].
Regarding concurrency, the function is specified as thread-safe and exception-safe [SWS_PER_00116]. Since multiple threads can access the same file storage instance in parallel, the physical storage is not necessarily closed when a single SharedHandle goes out of scope. Closing occurs only when all referencing handles have gone out of scope [SWS_PER_00116].
In case of an error, the Result contains error codes from the enumeration PerErrc or vendor-specific errors [SWS_PER_00116]:
PerErrc::kResourceBusy: Returned if administrative operations such as CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles are executed concurrently. While UpdatePersistency is active, this error occurs if the call takes place outside the callback registered via RegisterApplicationDataUpdateCallback or with a different identifier [SWS_PER_00116], [SWS_PER_00356].
Configuration and access errors: kStorageNotFound in case of an unconfigured instance, kPhysicalStorageFailure in case of physical storage errors, as well as kIntegrityCorrupted, kValidationFailed, kEncryptionFailed, and kAuthenticationFailed in case of integrity, verification, or decryption issues [SWS_PER_00116].
Capacity limits during implicit updates: kOutOfStorageSpace, kTooManyFiles, or kQuotaExceeded[SWS_PER_00116].
In interaction with the module, a prior reset using ResetPersistency causes deleted file storages to be recreated upon the next call to OpenFileStorage[SWS_PER_00358]. If data is updated during opening, an indication callback registered via RegisterDataUpdateIndication is invoked directly in the context of OpenFileStorage[SWS_PER_00578].
This text was generated by an AI based on the AUTOSAR Adaptive R25-11 specification.
rollback_semantics Returned if CleanUpPersistency, or ResetPersistency is currently being executed, or if RecoverAllFiles or ResetAllFiles is currently being executed for the same File Storage. Also, while Update Persistency is currently being executed, this error is returned when OpenFileStorage is called outside of the callback registered via RegisterApplicationDataUpdateCallback, or if the used Instance Specifier differs from the one provided by the callback.
no_rollback_semantics Returned if the available physical storage space is insufficient for the files that are added/updated during an implicit update of the File Storage.
rollback_semantics Returned if the files that are added/updated during an implicit update of the File Storage would exceed the configured maximum AllowedSize.
Opens a Key-Value Storage. OpenKeyValueStorage will fail with kResourceBusy when the Key-Value Storage is currently being modified by a call from another thread to UpdatePersistency, CleanUpPersistency, Reset Persistency, RecoverKeyValueStorage, or ResetKeyValueStorage. Because multiple threads can access the same Key-Value Storage concurrently, the Key-Value Storage might not be closed when the SharedHandle returned by this function goes out of scope. It will only be closed when all SharedHandles that refer to the same Key-Value Storage went out of scope.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: d24427922381Provenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
Usage and lifecycle
The synchronous function OpenKeyValueStorage opens a key-value storage and is specified as thread-safe as well as noexcept[SWS_PER_00052]. As parameter kvs, an ara::core::InstanceSpecifier referencing the path of a PortPrototype typed by an PersistencyKeyValueStorageInterface is passed. Return occurs as ara::core::Result<SharedHandle<KeyValueStorage>>. Since multiple threads can open the same storage concurrently, Persistency only closes physical storage once all referencing SharedHandle instances have left their scope [SWS_PER_00052].
Error Handling and Concurrency
In case of error, the result returns specific error codes of the Persistency error domain [SWS_PER_00052]:
PerErrc::kStorageNotFound: The identifier does not match any configured interface of the executable.
PerErrc::kResourceBusy: Occurs when CleanUpPersistency, ResetPersistency[SWS_PER_00358], RecoverKeyValueStorage, or ResetKeyValueStorage are executed concurrently for this storage. During UpdatePersistency, the call is only permitted within the callback registered via RegisterApplicationDataUpdateCallback with the instance identifier passed there [SWS_PER_00356].
PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, and PerErrc::kAuthenticationFailed on defects, validation, or crypto errors.
PerErrc::kOutOfStorageSpace and PerErrc::kQuotaExceeded on insufficient storage space or quota exceeded during an implicit update.
Interaction
If all data was previously deleted using ResetPersistency, storage is automatically recreated upon the next call to OpenKeyValueStorage[SWS_PER_00358]. After opening, unsaved modifications can be reset to the state at opening via DiscardPendingChanges[SWS_PER_00365]. In addition, opening can trigger the execution of callbacks registered via RegisterDataUpdateIndication[SWS_PER_00578].
This usage note was generated automatically based on the specification requirements.
A Result containing a SharedHandle for the KeyValueStorage. In case of an error, it contains any of the errors defined below, or a vendor specific error.
Fehler
Fehlercode
Beschreibung
Found
Returned if the passed InstanceSpecifier does not match any PersistencyKeyValueStorageInterface configured for this Executable.
rollback_semantics Returned if CleanUpPersistency, or ResetPersistency is currently being executed, or if RecoverKeyValueStorage or ResetKeyValue Storage is currently being executed for the same Key-Value Storage. Also, while UpdatePersistency is currently being executed, this error is returned when OpenKeyValueStorage is called outside of the callback registered via RegisterApplicationDataUpdate Callback, or if the used InstanceSpecifier differs from the one provided by the callback.
no_rollback_semantics Returned if the available physical storage space is insufficient for the values that are added/updated during an implicit update of the Key-Value Storage.
rollback_semantics Returned if the values that are added/updated during an implicit update of the Key-Value Storage would exceed the configured maximumAllowedSize.
Recovers a File Storage, including all files. RecoverAllFiles recovers a File Storage when the redundancy checks fail. It will fail with kResourceBusy when the File Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles. This method does a best-effort recovery of all files. After recovery, files might show outdated or initial content, or might be lost.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: ca84cc440ba3Provenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The function RecoverAllFiles performs a recovery of a file-based storage (File Storage) including all files stored in it when redundancy checks fail [SWS_PER_00335]. The call is synchronous, specifies the InstanceSpecifier for the configured PortPrototype, and returns a ara::core::Result<void>[SWS_PER_00335].
The recovery operates on a best-effort basis: After completion, files may contain outdated content, be reset to their initial state, or be lost entirely [SWS_PER_00335]. If access to the storage medium fails (PerErrc::kPhysicalStorageFailure) or storage space is insufficient (PerErrc::kOutOfStorageSpace), no rollback guarantee exists [SWS_PER_00335]. If an error occurs during encryption (PerErrc::kEncryptionFailed), integrity check (PerErrc::kAuthenticationFailed), or storage size limitation (PerErrc::kQuotaExceeded), rollback semantics apply [SWS_PER_00335]. If the identifier does not match any configured interface, this results in PerErrc::kStorageNotFound[SWS_PER_00335].
Although the function is thread-safe, execution fails with PerErrc::kResourceBusy as long as the storage is open or an active shared handle is present [SWS_PER_00335], [SWS_PER_00116]. Likewise, concurrent executions of ResetAllFiles[SWS_PER_00336] for the same storage as well as the global update operations UpdatePersistency[SWS_PER_00357], ResetPersistency[SWS_PER_00358], and CleanUpPersistency[SWS_PER_00567] block the call [SWS_PER_00335].
This usage note was generated by an AI based on the specifications.
rollback_semantics Returned if UpdatePersistency, CleanUpPersistency, or Reset Persistency is currently being executed, or if ResetAllFiles is currently being executed for the same File Storage, or a Shared Handle of the same File Storage is currently in use.
Recovers a Key-ValueStorage. RecoverKeyValueStorage allows to recover a Key-Value Storage when the redundancy checks fail. It will fail with kResourceBusy when the Key-Value Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, Reset Persistency, RecoverKeyValueStorage, or ResetKeyValueStorage. This method does a best-effort recovery of all key-value pairs. After recovery, keys might show outdated or initial value, or might be lost.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: ba269bfce693Provenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The synchronous function RecoverKeyValueStorage in namespace ara::per serves to recover a key-value storage after failed redundancy checks ([SWS_PER_00333]). As parameter kvs, a ara::core::InstanceSpecifier referencing the ShortName path of a corresponding PortPrototype is passed ([SWS_PER_00333]). Recovery is performed on a best-effort basis; after the process, keys may exhibit outdated or initial values or be lost entirely ([SWS_PER_00333]).
Although the function is specified as thread-safe, execution fails with error code PerErrc::kResourceBusy if the respective key-value storage is open—i.e., at least one active SharedHandle exists ([SWS_PER_00052], [SWS_PER_00333]). The same error occurs if other threads concurrently call modifying functions: UpdatePersistency ([SWS_PER_00357]), CleanUpPersistency ([SWS_PER_00567]), ResetPersistency ([SWS_PER_00358]), or ResetKeyValueStorage ([SWS_PER_00334]). During recovery, a call to OpenKeyValueStorage also fails with kResourceBusy ([SWS_PER_00052]).
The result is returned synchronously as ara::core::Result<void>. In addition to PerErrc::kResourceBusy, the following specific errors are defined ([SWS_PER_00333]):
PerErrc::kStorageNotFound: The passed identifier does not match any configured interface.
PerErrc::kPhysicalStorageFailure: Access to physical storage fails (no rollback semantics).
PerErrc::kOutOfStorageSpace: Insufficient physical storage space for the recovered data (no rollback semantics).
PerErrc::kQuotaExceeded: Exceeding the configured maximum length (maximumAllowedSize).
PerErrc::kEncryptionFailed and PerErrc::kAuthenticationFailed: Error during encryption or MAC calculation.
This text was created by an AI based on the AUTOSAR specification.
rollback_semantics Returned if UpdatePersistency, CleanUpPersistency, or Reset Persistency is currently being executed, or if ResetKeyValue Storage is currently being executed for the same Key-Value Storage, or a SharedHandle of the same Key-Value Storage is currently in use.
Registers an application data update callback with Persistency. The provided callback function will be called by Persistency if an update of stored application data might be necessary. This decision is based on the contract versions. The contract version that last accessed Persistency is provided as an argument to the callback, as well as the ara::core::InstanceSpecifier referring to the updated Key- Value Storage or File Storage. Based on this information, the Adaptive Application can decide which updates are actually necessary, e.g. a migration from any older contract version could be supported, with different steps required for each of these. The provided function will be called from the context of ara::per::UpdatePersistency, ara::per::OpenKeyValueStorage, or ara::per::OpenFileStorage.
The callback function to be called by Persistency after an update of persistent data took place. The function will be called with the shortName path of an updated Key-Value Storage or File Storage, and with the contract version with which the Persistency was last accessed.
Rückgabewert
Typ
Beschreibung
None
Request a governed re-review of this record. The record is not changed immediately.
Registers a data update indication callback with Persistency. The provided callback function will be called by Persistency when an update of stored data happened. It will be called from the context of ara::per::UpdatePersistency, ara:: per::OpenKeyValueStorage, or ara::per::OpenFileStorage.
The callback function to be called by Persistency after an update of persistent data took place. The function will be called with the shortName path of an updated Key-Value Storage or File Storage, and with the the updated elements of the storage.
monitoredStorage
A Key-Value Storage or File Storage for which updates shall be reported.
monitoredElements
A set of elements for which updates shall be reported.
Rückgabewert
Typ
Beschreibung
None
Request a governed re-review of this record. The record is not changed immediately.
Register a recovery reporting callback with Persistency. This callback can be used in safety-aware Adaptive Applications to detect actions of the Persistency that are related to the correctness of the persisted data and the reliability of the storage.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 5828fc3d3f00ProvenanceOpen questions (1)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The function RegisterRecoveryReportCallback in namespace ara::per ([SWS_PER_00433]) is used to register a callback routine with the Persistency component. It is used in safety-related Adaptive Applications to detect corrective actions taken by Persistency regarding the correctness of persisted data and the reliability of storage [SWS_PER_00433].
Parameters and Call Semantics
Passed as a parameter is recoveryReportCallback, a std::function that is called by Persistency when errors in the stored data have been successfully corrected using available redundancy [SWS_PER_00433]. The following context information is passed to the callback [SWS_PER_00433]:
storage: The path (shortName) of the affected key-value storage or file storage as ara::core::InstanceSpecifier.
recoveryReportKind: The recovery report type (ara::per::RecoveryReportKind).
reportedElements: A vector of identifiers of the affected elements (ara::core::Vector<ara::core::String>).
reportedInstances: A vector of the affected instances (ara::core::Vector<std::uint8_t>).
Error Handling and Concurrency
The function has no return value and is declared as noexcept; it is considered exception-safe (exception safe) [SWS_PER_00433]. Distinct error codes do not exist [SWS_PER_00433]. Regarding thread safety, the interface is classified as not thread-safe[SWS_PER_00433]. Therefore, the call typically takes place during the initialization phase of the application before concurrent storage accesses are started. Question Q-e5b93ea58fb56a1c (open)
This usage note was created by an AI and is based on the specifications of the AUTOSAR platform.
The callback function to be called by Persistency to report errors in the stored data that were corrected using the available redundancy. The function will be called with the shortName path of the affected Key-Value Storage or File Storage in storage and information on what has been corrected, placed in the parameters recoveryReport Kind, reportedElements, and reportedInstances.
Rückgabewert
Typ
Beschreibung
None
Request a governed re-review of this record. The record is not changed immediately.
Re-reads the Target Configuration. This method can be used to prepare for updates of the Key-Value Storages and File Storages of Persistency after a new Target Configuration was installed by UCM while the Adaptive Application that uses Persistency is running. Storages are only updated after closing them, either when they are opened again or by an explicit call to ara:: per::UpdatePersistency.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 19920ccb9cf9ProvenanceOpen questions (1)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The synchronous function ReloadPersistencyManifest from namespace ara::per (declared in #include "ara/per/update.h") reloads the target configuration (Target Configuration) of Persistency [SWS_PER_00577]. It serves to prepare updates of Key-Value Storages and File Storages after a new target configuration has been installed by the Update and Configuration Management (UCM) during the runtime of the Adaptive Application [SWS_PER_00577].
Typically, the application checks beforehand with CheckForManifestUpdate[SWS_PER_00576] whether a configuration update is present and subsequently calls ReloadPersistencyManifest[SWS_PER_00576]. However, the reload does not yet update the persistent storages immediately: storages are updated only after they are closed – either upon reopening or via an explicit call to ara::per::UpdatePersistency[SWS_PER_00577]. Interpretation: Already opened storage areas are presumably not closed automatically by the call, so that the application must close them itself or update them explicitly. Question Q-16f9dae418feb3fa (open)
The function takes no parameters and returns a ara::core::Result<void>[SWS_PER_00577]. In the event of an error, the result contains vendor-specific errors or one of the following error codes with rollback semantics [SWS_PER_00577]:
kPhysicalStorageFailure: Occurs if access to the physical storage fails during the read operation [SWS_PER_00577].
kIntegrityCorrupted: Occurs if stored data cannot be read due to corrupted structural integrity [SWS_PER_00577].
Regarding concurrency, the function is specified as not thread-safe (not thread-safe), but declared as exception-safe (exception safe) and noexcept[SWS_PER_00577]. Parallel calls must therefore be synchronized on the application side.
This usage note was created by an AI based on the specification.
Resets a File Storage, including all files. ResetAllFiles resets a File Storage to the initial state, containing only the files which were deployed from the Target Configuration, with their initial content. Afterwards, the File Storage will appear as if it was newly installed from the current Target Configuration. It will fail with kResourceBusy when the File Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, ResetPersistency, RecoverAllFiles, or ResetAllFiles.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: f645139d391cProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The function ResetAllFiles synchronously resets a File Storage to its initial delivery state according to the current Target Configuration[SWS_PER_00336]. After successful execution, the storage contains exclusively the files defined there with their original contents, as if it had been newly installed [SWS_PER_00336].
Usage and concurrency: The parameter fs is used to pass the instance identifier of a PortPrototype typed via PersistencyFileStorageInterface[SWS_PER_00336]. Although the function is specified as thread-safe and exception safe, it requires exclusive storage access: If the storage is currently open (for example via an active SharedHandle from OpenFileStorage[SWS_PER_00116]) or is modified concurrently by UpdatePersistency[SWS_PER_00357], CleanUpPersistency[SWS_PER_00567], ResetPersistency[SWS_PER_00358], RecoverAllFiles[SWS_PER_00335], or another call to ResetAllFiles, the execution fails [SWS_PER_00336].
Error handling: The function returns a ara::core::Result<void>[SWS_PER_00336]. Possible error codes from PerErrc are:
kResourceBusy: The file storage is open or is being modified concurrently (rollback semantics) [SWS_PER_00336].
kStorageNotFound: The identifier does not match any interface configured for the executable [SWS_PER_00336].
kPhysicalStorageFailure or kOutOfStorageSpace: Physical storage error or insufficient storage space (no rollback semantics) [SWS_PER_00336].
kEncryptionFailed or kAuthenticationFailed: Error during encryption or MAC calculation (rollback semantics) [SWS_PER_00336].
Interaction: After resetting, recovered files have the status FileCreationState::kCreatedDuringReset[SWS_PER_00435] as well as FileModificationState::kModifiedDuringReset[SWS_PER_00436] during status queries.
This usage note was generated by an AI based on the AUTOSAR R25-11 specification.
rollback_semantics Returned if UpdatePersistency, CleanUpPersistency, or Reset Persistency is currently being executed, or if RecoverAllFiles is currently being executed for the same File Storage, or a Shared Handle of the same File Storage is currently in use.
Resets a Key-Value Storage to the initial state. ResetKeyValueStorage allows to reset a Key-Value Storage to the initial state, containing only key-value pairs which were deployed from the Target Configuration, with their initial values. Afterwards, the Key-Value Storage will appear as if it was newly installed from the current Target Configuration. It will fail with kResourceBusy when the Key-Value Storage is currently open, or when it is modified by a call from another thread to UpdatePersistency, CleanUpPersistency, Reset Persistency, RecoverKeyValueStorage, or ResetKeyValueStorage.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 48697319880fProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The synchronous function ResetKeyValueStorage resets a specific key-value storage to its initial state [SWS_PER_00334]. After successful execution, the storage contains exclusively those key-value pairs with their initial values that were provided via the Target Configuration; the storage then behaves as if it had been freshly installed from the current configuration [SWS_PER_00334]. As a parameter, the kvs path referencing the PortPrototype of a configured PersistencyKeyValueStorageInterface is passed as ara::core::InstanceSpecifier[SWS_PER_00334].
The function is specified as thread-safe and exception safe, but is subject to strict concurrency conditions regarding open storages and global persistence operations [SWS_PER_00334]:
The call fails with PerErrc::kResourceBusy if the respective key-value storage is currently open (i.e., a SharedHandle still exists, see [SWS_PER_00052]) or a recovery using RecoverKeyValueStorage[SWS_PER_00333] is being executed concurrently on the same storage [SWS_PER_00334].
Likewise, concurrent execution of the global operations UpdatePersistency[SWS_PER_00357], CleanUpPersistency[SWS_PER_00567], ResetPersistency[SWS_PER_00358] or a concurrent call to ResetKeyValueStorage in another thread leads to kResourceBusy[SWS_PER_00334].
As a result, the function returns a ara::core::Result<void>[SWS_PER_00334]. In case of an error, the following specific error codes occur in addition to kResourceBusy: PerErrc::kStorageNotFound (invalid InstanceSpecifier), PerErrc::kPhysicalStorageFailure (access error to the storage medium, no rollback semantics), PerErrc::kOutOfStorageSpace (insufficient storage space for initial values, no rollback semantics), PerErrc::kEncryptionFailed (encryption error), and PerErrc::kAuthenticationFailed (error during MAC calculation) [SWS_PER_00334].
This usage note was generated by an AI based on the AUTOSAR R25-11 specification.
rollback_semantics Returned if UpdatePersistency, CleanUpPersistency, or Reset Persistency is currently being executed, or if RecoverKeyValue Storage is currently being executed for the same Key-Value Storage, or a SharedHandle of the same Key-Value Storage is currently in use.
Resets all Key-Value Storages and File Storages by entirely removing their content. The Key-Value Storages and File Storages will be re-created when ara::per:: OpenFileStorage or ara::per::OpenKeyValueStorage is called next time.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: d1720067a24eProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The synchronous function ResetPersistency ([SWS_PER_00358]) from header ara/per/update.h serves to completely reset all key-value and file storages of an application. Upon invocation, all persistent contents are completely deleted. The storages themselves are not immediately recreated, but are only recreated upon the respective next call to ara::per::OpenKeyValueStorage ([SWS_PER_00052]) or ara::per::OpenFileStorage ([SWS_PER_00116]). Files that are newly provided after the reset receive the creation status FileCreationState::kCreatedDuringInstallation ([SWS_PER_00435]).
Error handling
As a return value, the function provides a ara::core::Result<void> ([SWS_PER_00358]). If access to the physical storage medium fails during the operation, the function returns kPhysicalStorageFailure without rollback semantics. If persistent resources are occupied or modified in parallel, the call is aborted with kResourceBusy and active rollback semantics ([SWS_PER_00358]). In addition, vendor-specific errors may occur.
Concurrency and Limitations
The interface is declared as exception safe, but explicitly classified as not thread-safe ([SWS_PER_00358]). It fails with kResourceBusy as soon as:
global operations such as UpdatePersistency ([SWS_PER_00357]) or CleanUpPersistency ([SWS_PER_00567]) are already being executed,
an individual storage is processed in parallel via RecoverKeyValueStorage, ResetKeyValueStorage, RecoverAllFiles ([SWS_PER_00335]), or ResetAllFiles ([SWS_PER_00336]),
or at least one active SharedHandle of a key-value or file storage still exists ([SWS_PER_00358]).
As long as ResetPersistency is running, concurrent opening attempts via OpenKeyValueStorage ([SWS_PER_00052]) or OpenFileStorage ([SWS_PER_00116]) in other threads will also result in kResourceBusy.
This text was created by an AI. AUTOSAR specifications are authoritative.
Updates all Persistency Key-Value Storages and File Storages after a new Target Configuration was installed. This method can be used to update the persistent data of the Adaptive Application during verification phase.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: a05074f12eedProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The synchronous function ara::per::UpdatePersistency ([SWS_PER_00357], header ara/per/update.h) updates all key-value and file storages of an application after the installation of a new target configuration. It serves to update the persistent data of an Adaptive Application during the verification phase [SWS_PER_00357]. The function takes no input parameters and returns a ara::core::Result<void>[SWS_PER_00357].
Error handling
In case of an error, the returned Result contains a specific error code or a vendor-specific error [SWS_PER_00357]. A distinction is made between operations with and without rollback semantics:
Rollback semantics: In case of kIntegrityCorrupted, kValidationFailed, kEncryptionFailed, kAuthenticationFailed, kTooManyFiles (exceeding maxNumberOfFiles), kQuotaExceeded (exceeding MaximumAllowedSize), and kResourceBusy, changes made are rolled back [SWS_PER_00357].
No rollback semantics: In case of physical storage errors (kPhysicalStorageFailure) and insufficient physical storage space (kOutOfStorageSpace), no rollback is guaranteed [SWS_PER_00357].
Concurrency and Limitations
The function is specified as exception-safe, but explicitly as not thread-safe [SWS_PER_00357]. A call fails with kResourceBusy as soon as a SharedHandle of a key-value or file storage is still in use or maintenance functions such as CleanUpPersistency[SWS_PER_00567], ResetPersistency[SWS_PER_00358], RecoverKeyValueStorage[SWS_PER_00333], ResetKeyValueStorage[SWS_PER_00334], RecoverAllFiles[SWS_PER_00335], or ResetAllFiles[SWS_PER_00336] are executed in parallel [SWS_PER_00357]. Conversely, concurrent calls to OpenKeyValueStorage[SWS_PER_00052] and OpenFileStorage[SWS_PER_00116] from other threads during the update likewise fail with kResourceBusy.
Interaction
If a new target configuration was installed at runtime by UCM and reread via ReloadPersistencyManifest[SWS_PER_00577], closed storages are updated via UpdatePersistency. If callbacks were previously registered via RegisterDataUpdateIndication[SWS_PER_00578] or RegisterApplicationDataUpdateCallback[SWS_PER_00356], they are invoked synchronously in the context of UpdatePersistency[SWS_PER_00578].
This usage note was generated automatically based on the AUTOSAR specification R25-11.
no_rollback_semantics Returned if the available physical storage space is insufficient for the update.
kTooManyFiles
rollback_semantics Returned if the files added during the update of any File Storage would exceed the configured PersistencyFileStorageInterface.maxNumberOfFiles.
kQuotaExceeded
rollback_semantics Returned if the update would exceed the configured PersistencyCommon.MaximumAllowedSize of any Key- Value Storage or File Storage.
kAuthentication-Failed
rollback_semantics Returned if calculating or checking the MAC of stored data fails.
Request a governed re-review of this record. The record is not changed immediately.
gemini-3.8-flash-low· 2026-10-13 · German original