clase ara::per::KeyValueStorage

Uso y semántica

La función miembro síncrona DiscardPendingChanges de la clase ara::per::KeyValueStorage ([SWS_PER_00365]) se proporciona a través del encabezado ara/per/key_value_storage.h. No toma ningún parámetro y devuelve un ara::core::Result<void>. Su finalidad es descartar todos los cambios pendientes en la instancia de Key-Value Storage que se hayan acumulado desde la última llamada a SyncToStorage o desde la apertura mediante OpenKeyValueStorage() [SWS_PER_00365].

Interacción y comportamiento transaccional

Las operaciones de escritura como SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047] y RemoveAllKeys [SWS_PER_00048] están sujetas a una semántica transaccional. Sus modificaciones solo se escriben permanentemente en el soporte de almacenamiento físico mediante la llamada a SyncToStorage [SWS_PER_00049]. A través de DiscardPendingChanges, estas modificaciones no guardadas se revierten, de modo que las consultas mediante GetCurrentValueSize vuelven a reflejar también el estado inicial transaccional anterior [SWS_PER_00554].

Tratamiento de errores y concurrencia

En caso de error, el resultado contiene un error específico del fabricante o un código de error de PerErrc con semántica de rollback definida [SWS_PER_00365]:

• PerErrc::kIllegalWriteAccess: si el almacenamiento está protegido contra escritura o, en caso de configuración write-only-once, la clave ya existe.
• PerErrc::kPhysicalStorageFailure: si falla el acceso al medio de almacenamiento físico.
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed o PerErrc::kAuthenticationFailed: en caso de pérdida de integridad, errores de validación, errores de descifrado o comprobación MAC fallida.

El método está declarado como noexcept, seguro ante excepciones (exception safe) y seguro para subprocesos (thread-safe) [SWS_PER_00365]. No obstante, la ejecución puede retrasarse si en paralelo en otros hilos están activas llamadas a SyncToStorage, SetValue, RemoveKey, RemoveAllKeys, ResetKey o RecoverKey [SWS_PER_00365] [SWS_PER_00426] [SWS_PER_00427].

El método síncrono KeyExists de la clase ara::per::KeyValueStorage comprueba si un par clave-valor determinado existe en la memoria [SWS_PER_00043]. Como parámetro de entrada se pasa la clave que se va a comprobar key de tipo ara::core::StringView [SWS_PER_00043]. El valor de retorno es un ara::core::Result<bool> que contiene true si la clave pudo ser localizada y, en caso contrario, false [SWS_PER_00043]. La función está declarada como const, así como noexcept, y es segura frente a excepciones (exception safe) [SWS_PER_00043].

En cuanto a semántica y concurrencia, KeyExists opera de forma basada en transacciones: refleja el estado actual de la transacción y no necesariamente el almacenamiento físico [SWS_PER_00043]. Aunque la ejecución es segura para subprocesos (thread-safe), el resultado devuelto solo es preciso si no se añaden ni se eliminan pares clave-valor simultáneamente [SWS_PER_00043]. Por ejemplo, si el par se elimina en otro subproceso inmediatamente después de devolverse true, el resultado pierde su validez [SWS_PER_00043].

En caso de error, el Result contiene un código de error específico [SWS_PER_00043]:

• StorageFailure: error al acceder a la memoria física [SWS_PER_00043].
• PerErrc::kIntegrityCorrupted: los datos almacenados no pueden leerse debido a una vulneración de la integridad estructural [SWS_PER_00043].
• PerErrc::kValidationFailed: No se puede garantizar la validez de los datos almacenados [SWS_PER_00043].
• PerErrc::kEncryptionFailed: falla el descifrado de los datos [SWS_PER_00043].
• PerErrc::kAuthenticationFailed: falla la verificación del MAC [SWS_PER_00043].
• También se pueden devolver errores específicos del proveedor (vendor specific error) [SWS_PER_00043].

El método síncrono RecoverKey de la clase ara::per::KeyValueStorage sirve para la restauración por mejor esfuerzo (best-effort) de un par clave-valor individual cuando fallan las comprobaciones internas de redundancia [SWS_PER_00427]. Recibe el identificador de la clave a través del parámetro key como ara::core::StringView y notifica el éxito o el error mediante un ara::core::Result<void> [SWS_PER_00427]. Tras la restauración, el par puede presentar contenidos obsoletos o valores iniciales, o bien haberse perdido por completo [SWS_PER_00427].

Si se produce un error, el resultado proporciona códigos de error específicos de PerErrc o errores específicos del fabricante [SWS_PER_00427]:

• kKeyNotFound: la clave especificada no existe en el almacenamiento [SWS_PER_00427].
• kIllegalWriteAccess: el almacenamiento está configurado como de solo lectura (read-only) [SWS_PER_00427].
• kPhysicalStorageFailure: El acceso al almacenamiento físico ha fallado [SWS_PER_00427].
• kIntegrityCorrupted: daños en la integridad estructural impiden la escritura de datos [SWS_PER_00427].
• kEncryptionFailed o bien kAuthenticationFailed: falla el cifrado, el descifrado o la validación MAC [SWS_PER_00427].
• kOutOfStorageSpace o bien kQuotaExceeded: la memoria física disponible es insuficiente o se supera el tamaño máximo configurado [SWS_PER_00427].

La operación está especificada como thread-safe y exception-safe [SWS_PER_00427]. Sin embargo, las llamadas pueden demorarse si se ejecutan en paralelo acciones a nivel de almacenamiento completo como RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049] o DiscardPendingChanges [SWS_PER_00365] [SWS_PER_00427]. Asimismo, las llamadas simultáneas a SetValue [SWS_PER_00046], GetValue [SWS_PER_00044], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426] o de nuevo a RecoverKey para la misma clave provocan demoras [SWS_PER_00427]. A diferencia de ResetKey [SWS_PER_00426], que restablece la entrada a su estado de fábrica, RecoverKey intenta una recuperación de datos [SWS_PER_00427].

Uso y semántica de transacciones

El método RemoveAllKeys de la clase ara::per::KeyValueStorage elimina del almacenamiento todos los pares clave-valor y sus contenidos correspondientes [SWS_PER_00048]. La función se invoca de forma síncrona, no posee parámetros de transferencia y está especificada con noexcept [SWS_PER_00048]. La operación está sujeta a una semántica de transacciones: el borrado de todas las claves solo se hace efectivo de forma permanente en el almacenamiento físico en cuanto se invoca posteriormente SyncToStorage [SWS_PER_00049] [SWS_PER_00048]. Dentro de la transacción en curso, las operaciones de lectura como GetValue [SWS_PER_00332] o las consultas de tamaño mediante GetCurrentValueSize [SWS_PER_00554] reflejan de inmediato el estado vaciado [SWS_PER_00044].

Manejo de errores

Como valor de retorno sirve ara::core::Result<void> [SWS_PER_00048]. Si se produce un error, se aplica una semántica de reversión (rollback) [SWS_PER_00048]. Entre los posibles errores se incluyen:

• Violación de acceso en caso de almacenamiento configurado como de solo lectura (interpretación: esto debería corresponder al código de error PerErrc::kIllegalWrite) [SWS_PER_00048], Pregunta Q-a820d779e19ac5c9 (abierta)
• PerErrc::kPhysicalStorageFailure en caso de errores de acceso al medio de almacenamiento físico [SWS_PER_00048],
• PerErrc::kIntegrityCorrupted en caso de integridad de datos estructural dañada [SWS_PER_00048],
• PerErrc::kEncryptionFailed así como PerErrc::kAuthenticationFailed en caso de fallos del cifrado/descifrado o de la comprobación MAC [SWS_PER_00048], así como errores específicos del fabricante.

Concurrencia e interacción

El método está catalogado como thread-safe y exception safe [SWS_PER_00048]. No obstante, la ejecución puede retrasarse si en otro subproceso están activas al mismo tiempo invocaciones de RemoveAllKeys, SyncToStorage [SWS_PER_00049], SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426] o RecoverKey [SWS_PER_00427] [SWS_PER_00048].

La función miembro sincrónica RemoveKey de la clase ara::per::KeyValueStorage sirve para eliminar una clave y el valor asignado del Key-Value Storage [SWS_PER_00047]. Recibe el identificador de la clave que se va a eliminar como ara::core::StringView a través del parámetro key y devuelve un ara::core::Result<void> [SWS_PER_00047].

La operación está sujeta a una semántica transaccional: las modificaciones no se hacen persistentes de inmediato en el almacenamiento físico, sino que surten efecto únicamente cuando se llama explícitamente a SyncToStorage [SWS_PER_00047], el cual sincroniza los pares clave-valor modificados [SWS_PER_00049]. Las modificaciones pendientes se pueden descartar antes de la sincronización mediante DiscardPendingChanges [SWS_PER_00365]. Los accesos de lectura como GetValue [SWS_PER_00044], [SWS_PER_00332] o GetCurrentValueSize [SWS_PER_00554] operan igualmente sobre el estado de la transacción y reflejan la eliminación de forma inmediata.

En cuanto a la concurrencia, el método está especificado como seguro para subprocesos (thread-safe) y seguro frente a excepciones (exception safe) [SWS_PER_00047]. Una llamada puede demorarse si en paralelo se ejecutan RemoveAllKeys, SyncToStorage o DiscardPendingChanges en otro subproceso, o si simultáneamente operaciones tales como SetValue, GetValue, GetCurrentValueSize, RemoveKey, RecoverKey o ResetKey acceden al mismo par clave-valor [SWS_PER_00047].

Si se produce un error durante la ejecución, se aplica una semántica de reversión (rollback) y el objeto Result devuelto contiene un código de error [SWS_PER_00047]:

• PerErrc::kKeyNotFound: la clave especificada no existe en el almacenamiento [SWS_PER_00047].
• PerErrc::kIllegalWriteAccess: el Key-Value Storage está configurado como de solo lectura (read-only) [SWS_PER_00047].
• PerErrc::kPhysicalStorageFailure: ha fallado el acceso al medio de almacenamiento físico [SWS_PER_00047].
• PerErrc::kIntegrityCorrupted: la escritura falla debido a una integridad estructural dañada [SWS_PER_00047].
• PerErrc::kEncryptionFailed o bien PerErrc::kAuthenticationFailed: el cifrado o descifrado falla, o el cálculo/verificación del MAC es erróneo [SWS_PER_00047].

usar

El método síncrono ResetKey restablece un par clave-valor individual en una instancia de ara::per::KeyValueStorage a su valor inicial [SWS_PER_00426]. Como parámetro se pasa el identificador key como ara::core::StringView [SWS_PER_00426]. Si la clave no existe actualmente en el almacenamiento, se crea de nuevo. En ambos casos, el estado de la entrada corresponde posteriormente al de una nueva instalación a partir de la Target Configuration actual [SWS_PER_00426]. La función está declarada como noexcept y devuelve un ara::core::Result<void> [SWS_PER_00426].

Manejo de errores

Si se produce un error durante la ejecución, el objeto Result devuelve el correspondiente código de error [SWS_PER_00426]:

• PerErrc::kInitValueNotAvailable: si no se ha definido ningún valor inicial para la clave ni en el Application Design ni en la Target Configuration (semántica de reversión) [SWS_PER_00426].
• kIllegalWrite: si el Key-Value Storage está configurado como de solo lectura (read-only) [SWS_PER_00426].
• PerErrc::kPhysicalStorageFailure o PerErrc::kOutOfStorageSpace: en caso de errores de acceso físico al almacenamiento o de espacio de almacenamiento insuficiente (sin semántica de reversión) [SWS_PER_00426].
• PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed o PerErrc::kQuotaExceeded: en caso de violaciones de integridad, errores de criptografía y autenticación, o superación del AllowedSize configurado (en cada caso con semántica de reversión) [SWS_PER_00426].

Concurrencia e interacción

La función es thread-safe y exception-safe [SWS_PER_00426]. Sin embargo, la llamada se puede demorar si están activas en paralelo desde otro hilo operaciones a nivel de almacenamiento completo como RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049] o DiscardPendingChanges [SWS_PER_00365]. Del mismo modo, los accesos concurrentes a la misma clave a través de SetValue [SWS_PER_00046], GetValue [SWS_PER_00044] [SWS_PER_00332], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], RecoverKey [SWS_PER_00427] o un ResetKey adicional provocan demoras [SWS_PER_00426].

El método sincrónico SyncToStorage de la clase ara::per::KeyValueStorage escribe de forma permanente en el almacenamiento físico los pares clave-valor modificados procedentes del búfer de memoria [SWS_PER_00049]. No recibe ningún parámetro y devuelve un ara::core::Result<void>, está declarado como noexcept y especificado como seguro frente a excepciones y seguro para subprocesos (thread-safe) [SWS_PER_00049].

Interacción y semántica transaccional

Las operaciones de modificación tales como SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047] y RemoveAllKeys [SWS_PER_00048] emplean semántica transaccional. Sus modificaciones no surten efecto hasta la llamada a SyncToStorage [SWS_PER_00046]. Si se desean descartar las modificaciones pendientes antes de escribir, se puede invocar alternativamente DiscardPendingChanges [SWS_PER_00365].

concurrencia

Aunque la función es thread-safe, la ejecución puede retrasarse si en paralelo en otro hilo están activas operaciones como SetValue, RemoveKey, RemoveAllKeys, DiscardPendingChanges, RecoverKey o ResetKey [SWS_PER_00049].

Manejo de errores

Si la sincronización falla, el Result devuelve un código de error [SWS_PER_00049]:

• Errores con semántica de rollback (los cambios se revierten): PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed, PerErrc::kQuotaExceeded así como PerErrc::kIllegalWrite [SWS_PER_00049].
• Errores sin semántica de rollback: PerErrc::kPhysicalStorageFailure en caso de errores de acceso físico y PerErrc::kOutOfStorageSpace en caso de espacio de almacenamiento insuficiente [SWS_PER_00049].
• Errores de configuración: código de error Access si el almacenamiento está configurado como read-only o si, en caso de write-only-once, la clave ya existe [SWS_PER_00049].