classe ara::per::KeyValueStorage

Utilização e semântica

A função-membro síncrona DiscardPendingChanges da classe ara::per::KeyValueStorage ([SWS_PER_00365]) é disponibilizada através do cabeçalho ara/per/key_value_storage.h. Ela não recebe parâmetros e retorna um ara::core::Result<void>. Sua finalidade é o descarte de todas as alterações pendentes na instância de key-value storage acumuladas desde a última chamada de SyncToStorage ou desde a abertura por meio de OpenKeyValueStorage() [SWS_PER_00365].

Interação e comportamento transacional

Operações de escrita como SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047] e RemoveAllKeys [SWS_PER_00048] estão sujeitas a uma semântica transacional. Suas alterações são gravadas de forma permanente no meio de armazenamento físico apenas mediante a chamada de SyncToStorage [SWS_PER_00049]. Por meio de DiscardPendingChanges, essas modificações não salvas são revertidas, de modo que consultas via GetCurrentValueSize também voltem a refletir o estado inicial transacional anterior [SWS_PER_00554].

Tratamento de erros e simultaneidade

Em caso de erro, o resultado contém um erro específico do fabricante ou um código de erro de PerErrc com semântica de reversão definida [SWS_PER_00365]:

• PerErrc::kIllegalWriteAccess: se o armazenamento for protegido contra escrita ou se, na configuração Write-Only-Once, a chave já existir.
• PerErrc::kPhysicalStorageFailure: se o acesso ao meio de armazenamento físico falhar.
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed ou PerErrc::kAuthenticationFailed: em caso de perda de integridade, erros de validação, erros de decodificação/descriptografia ou falha na verificação de MAC.

O método está declarado como noexcept, seguro contra exceções (exception safe) e seguro para threads (thread-safe) [SWS_PER_00365]. A execução pode, contudo, ser retardada se, em paralelo em outras threads, chamadas de SyncToStorage, SetValue, RemoveKey, RemoveAllKeys, ResetKey ou RecoverKey estiverem ativas [SWS_PER_00365] [SWS_PER_00426] [SWS_PER_00427].

O método síncrono KeyExists da classe ara::per::KeyValueStorage verifica se um determinado par chave-valor existe no armazenamento [SWS_PER_00043]. Como parâmetro de entrada, é transmitida a chave a verificar key do tipo ara::core::StringView [SWS_PER_00043]. O valor de retorno é um ara::core::Result<bool> que contém true se a chave tiver sido localizada e, caso contrário, false [SWS_PER_00043]. A função está declarada como const bem como noexcept e é segura contra exceções (exception safe) [SWS_PER_00043].

No que diz respeito à semântica e à concorrência, KeyExists opera com base em transações: reflete o estado atual da transação e não forçosamente o armazenamento físico [SWS_PER_00043]. Embora a execução seja segura para threads (thread-safe), o resultado fornecido só é preciso se não forem adicionados ou eliminados pares chave-valor em simultâneo [SWS_PER_00043]. Se, por exemplo, o par for removido noutra thread imediatamente após o retorno de true, o resultado perde a sua validade [SWS_PER_00043].

Em caso de erro, o Result contém um código de erro específico [SWS_PER_00043]:

• StorageFailure: erro no acesso ao armazenamento físico [SWS_PER_00043].
• PerErrc::kIntegrityCorrupted: os dados armazenados não podem ser lidos devido a integridade estrutural comprometida [SWS_PER_00043].
• PerErrc::kValidationFailed: A validade dos dados armazenados não pode ser garantida [SWS_PER_00043].
• PerErrc::kEncryptionFailed: a desencriptação dos dados falha [SWS_PER_00043].
• PerErrc::kAuthenticationFailed: a verificação do MAC falha [SWS_PER_00043].
• Erros específicos do fabricante (vendor specific error) também podem ser devolvidos [SWS_PER_00043].

O método síncrono RecoverKey da classe ara::per::KeyValueStorage serve para o restauro best-effort de um par chave-valor individual quando as verificações internas de redundância falham [SWS_PER_00427]. Ele recebe o identificador da chave através do parâmetro key como ara::core::StringView e comunica o sucesso ou erro através de um ara::core::Result<void> [SWS_PER_00427]. Após o restauro, o par pode apresentar conteúdos obsoletos ou valores iniciais, ou perder-se completamente [SWS_PER_00427].

Se ocorrer um erro, o resultado fornece códigos de erro específicos de PerErrc ou erros específicos do fabricante [SWS_PER_00427]:

• kKeyNotFound: a chave especificada não existe no armazenamento [SWS_PER_00427].
• kIllegalWriteAccess: O armazenamento está configurado como só de leitura (read-only) [SWS_PER_00427].
• kPhysicalStorageFailure: o acesso ao armazenamento físico falhou [SWS_PER_00427].
• kIntegrityCorrupted: Danos estruturais de integridade impedem a escrita de dados [SWS_PER_00427].
• kEncryptionFailed ou kAuthenticationFailed: A encriptação, desencriptação ou validação MAC falha [SWS_PER_00427].
• kOutOfStorageSpace ou kQuotaExceeded: O armazenamento físico disponível não é suficiente ou o tamanho máximo configurado é excedido [SWS_PER_00427].

A operação está especificada como thread-safe e exception-safe [SWS_PER_00427]. As chamadas podem, contudo, ser atrasadas se forem executadas em paralelo ações a nível de todo o armazenamento, como RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049] ou DiscardPendingChanges [SWS_PER_00365] [SWS_PER_00427]. Da mesma forma, chamadas simultâneas de SetValue [SWS_PER_00046], GetValue [SWS_PER_00044], GetCurrentValueSize [SWS_PER_00554], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426] ou novamente RecoverKey para a mesma chave causam atrasos [SWS_PER_00427]. Ao contrário de ResetKey [SWS_PER_00426], que repõe a entrada no seu estado de fornecimento, RecoverKey tenta uma recuperação de dados [SWS_PER_00427].

Uso e semântica transacional

O método RemoveAllKeys da classe ara::per::KeyValueStorage remove todos os pares chave-valor e seus conteúdos associados do armazenamento [SWS_PER_00048]. A função é chamada de forma síncrona, não possui parâmetros de passagem e é especificada com noexcept [SWS_PER_00048]. A operação segue uma semântica transacional: a exclusão de todas as chaves só se torna permanente no armazenamento físico assim que SyncToStorage [SWS_PER_00049] for chamado subsequentemente [SWS_PER_00048]. Dentro da transação em andamento, operações de leitura como GetValue [SWS_PER_00332] ou consultas de tamanho via GetCurrentValueSize [SWS_PER_00554] refletem imediatamente o estado esvaziado [SWS_PER_00044].

Tratamento de erros

Como valor de retorno é utilizado ara::core::Result<void> [SWS_PER_00048]. Se ocorrer um erro, aplica-se uma semântica de rollback [SWS_PER_00048]. Entre os possíveis erros estão:

• violação de acesso em armazenamento configurado como somente leitura (interpretação: isto provavelmente deve corresponder ao código de erro PerErrc::kIllegalWrite) [SWS_PER_00048], Pergunta Q-a820d779e19ac5c9 (aberta)
• PerErrc::kPhysicalStorageFailure em caso de erros no acesso à mídia de armazenamento física [SWS_PER_00048],
• PerErrc::kIntegrityCorrupted em caso de integridade estrutural de dados corrompida [SWS_PER_00048],
• PerErrc::kEncryptionFailed bem como PerErrc::kAuthenticationFailed em caso de falhas na criptografia/descriptografia ou na verificação de MAC [SWS_PER_00048], além de erros específicos do fabricante.

Concorrência e interação

O método é classificado como thread-safe e exception safe [SWS_PER_00048]. A execução pode, no entanto, ser atrasada se chamadas de RemoveAllKeys, SyncToStorage [SWS_PER_00049], SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047], ResetKey [SWS_PER_00426] ou RecoverKey [SWS_PER_00427] estiverem ativas simultaneamente em outra thread [SWS_PER_00048].

A função-membro síncrona RemoveKey da classe ara::per::KeyValueStorage serve para remover uma chave e o valor associado do Key-Value Storage [SWS_PER_00047]. Recebe o identificador da chave a remover como ara::core::StringView através do parâmetro key e retorna um ara::core::Result<void> [SWS_PER_00047].

A operação está sujeita a uma semântica transacional: as alterações não se tornam imediatamente persistentes no armazenamento físico, tornando-se efetivas apenas quando SyncToStorage é explicitamente chamado [SWS_PER_00047], o qual sincroniza os pares chave-valor alterados [SWS_PER_00049]. Alterações pendentes podem ser descartadas antes da sincronização com DiscardPendingChanges [SWS_PER_00365]. Acessos de leitura como GetValue [SWS_PER_00044], [SWS_PER_00332] ou GetCurrentValueSize [SWS_PER_00554] operam igualmente sobre o estado transacional e refletem a eliminação de imediato.

No que diz respeito à concorrência, o método está especificado como seguro para threads (thread-safe) e seguro contra exceções (exception safe) [SWS_PER_00047]. Uma chamada pode ser atrasada se RemoveAllKeys, SyncToStorage ou DiscardPendingChanges forem executados em paralelo noutra thread, ou se operações como SetValue, GetValue, GetCurrentValueSize, RemoveKey, RecoverKey ou ResetKey acederem ao mesmo par chave-valor em simultâneo [SWS_PER_00047].

Se ocorrer um erro durante a execução, aplica-se uma semântica de reversão e o objeto Result retornado contém um código de erro [SWS_PER_00047]:

• PerErrc::kKeyNotFound: a chave especificada não existe no armazenamento [SWS_PER_00047].
• PerErrc::kIllegalWriteAccess: o Key-Value Storage está configurado como apenas de leitura (read-only) [SWS_PER_00047].
• PerErrc::kPhysicalStorageFailure: o acesso ao suporte de armazenamento físico falhou [SWS_PER_00047].
• PerErrc::kIntegrityCorrupted: a escrita falha devido a integridade estrutural corrompida [SWS_PER_00047].
• PerErrc::kEncryptionFailed ou PerErrc::kAuthenticationFailed: a encriptação ou desencriptação falha, ou o cálculo/verificação do MAC está com erro [SWS_PER_00047].

usar

O método síncrono ResetKey repõe um par chave-valor individual numa instância de ara::per::KeyValueStorage para o seu valor inicial [SWS_PER_00426]. É transmitido como parâmetro o identificador key como ara::core::StringView [SWS_PER_00426]. Se a chave não existir atualmente no armazenamento, ela é criada de novo. Em ambos os casos, o estado da entrada corresponde subsequentemente ao de uma nova instalação a partir da Target Configuration atual [SWS_PER_00426]. A função é declarada como noexcept e devolve um ara::core::Result<void> [SWS_PER_00426].

Tratamento de erros

Se ocorrer um erro durante a execução, o objeto de resultado fornece um código de erro correspondente [SWS_PER_00426]:

• PerErrc::kInitValueNotAvailable: Quando não está definido nenhum valor inicial para a chave nem no Application Design nem na Target Configuration (semântica de rollback) [SWS_PER_00426].
• kIllegalWrite: Quando o Key-Value Storage está configurado como só de leitura (read-only) [SWS_PER_00426].
• PerErrc::kPhysicalStorageFailure ou PerErrc::kOutOfStorageSpace: Em caso de erros de acesso ao armazenamento físico ou espaço de armazenamento insuficiente (sem semântica de rollback) [SWS_PER_00426].
• PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed ou PerErrc::kQuotaExceeded: Em caso de violações de integridade, erros de criptografia e autenticação ou excesso do AllowedSize configurado (cada um com semântica de rollback) [SWS_PER_00426].

Concorrência e interação

A função é thread-safe e exception-safe [SWS_PER_00426]. No entanto, a chamada pode sofrer atrasos se operações a nível de todo o armazenamento, como RemoveAllKeys [SWS_PER_00048], SyncToStorage [SWS_PER_00049] ou DiscardPendingChanges [SWS_PER_00365], estiverem ativas em paralelo a partir de outra thread. Do mesmo modo, acessos concorrentes à mesma chave atravé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] ou um outro ResetKey levam a atrasos [SWS_PER_00426].

O método síncrono SyncToStorage da classe ara::per::KeyValueStorage escreve permanentemente no armazenamento físico os pares chave-valor alterados a partir do buffer de memória [SWS_PER_00049]. Não recebe parâmetros e retorna um ara::core::Result<void>, está declarado como noexcept, bem como especificado como seguro contra exceções e thread-safe [SWS_PER_00049].

Interação e semântica transacional

Operações modificadoras como SetValue [SWS_PER_00046], RemoveKey [SWS_PER_00047] e RemoveAllKeys [SWS_PER_00048] utilizam semântica transacional. As suas alterações só se tornam efetivas com a chamada de SyncToStorage [SWS_PER_00046]. Caso as modificações pendentes devam ser descartadas antes da escrita, pode ser chamado alternativamente DiscardPendingChanges [SWS_PER_00365].

simultaneidade

Embora a função seja thread-safe, a execução pode ser atrasada se estiverem ativas operações como SetValue, RemoveKey, RemoveAllKeys, DiscardPendingChanges, RecoverKey ou ResetKey em paralelo noutra thread [SWS_PER_00049].

Tratamento de erros

Se a sincronização falhar, o Result fornece um código de erro [SWS_PER_00049]:

• Erros com semântica de reversão (as alterações são revertidas): PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed, PerErrc::kQuotaExceeded, bem como PerErrc::kIllegalWrite [SWS_PER_00049].
• Erros sem semântica de reversão: PerErrc::kPhysicalStorageFailure em erros de acesso físico e PerErrc::kOutOfStorageSpace em caso de espaço de armazenamento insuficiente [SWS_PER_00049].
• Erros de configuração: código de erro Access se o armazenamento estiver configurado como read-only ou, no caso de write-only-once, se a chave já existir [SWS_PER_00049].