namespace ara::per

usar

La función síncrona CheckForManifestUpdate de la cabecera ara/per/update.h comprueba en el espacio de nombres ara::per si existen actualizaciones de la Persistency Target Configuration [SWS_PER_00576]. Sirve para detectar modificaciones de configuración introducidas por el Update and Configuration Management (UCM) mientras la aplicación adaptativa que utiliza Persistency ya está en ejecución [SWS_PER_00576]. La función no acepta parámetros y devuelve un ara::core::Result<bool>: true si la configuración se ha actualizado desde la última lectura, o false si ha permanecido inalterada [SWS_PER_00576].

Tratamiento de errores y concurrencia

La función está declarada como noexcept y es segura frente a excepciones (exception safe), pero no segura para hilos (not thread-safe) [SWS_PER_00576]. En caso de error, el resultado contiene errores específicos del fabricante o bien uno de los siguientes códigos de error [SWS_PER_00576]:

• kPhysicalStorageFailure: Se produce si el acceso a la memoria física falla durante la comprobación [SWS_PER_00576].
• kIntegrityCorrupted: Se produce si los datos almacenados no pueden leerse debido a que su integridad estructural está dañada [SWS_PER_00576].

Interacción

Si se detecta una actualización (valor de retorno true), la aplicación debe llamar a continuación a ara::per::ReloadPersistencyManifest para volver a leer efectivamente la Target Configuration modificada [SWS_PER_00576].

usar

La función sincrónica CleanUpPersistency de ara/per/update.h sirve para eliminar datos de respaldo (Backup Data) y otros datos no utilizados en todos los almacenamientos clave-valor y de archivos de una instancia [SWS_PER_00567]. No recibe parámetros y devuelve el resultado a través del tipo de retorno ara::core::Result<void> [SWS_PER_00567].

Concurrencia y restricciones

La función no es segura para subprocesos (not thread-safe) y requiere acceso exclusivo a todos los recursos de almacenamiento [SWS_PER_00567]. Si todavía está abierto un ara::per::SharedHandle de un almacenamiento clave-valor o de archivos, la llamada falla con kResourceBusy [SWS_PER_00567]. Del mismo modo, las operaciones en paralelo como UpdatePersistency, ResetPersistency, RecoverKeyValueStorage, ResetKeyValueStorage, RecoverAllFiles o ResetAllFiles conducen al código de error kResourceBusy [SWS_PER_00567].

Mientras se ejecuta CleanUpPersistency, las llamadas concurrentes para abrir almacenamientos mediante OpenKeyValueStorage [SWS_PER_00052] o OpenFileStorage [SWS_PER_00116], así como las funciones de recuperación y restablecimiento [SWS_PER_00333], [SWS_PER_00334], [SWS_PER_00335], [SWS_PER_00336], también fallan con kResourceBusy.

Manejo de errores

Para los errores ocurridos se aplica una semántica de reversión referida al almacenamiento [SWS_PER_00567]. Entre los posibles errores se encuentran, además de kResourceBusy:

• kPhysicalStorageFailure en caso de errores de acceso al medio de almacenamiento físico [SWS_PER_00567],
• kIntegrityCorrupted en caso de corrupción estructural de los datos almacenados [SWS_PER_00567],
• kValidationFailed en caso de fallo en la comprobación de la validez de los datos [SWS_PER_00567],
• kEncryptionFailed en caso de errores durante el cifrado o descifrado [SWS_PER_00567],
• kAuthenticationFailed en caso de fallo en el cálculo o la verificación del MAC [SWS_PER_00567],
• así como códigos de error específicos del fabricante [SWS_PER_00567].

La función síncrona ara::per::OpenFileStorage abre un almacenamiento de archivos para datos persistentes y lo pone a disposición a través de un handle de acceso compartido [SWS_PER_00116]. Como parámetro espera una referencia a un ara::core::InstanceSpecifier, el cual indica la ruta shortName de un prototipo de puerto tipado mediante un PersistencyFileStorageInterface. El valor de retorno es un ara::core::Result<ara::core::SharedHandle<FileStorage>> [SWS_PER_00116].

En cuanto a la concurrencia, la función está especificada como thread-safe y exception-safe [SWS_PER_00116]. Dado que múltiples hilos pueden acceder en paralelo a la misma instancia de almacenamiento de archivos, el almacenamiento físico no se cierra necesariamente cuando un único SharedHandle sale de su ámbito de validez. El cierre solo se produce cuando todos los handles que lo referencian han salido de ámbito (out-of-scope) [SWS_PER_00116].

En caso de error, el Result contiene códigos de error de la enumeración PerErrc o errores específicos del fabricante [SWS_PER_00116]:

• PerErrc::kResourceBusy: Se devuelve si al mismo tiempo se ejecutan operaciones administrativas como CleanUpPersistency, ResetPersistency, RecoverAllFiles o ResetAllFiles. Mientras UpdatePersistency está activo, este error se produce si la llamada se realiza fuera del callback registrado mediante RegisterApplicationDataUpdateCallback o con un identificador divergente [SWS_PER_00116], [SWS_PER_00356].
• Errores de configuración y de acceso: kStorageNotFound en caso de instancia no configurada, kPhysicalStorageFailure en caso de errores del almacenamiento físico, así como kIntegrityCorrupted, kValidationFailed, kEncryptionFailed y kAuthenticationFailed en caso de problemas de integridad, verificación o descifrado [SWS_PER_00116].
• Límites de capacidad en actualizaciones implícitas: kOutOfStorageSpace, kTooManyFiles o kQuotaExceeded [SWS_PER_00116].

En interacción con el módulo, un restablecimiento previo mediante ResetPersistency provoca que los almacenamientos de archivos eliminados se vuelvan a crear en la siguiente llamada a OpenFileStorage [SWS_PER_00358]. Si durante la apertura se actualizan datos, un callback de indicación registrado mediante RegisterDataUpdateIndication se invoca directamente en el contexto de OpenFileStorage [SWS_PER_00578].

Uso y ciclo de vida

La función síncrona OpenKeyValueStorage abre un almacenamiento de clave-valor y está especificada como thread-safe así como noexcept [SWS_PER_00052]. Como parámetro kvs se pasa un ara::core::InstanceSpecifier que referencia la ruta de un PortPrototype tipado mediante un PersistencyKeyValueStorageInterface. El retorno se produce como ara::core::Result<SharedHandle<KeyValueStorage>>. Dado que varios hilos pueden abrir simultáneamente el mismo almacenamiento, Persistency no cierra el almacenamiento físico hasta que todas las instancias de SharedHandle que lo referencian hayan salido de su ámbito de validez [SWS_PER_00052].

Tratamiento de errores y concurrencia

En caso de error, el Result proporciona códigos de error específicos del dominio de errores de Persistency [SWS_PER_00052]:

• PerErrc::kStorageNotFound: El identificador no coincide con ninguna interfaz configurada del ejecutable.
• PerErrc::kResourceBusy: Se produce si se ejecutan de forma concurrente CleanUpPersistency, ResetPersistency [SWS_PER_00358], RecoverKeyValueStorage o ResetKeyValueStorage para este almacenamiento. Durante UpdatePersistency, la llamada solo está permitida dentro del callback registrado mediante RegisterApplicationDataUpdateCallback con el identificador de instancia allí pasado [SWS_PER_00356].
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed y PerErrc::kAuthenticationFailed en caso de defectos, errores de validación o criptográficos.
• PerErrc::kOutOfStorageSpace y PerErrc::kQuotaExceeded en caso de espacio de almacenamiento insuficiente o exceso de cuota durante una actualización implícita.

Interacción

Si todos los datos se eliminaron previamente mediante ResetPersistency, el almacenamiento se vuelve a crear automáticamente en la siguiente llamada a OpenKeyValueStorage [SWS_PER_00358]. Tras la apertura, las modificaciones no guardadas pueden restablecerse al estado de la apertura mediante DiscardPendingChanges [SWS_PER_00365]. Además, la apertura puede desencadenar la ejecución de callbacks que se registraron mediante RegisterDataUpdateIndication [SWS_PER_00578].

La función RecoverAllFiles lleva a cabo una restauración de un almacenamiento basado en archivos (File Storage), incluidos todos los archivos almacenados en él, cuando fallan las comprobaciones de redundancia [SWS_PER_00335]. La invocación se realiza de forma síncrona especificando el InstanceSpecifier para el prototipo de puerto configurado y devuelve un ara::core::Result<void> [SWS_PER_00335].

La restauración funciona según el principio de mejor esfuerzo (best effort): tras completarse, los archivos pueden presentar contenidos obsoletos, estar restablecidos a su estado inicial o perderse por completo [SWS_PER_00335]. Si falla el acceso al medio de almacenamiento (PerErrc::kPhysicalStorageFailure) o si el espacio de almacenamiento es insuficiente (PerErrc::kOutOfStorageSpace), no existe garantía de reversión (rollback) [SWS_PER_00335]. Si se produce un error en el cifrado (PerErrc::kEncryptionFailed), en la comprobación de integridad (PerErrc::kAuthenticationFailed) o en la limitación del tamaño de almacenamiento (PerErrc::kQuotaExceeded), se aplica la semántica de reversión [SWS_PER_00335]. Si el identificador no coincide con ninguna interfaz configurada, esto resulta en PerErrc::kStorageNotFound [SWS_PER_00335].

Aunque la función es segura para subprocesos, la ejecución falla con PerErrc::kResourceBusy mientras el almacenamiento esté abierto o exista un identificador compartido activo [SWS_PER_00335], [SWS_PER_00116]. Del mismo modo, las ejecuciones paralelas de ResetAllFiles [SWS_PER_00336] para el mismo almacenamiento, así como las operaciones de actualización global UpdatePersistency [SWS_PER_00357], ResetPersistency [SWS_PER_00358] y CleanUpPersistency [SWS_PER_00567], bloquean la llamada [SWS_PER_00335].

La función síncrona RecoverKeyValueStorage en el espacio de nombres ara::per sirve para restaurar un almacenamiento de clave-valor tras fallos en las comprobaciones de redundancia ([SWS_PER_00333]). Como parámetro kvs se pasa un ara::core::InstanceSpecifier que referencia la ruta ShortName de un PortPrototype correspondiente ([SWS_PER_00333]). La restauración se lleva a cabo según el principio del mejor esfuerzo (best-effort); tras el proceso, las claves pueden presentar valores obsoletos o iniciales, o haberse perdido por completo ([SWS_PER_00333]).

Aunque la función está especificada como segura frente a hilos, la ejecución falla con el código de error PerErrc::kResourceBusy si el almacenamiento de clave-valor en cuestión está abierto —es decir, si existe al menos un SharedHandle activo ([SWS_PER_00052], [SWS_PER_00333])—. El mismo error se produce si otros hilos llaman simultáneamente a funciones modificadoras: UpdatePersistency ([SWS_PER_00357]), CleanUpPersistency ([SWS_PER_00567]), ResetPersistency ([SWS_PER_00358]) o ResetKeyValueStorage ([SWS_PER_00334]). Durante la restauración, una llamada a OpenKeyValueStorage con kResourceBusy también falla ([SWS_PER_00052]).

El resultado se devuelve de forma síncrona como ara::core::Result<void>. Además de PerErrc::kResourceBusy, se definen los siguientes errores específicos ([SWS_PER_00333]):

• PerErrc::kStorageNotFound: el identificador pasado no coincide con ninguna interfaz configurada.
• PerErrc::kPhysicalStorageFailure: el acceso al almacenamiento físico falla (sin semántica de reversión).
• PerErrc::kOutOfStorageSpace: espacio de almacenamiento físico insuficiente para los datos restaurados (sin semántica de reversión).
• PerErrc::kQuotaExceeded: superación de la longitud máxima configurada (maximumAllowedSize).
• PerErrc::kEncryptionFailed y PerErrc::kAuthenticationFailed: error en el cifrado o en el cálculo de MAC.

La función RegisterRecoveryReportCallback en el espacio de nombres ara::per ([SWS_PER_00433]) sirve para registrar una rutina de retrollamada en el componente Persistency. Se utiliza en Adaptive Applications relacionadas con la seguridad para detectar medidas correctivas de Persistency relativas a la corrección de datos persistidos, así como a la fiabilidad del almacenamiento [SWS_PER_00433].

Parámetros y semántica de invocación

Como parámetro se pasa recoveryReportCallback, una std::function que es llamada por Persistency cuando se corrigen con éxito errores en los datos almacenados haciendo uso de la redundancia disponible [SWS_PER_00433]. A la retrollamada se le transmiten las siguientes informaciones de contexto [SWS_PER_00433]:

• storage: La ruta (shortName) del Key-Value Storage o File Storage afectado como ara::core::InstanceSpecifier.
• recoveryReportKind: El tipo de informe de recuperación (ara::per::RecoveryReportKind).
• reportedElements: Un vector de identificadores de los elementos afectados (ara::core::Vector<ara::core::String>).
• reportedInstances: Un vector de las instancias afectadas (ara::core::Vector<std::uint8_t>).

Tratamiento de errores y concurrencia

La función no devuelve ningún valor y está declarada como noexcept; se considera segura frente a excepciones (exception safe) [SWS_PER_00433]. No existen códigos de error propios [SWS_PER_00433]. En cuanto a la seguridad para subprocesos, la interfaz está clasificada como not thread-safe [SWS_PER_00433]. Por tanto, es probable que la llamada se realice típicamente en la fase de inicialización de la aplicación antes de iniciar accesos concurrentes al almacenamiento. Pregunta Q-e5b93ea58fb56a1c (abierta)

La función síncrona ReloadPersistencyManifest del espacio de nombres ara::per (declarada en #include "ara/per/update.h") vuelve a leer la configuración de destino (Target Configuration) de la persistencia [SWS_PER_00577]. Sirve para preparar actualizaciones de los Key-Value Storages y File Storages después de que el Update and Config Management (UCM) haya instalado una nueva configuración de destino durante el tiempo de ejecución de la Adaptive Application [SWS_PER_00577].

Normalmente, la aplicación comprueba previamente con CheckForManifestUpdate [SWS_PER_00576] si existe una actualización de configuración y, a continuación, llama a ReloadPersistencyManifest [SWS_PER_00576]. Sin embargo, la relectura aún no actualiza de inmediato los almacenamientos persistentes: los Storages solo se actualizan tras su cierre, ya sea al volver a abrirlos o mediante una llamada explícita a ara::per::UpdatePersistency [SWS_PER_00577]. Interpretación: Es de suponer que las áreas de almacenamiento ya abiertas no se cierren automáticamente mediante la llamada, por lo que la aplicación debe cerrarlas por sí misma o actualizarlas explícitamente. Pregunta Q-16f9dae418feb3fa (abierta)

La función no toma parámetros y devuelve un ara::core::Result<void> [SWS_PER_00577]. En caso de error, el resultado contiene errores específicos del fabricante o uno de los siguientes códigos de error con semántica de reversión (rollback) [SWS_PER_00577]:

• kPhysicalStorageFailure: Se produce si falla el acceso al almacenamiento físico durante la operación de lectura [SWS_PER_00577].
• kIntegrityCorrupted: Se produce si los datos almacenados no se pueden leer debido a una integridad estructural dañada [SWS_PER_00577].

En cuanto a la concurrencia, la función está especificada como no segura para subprocesos (not thread-safe), pero declarada como segura frente a excepciones (exception safe) y noexcept [SWS_PER_00577]. Por lo tanto, las llamadas paralelas deben sincronizarse del lado de la aplicación.

La función ResetAllFiles restablece un File Storage de forma síncrona a su estado de entrega inicial conforme a la Target Configuration actual [SWS_PER_00336]. Tras una ejecución correcta, el almacenamiento contiene exclusivamente los archivos allí definidos con sus contenidos originales, como si hubiera sido instalado de nuevo [SWS_PER_00336].

Uso y concurrencia: a través del parámetro fs se pasa el identificador de instancia de un PortPrototype tipificado mediante PersistencyFileStorageInterface [SWS_PER_00336]. Aunque la función está especificada como thread-safe y exception safe, presupone un acceso exclusivo al almacenamiento: si el almacenamiento está actualmente abierto (por ejemplo, a través de un SharedHandle activo procedente de OpenFileStorage [SWS_PER_00116]) o se modifica de forma paralela mediante UpdatePersistency [SWS_PER_00357], CleanUpPersistency [SWS_PER_00567], ResetPersistency [SWS_PER_00358], RecoverAllFiles [SWS_PER_00335] o una llamada adicional a ResetAllFiles, la ejecución falla [SWS_PER_00336].

Tratamiento de errores: la función devuelve un ara::core::Result<void> [SWS_PER_00336]. Los posibles códigos de error de PerErrc son:

• kResourceBusy: el almacenamiento de archivos está abierto o se está modificando en paralelo (semántica de reversión) [SWS_PER_00336].
• kStorageNotFound: el identificador no coincide con ninguna interfaz configurada para el ejecutable [SWS_PER_00336].
• kPhysicalStorageFailure o kOutOfStorageSpace: error físico de almacenamiento o espacio de almacenamiento insuficiente (sin semántica de reversión) [SWS_PER_00336].
• kEncryptionFailed o kAuthenticationFailed: error durante el cifrado o el cálculo del MAC (semántica de reversión) [SWS_PER_00336].

Interacción: tras el restablecimiento, los archivos recuperados poseen en las consultas de estado el estado FileCreationState::kCreatedDuringReset [SWS_PER_00435] así como FileModificationState::kModifiedDuringReset [SWS_PER_00436].

La función síncrona ResetKeyValueStorage restablece un Key-Value Storage específico a su estado inicial [SWS_PER_00334]. Tras una ejecución correcta, el almacenamiento contiene exclusivamente aquellos pares clave-valor con sus valores iniciales que se proporcionaron a través de la Target Configuration; a partir de ese momento, el almacenamiento se comporta como si se hubiera instalado de nuevo a partir de la configuración actual [SWS_PER_00334]. Como parámetro se pasa la ruta de kvs como ara::core::InstanceSpecifier, la cual referencia el PortPrototype de una PersistencyKeyValueStorageInterface configurada [SWS_PER_00334].

La función está especificada como thread-safe y exception safe, pero está sujeta a estrictas condiciones de concurrencia relativas a almacenamientos abiertos y operaciones globales de persistencia [SWS_PER_00334]:

• La llamada falla con PerErrc::kResourceBusy si el Key-Value Storage en cuestión está abierto actualmente (es decir, si todavía existe un SharedHandle, véase [SWS_PER_00052]) o si se ejecuta simultáneamente una restauración mediante RecoverKeyValueStorage [SWS_PER_00333] en el mismo almacenamiento [SWS_PER_00334].
• Asimismo, conducen a kResourceBusy la ejecución paralela de las operaciones globales UpdatePersistency [SWS_PER_00357], CleanUpPersistency [SWS_PER_00567], ResetPersistency [SWS_PER_00358] o una llamada concurrente a ResetKeyValueStorage en otro hilo [SWS_PER_00334].

Como resultado, la función devuelve un ara::core::Result<void> [SWS_PER_00334]. En caso de error, además de kResourceBusy, se producen los siguientes códigos de error específicos: PerErrc::kStorageNotFound (InstanceSpecifier no válido), PerErrc::kPhysicalStorageFailure (error de acceso al medio de almacenamiento, sin semántica de reversión), PerErrc::kOutOfStorageSpace (espacio de almacenamiento insuficiente para valores iniciales, sin semántica de reversión), PerErrc::kEncryptionFailed (error de cifrado), así como PerErrc::kAuthenticationFailed (error en el cálculo de MAC) [SWS_PER_00334].

usar

La función síncrona ResetPersistency ([SWS_PER_00358]) de la cabecera ara/per/update.h sirve para el restablecimiento completo de todos los Key-Value Storages y File Storages de una aplicación. Al invocarla, se borran sin excepción todos los contenidos persistentes. Los almacenamientos en sí no se crean de nuevo de forma inmediata, sino únicamente al producirse la siguiente llamada a ara::per::OpenKeyValueStorage ([SWS_PER_00052]) o ara::per::OpenFileStorage ([SWS_PER_00116]). Los archivos que se proporcionan de nuevo tras el restablecimiento reciben el estado de creación FileCreationState::kCreatedDuringInstallation ([SWS_PER_00435]).

Manejo de errores

Como valor de retorno, la función proporciona un ara::core::Result<void> ([SWS_PER_00358]). Si el acceso al soporte de almacenamiento físico falla durante la operación, la función devuelve kPhysicalStorageFailure sin semántica de reversión (rollback). En caso de que haya recursos persistentes ocupados o se estén modificando en paralelo, la llamada se cancela con kResourceBusy y semántica activa de reversión ([SWS_PER_00358]). Además, pueden producirse errores específicos del fabricante.

Concurrencia y restricciones

La interfaz está declarada como exception safe, pero clasificada explícitamente como not thread-safe ([SWS_PER_00358]). Falla con kResourceBusy tan pronto como:

• ya se estén ejecutando operaciones globales como UpdatePersistency ([SWS_PER_00357]) o CleanUpPersistency ([SWS_PER_00567]),
• un almacenamiento individual se esté procesando en paralelo a través de RecoverKeyValueStorage, ResetKeyValueStorage, RecoverAllFiles ([SWS_PER_00335]) o ResetAllFiles ([SWS_PER_00336]),
• o aún exista al menos un SharedHandle activo de un Key-Value Storage o File Storage ([SWS_PER_00358]).

Mientras ResetPersistency esté en ejecución, los intentos simultáneos de apertura mediante OpenKeyValueStorage ([SWS_PER_00052]) o OpenFileStorage ([SWS_PER_00116]) en otros hilos darán lugar igualmente a kResourceBusy.

usar

La función síncrona ara::per::UpdatePersistency ([SWS_PER_00357], encabezado ara/per/update.h) actualiza todos los Key-Value Storages y File Storages de una aplicación tras la instalación de una nueva configuración de destino. Sirve para actualizar los datos persistentes de una Adaptive Application durante la fase de verificación [SWS_PER_00357]. La función no toma parámetros de entrada y devuelve un ara::core::Result<void> [SWS_PER_00357].

Manejo de errores

En caso de error, el Result devuelto contiene un código de error específico o un error específico del fabricante [SWS_PER_00357]. Al respecto, se distingue entre operaciones con y sin semántica de rollback:

• Semántica de rollback: En caso de kIntegrityCorrupted, kValidationFailed, kEncryptionFailed, kAuthenticationFailed, kTooManyFiles (superación de maxNumberOfFiles), kQuotaExceeded (superación de MaximumAllowedSize) así como kResourceBusy, se revierten los cambios realizados [SWS_PER_00357].
• Sin semántica de rollback: En caso de errores de almacenamiento físico (kPhysicalStorageFailure) así como espacio de almacenamiento físico insuficiente (kOutOfStorageSpace), no se garantiza el rollback [SWS_PER_00357].

Concurrencia y restricciones

La función está especificada como segura ante excepciones (exception safe), pero expresamente como no segura para subprocesos (not thread-safe) [SWS_PER_00357]. Una llamada falla con kResourceBusy en cuanto un SharedHandle de un Key-Value Storage o File Storage sigue en uso o se ejecutan en paralelo funciones de mantenimiento como CleanUpPersistency [SWS_PER_00567], ResetPersistency [SWS_PER_00358], RecoverKeyValueStorage [SWS_PER_00333], ResetKeyValueStorage [SWS_PER_00334], RecoverAllFiles [SWS_PER_00335] o ResetAllFiles [SWS_PER_00336] [SWS_PER_00357]. A la inversa, las llamadas simultáneas a OpenKeyValueStorage [SWS_PER_00052] y OpenFileStorage [SWS_PER_00116] desde otros hilos durante la actualización también fallan con kResourceBusy.

Interacción

Si UCM instaló una nueva configuración de destino durante el funcionamiento y esta se leyó de nuevo a través de ReloadPersistencyManifest [SWS_PER_00577], los almacenamientos cerrados se actualizan mediante UpdatePersistency. Si previamente se registraron callbacks a través de RegisterDataUpdateIndication [SWS_PER_00578] o RegisterApplicationDataUpdateCallback [SWS_PER_00356], su invocación se realiza de forma síncrona en el contexto de UpdatePersistency [SWS_PER_00578].