namespace ara::per

usar

A função síncrona CheckForManifestUpdate do cabeçalho ara/per/update.h verifica no namespace ara::per se existem atualizações da Persistency Target Configuration [SWS_PER_00576]. Ela serve para detectar alterações de configuração que foram aplicadas pelo Update and Configuration Management (UCM) enquanto a Adaptive Application que utiliza Persistency já está em execução [SWS_PER_00576]. A função não recebe parâmetros e retorna um ara::core::Result<bool>: true se a configuração tiver sido atualizada desde a última leitura, ou false se tiver permanecido inalterada [SWS_PER_00576].

Tratamento de erros e simultaneidade

A função é declarada como noexcept e segura contra exceções (exception safe), mas não thread-safe (not thread-safe) [SWS_PER_00576]. Em caso de erro, o resultado contém erros específicos do fornecedor ou um dos seguintes códigos de erro [SWS_PER_00576]:

• kPhysicalStorageFailure: Ocorre quando o acesso à memória física falha durante a verificação [SWS_PER_00576].
• kIntegrityCorrupted: Ocorre quando dados armazenados não podem ser lidos devido à integridade estrutural corrompida [SWS_PER_00576].

Interação

Se for detectada uma atualização (valor de retorno true), a aplicação deve, em seguida, chamar ara::per::ReloadPersistencyManifest para efetivamente reler a Target Configuration alterada [SWS_PER_00576].

usar

A função síncrona CleanUpPersistency de ara/per/update.h serve para a remoção de dados de backup (Backup Data) e outros dados não utilizados através de todos os Key-Value Storages e File Storages de uma instância [SWS_PER_00567]. Ela não recebe parâmetros e retorna o resultado por meio do tipo de retorno ara::core::Result<void> [SWS_PER_00567].

Simultaneidade e restrições

A função não é thread-safe (not thread-safe) e exige acesso exclusivo a todos os recursos de armazenamento [SWS_PER_00567]. Se um ara::per::SharedHandle de um Key-Value Storage ou File Storage ainda estiver aberto, a chamada falhará com kResourceBusy [SWS_PER_00567]. Da mesma forma, operações em execução paralela como UpdatePersistency, ResetPersistency, RecoverKeyValueStorage, ResetKeyValueStorage, RecoverAllFiles ou ResetAllFiles levam ao código de erro kResourceBusy [SWS_PER_00567].

Enquanto CleanUpPersistency estiver sendo executado, chamadas concorrentes para a abertura de armazenamentos via OpenKeyValueStorage [SWS_PER_00052] ou OpenFileStorage [SWS_PER_00116], bem como funções de restauração e reset [SWS_PER_00333], [SWS_PER_00334], [SWS_PER_00335], [SWS_PER_00336], também falharão com kResourceBusy.

Tratamento de erros

Aplica-se uma semântica de rollback relativa ao armazenamento para erros ocorridos [SWS_PER_00567]. Entre os erros possíveis estão, além de kResourceBusy:

• kPhysicalStorageFailure em caso de erros no acesso à mídia de armazenamento física [SWS_PER_00567],
• kIntegrityCorrupted em caso de corrupção estrutural dos dados armazenados [SWS_PER_00567],
• kValidationFailed em caso de falha na verificação da validade dos dados [SWS_PER_00567],
• kEncryptionFailed em caso de erros durante a criptografia ou descriptografia [SWS_PER_00567],
• kAuthenticationFailed em caso de falha no cálculo ou na verificação do MAC [SWS_PER_00567],
• bem como códigos de erro específicos do fabricante [SWS_PER_00567].

A função síncrona ara::per::OpenFileStorage abre um armazenamento de ficheiros para dados persistentes e disponibiliza-o através de um handle de acesso partilhado [SWS_PER_00116]. Como parâmetro, espera uma referência para um ara::core::InstanceSpecifier, que indica o caminho shortName de um protótipo de porta tipado por um PersistencyFileStorageInterface. O valor de retorno é um ara::core::Result<ara::core::SharedHandle<FileStorage>> [SWS_PER_00116].

Quanto à concorrência, a função está especificada como thread-safe e exception-safe [SWS_PER_00116]. Como múltiplas threads podem aceder em paralelo à mesma instância de armazenamento de ficheiros, o armazenamento físico não é obrigatoriamente fechado quando um único SharedHandle sai do âmbito de validade. O fecho ocorre apenas quando todos os handles de referência tiverem saído do âmbito (out-of-scope) [SWS_PER_00116].

Em caso de erro, o Result contém códigos de erro da enumeração PerErrc ou erros específicos do fabricante [SWS_PER_00116]:

• PerErrc::kResourceBusy: é retornado quando são executadas simultaneamente operações administrativas como CleanUpPersistency, ResetPersistency, RecoverAllFiles ou ResetAllFiles. Enquanto UpdatePersistency estiver ativo, este erro ocorre caso a chamada se realize fora do callback registado através de RegisterApplicationDataUpdateCallback ou com um identificador divergente [SWS_PER_00116], [SWS_PER_00356].
• Erros de configuração e de acesso: kStorageNotFound em caso de instância não configurada, kPhysicalStorageFailure em caso de erros do armazenamento físico, bem como kIntegrityCorrupted, kValidationFailed, kEncryptionFailed e kAuthenticationFailed em caso de problemas de integridade, verificação ou desencriptação [SWS_PER_00116].
• Limites de capacidade em atualizações implícitas: kOutOfStorageSpace, kTooManyFiles ou kQuotaExceeded [SWS_PER_00116].

Na interação com o módulo, uma reposição prévia por meio de ResetPersistency faz com que os armazenamentos de ficheiros eliminados sejam recriados na próxima chamada de OpenFileStorage [SWS_PER_00358]. Se forem atualizados dados durante a abertura, um callback de indicação registado através de RegisterDataUpdateIndication é chamado diretamente no contexto de OpenFileStorage [SWS_PER_00578].

Utilização e ciclo de vida

A função síncrona OpenKeyValueStorage abre um armazenamento de chave-valor e está especificada como thread-safe, bem como noexcept [SWS_PER_00052]. Como parâmetro kvs é passado um ara::core::InstanceSpecifier que referencia o caminho de um PortPrototype tipado por um PersistencyKeyValueStorageInterface. O retorno ocorre como ara::core::Result<SharedHandle<KeyValueStorage>>. Como múltiplas threads podem abrir o mesmo armazenamento concorrentemente, o Persistency só fecha o armazenamento físico quando todas as instâncias de SharedHandle que o referenciam tiverem saído do seu âmbito de validade [SWS_PER_00052].

Tratamento de erros e simultaneidade

Em caso de erro, o Result fornece códigos de erro específicos do domínio de erros do Persistency [SWS_PER_00052]:

• PerErrc::kStorageNotFound: o identificador não corresponde a nenhuma interface configurada do Executable.
• PerErrc::kResourceBusy: ocorre se CleanUpPersistency, ResetPersistency [SWS_PER_00358], RecoverKeyValueStorage ou ResetKeyValueStorage forem executados concorrentemente para este armazenamento. Durante UpdatePersistency, a chamada só é permitida dentro do callback registado através de RegisterApplicationDataUpdateCallback com o identificador de instância ali passado [SWS_PER_00356].
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed e PerErrc::kAuthenticationFailed em caso de anomalias, erros de validação ou de criptografia.
• PerErrc::kOutOfStorageSpace e PerErrc::kQuotaExceeded em caso de espaço de armazenamento insuficiente ou excesso de quota durante uma atualização implícita.

Interação

Se todos os dados tiverem sido eliminados previamente através de ResetPersistency, o armazenamento será recriado automaticamente na próxima chamada de OpenKeyValueStorage [SWS_PER_00358]. Após a abertura, modificações não guardadas podem ser repostas para o estado da abertura através de DiscardPendingChanges [SWS_PER_00365]. Além disso, a abertura pode desencadear a execução de callbacks registados através de RegisterDataUpdateIndication [SWS_PER_00578].

A função RecoverAllFiles realiza uma restauração de um armazenamento baseado em arquivos (File Storage), incluindo todos os arquivos nele contidos, quando as verificações de redundância falham [SWS_PER_00335]. A chamada é feita de forma síncrona com a especificação do InstanceSpecifier para o protótipo de porta configurado e retorna um ara::core::Result<void> [SWS_PER_00335].

A restauração opera no princípio de melhor esforço (best-effort): após a conclusão, os arquivos podem apresentar conteúdo desatualizado, ter sido redefinidos para seu estado inicial ou ser completamente perdidos [SWS_PER_00335]. Se o acesso ao meio de armazenamento falhar (PerErrc::kPhysicalStorageFailure) ou se o espaço de armazenamento for insuficiente (PerErrc::kOutOfStorageSpace), não haverá garantia de rollback [SWS_PER_00335]. Se ocorrer um erro durante a criptografia (PerErrc::kEncryptionFailed), verificação de integridade (PerErrc::kAuthenticationFailed) ou limitação de tamanho de armazenamento (PerErrc::kQuotaExceeded), a semântica de rollback entrará em ação [SWS_PER_00335]. Se o identificador não corresponder a nenhuma interface configurada, isso resultará em PerErrc::kStorageNotFound [SWS_PER_00335].

Embora a função seja thread-safe, a execução falhará com PerErrc::kResourceBusy se o armazenamento estiver aberto ou houver um handle compartilhado ativo [SWS_PER_00335], [SWS_PER_00116]. Da mesma forma, execuções concorrentes de ResetAllFiles [SWS_PER_00336] para o mesmo armazenamento, bem como as operações globais de atualização UpdatePersistency [SWS_PER_00357], ResetPersistency [SWS_PER_00358] e CleanUpPersistency [SWS_PER_00567], bloqueiam a chamada [SWS_PER_00335].

A função síncrona RecoverKeyValueStorage no espaço de nomes ara::per serve para restaurar um armazenamento de chave-valor após falhas nas verificações de redundância ([SWS_PER_00333]). É transmitido como parâmetro kvs um ara::core::InstanceSpecifier que referencia o caminho ShortName de um PortPrototype correspondente ([SWS_PER_00333]). O restauro ocorre de acordo com o princípio de melhor esforço (best-effort); após o processo, as chaves podem apresentar valores obsoletos ou iniciais, ou serem totalmente perdidas ([SWS_PER_00333]).

Embora a função esteja especificada como segura para threads, a execução falha com o código de erro PerErrc::kResourceBusy caso o respetivo armazenamento de chave-valor esteja aberto – ou seja, se existir pelo menos um SharedHandle ativo ([SWS_PER_00052], [SWS_PER_00333]). O mesmo erro ocorre se outras threads chamarem simultaneamente funções de modificação: UpdatePersistency ([SWS_PER_00357]), CleanUpPersistency ([SWS_PER_00567]), ResetPersistency ([SWS_PER_00358]) ou ResetKeyValueStorage ([SWS_PER_00334]). Durante o restauro, uma chamada de OpenKeyValueStorage também falha com kResourceBusy ([SWS_PER_00052]).

O resultado é devolvido de forma síncrona como ara::core::Result<void>. Além de PerErrc::kResourceBusy, estão definidos os seguintes erros específicos ([SWS_PER_00333]):

• PerErrc::kStorageNotFound: O identificador fornecido não corresponde a nenhuma interface configurada.
• PerErrc::kPhysicalStorageFailure: O acesso ao armazenamento físico falha (sem semântica de rollback).
• PerErrc::kOutOfStorageSpace: Espaço de armazenamento físico insuficiente para os dados restaurados (sem semântica de rollback).
• PerErrc::kQuotaExceeded: Excedido o comprimento máximo configurado (maximumAllowedSize).
• PerErrc::kEncryptionFailed e PerErrc::kAuthenticationFailed: Erro na encriptação ou no cálculo do MAC.

A função RegisterRecoveryReportCallback no namespace ara::per ([SWS_PER_00433]) serve para registar uma rotina de callback junto do componente Persistency. É utilizada em Adaptive Applications orientadas para a segurança a fim de detetar medidas de correção do Persistency relativas à exatidão de dados persistidos bem como à fiabilidade do armazenamento [SWS_PER_00433].

Parâmetros e semântica de chamada

Como parâmetro é transmitido recoveryReportCallback, uma std::function que é chamada pelo Persistency quando erros nos dados armazenados tiverem sido corrigidos com sucesso com recurso à redundância disponível [SWS_PER_00433]. São transmitidas ao callback as seguintes informações de contexto [SWS_PER_00433]:

• storage: o caminho (shortName) do Key-Value Storage ou File Storage afetado como ara::core::InstanceSpecifier.
• recoveryReportKind: o tipo de relatório de recuperação (ara::per::RecoveryReportKind).
• reportedElements: um vetor de identificadores dos elementos afetados (ara::core::Vector<ara::core::String>).
• reportedInstances: um vetor das instâncias afetadas (ara::core::Vector<std::uint8_t>).

Tratamento de erros e simultaneidade

A função não devolve qualquer valor e está declarada como noexcept; é considerada segura contra exceções (exception safe) [SWS_PER_00433]. Não existem códigos de erro próprios [SWS_PER_00433]. No que diz respeito à segurança de threads, a interface está classificada como not thread-safe [SWS_PER_00433]. A chamada deverá, portanto, ocorrer tipicamente na fase de inicialização da aplicação antes do início de acessos concorrentes ao armazenamento. Pergunta Q-e5b93ea58fb56a1c (aberta)

A função síncrona ReloadPersistencyManifest do namespace ara::per (declarada em #include "ara/per/update.h") relê a configuração de destino (Target Configuration) de Persistency [SWS_PER_00577]. Ela serve para preparar atualizações dos Key-Value Storages e File Storages após uma nova configuração de destino ter sido instalada pelo Update and Config Management (UCM) durante o tempo de execução da Adaptive Application [SWS_PER_00577].

Tipicamente, a aplicação verifica previamente com CheckForManifestUpdate [SWS_PER_00576] se existe uma atualização de configuração e chama, em seguida, ReloadPersistencyManifest [SWS_PER_00576]. A nova leitura, no entanto, ainda não atualiza imediatamente os armazenamentos persistentes: os Storages só são atualizados após o seu fechamento – seja na reabertura ou através de uma chamada explícita a ara::per::UpdatePersistency [SWS_PER_00577]. Interpretação: Presume-se que as áreas de armazenamento já abertas não sejam fechadas automaticamente pela chamada, de modo que a aplicação deve fechá-las por si própria ou atualizá-las explicitamente. Pergunta Q-16f9dae418feb3fa (aberta)

A função não recebe parâmetros e retorna um ara::core::Result<void> [SWS_PER_00577]. Em caso de erro, o resultado contém erros específicos do fornecedor ou um dos seguintes códigos de erro com semântica de rollback [SWS_PER_00577]:

• kPhysicalStorageFailure: Ocorre quando o acesso à memória física falha durante a operação de leitura [SWS_PER_00577].
• kIntegrityCorrupted: Ocorre quando dados armazenados não podem ser lidos devido à integridade estrutural corrompida [SWS_PER_00577].

Em relação à concorrência, a função é especificada como não thread-safe (not thread-safe), mas declarada como segura contra exceções (exception safe) e noexcept [SWS_PER_00577]. Chamadas paralelas devem, portanto, ser sincronizadas pelo lado da aplicação.

A função ResetAllFiles redefine um File Storage de forma síncrona para o seu estado de entrega inicial de acordo com a Target Configuration atual [SWS_PER_00336]. Após a execução bem-sucedida, o armazenamento conterá exclusivamente os arquivos ali definidos com seus conteúdos originais, como se tivesse acabado de ser instalado [SWS_PER_00336].

Uso e concorrência: por meio do parâmetro fs, é passado o identificador de instância de um PortPrototype tipado via PersistencyFileStorageInterface [SWS_PER_00336]. Embora a função seja especificada como thread-safe e exception safe, ela pressupõe acesso exclusivo ao armazenamento: se o armazenamento estiver aberto no momento (por exemplo, por meio de um SharedHandle ativo de OpenFileStorage [SWS_PER_00116]) ou for modificado em paralelo por UpdatePersistency [SWS_PER_00357], CleanUpPersistency [SWS_PER_00567], ResetPersistency [SWS_PER_00358], RecoverAllFiles [SWS_PER_00335] ou por outra chamada de ResetAllFiles, a execução falhará [SWS_PER_00336].

Tratamento de erros: a função retorna um ara::core::Result<void> [SWS_PER_00336]. Possíveis códigos de erro de PerErrc são:

• kResourceBusy: o armazenamento de arquivos está aberto ou está sendo modificado em paralelo (semântica de rollback) [SWS_PER_00336].
• kStorageNotFound: o identificador não corresponde a nenhuma interface configurada para o executável [SWS_PER_00336].
• kPhysicalStorageFailure ou kOutOfStorageSpace: erro físico de armazenamento ou espaço de armazenamento insuficiente (sem semântica de rollback) [SWS_PER_00336].
• kEncryptionFailed ou kAuthenticationFailed: erro na criptografia ou cálculo de MAC (semântica de rollback) [SWS_PER_00336].

Interação: após a redefinição, os arquivos restaurados têm o status FileCreationState::kCreatedDuringReset [SWS_PER_00435] e FileModificationState::kModifiedDuringReset [SWS_PER_00436] em consultas de estado.

A função síncrona ResetKeyValueStorage repõe um Key-Value-Storage específico para o seu estado inicial [SWS_PER_00334]. Após uma execução bem-sucedida, o armazenamento contém exclusivamente os pares chave-valor com os respetivos valores iniciais que foram disponibilizados através da Target Configuration; o armazenamento comporta-se depois como se tivesse acabado de ser instalado a partir da configuração atual [SWS_PER_00334]. Como parâmetro, é passado o caminho de kvs como ara::core::InstanceSpecifier, que referencia o PortPrototype de uma PersistencyKeyValueStorageInterface configurada [SWS_PER_00334].

A função está especificada como thread-safe e exception safe, mas está sujeita a condições de concorrência estritas relativas a armazenamentos abertos e operações globais de persistência [SWS_PER_00334]:

• A chamada falha com PerErrc::kResourceBusy se o respetivo Key-Value-Storage estiver atualmente aberto (ou seja, se ainda existir um SharedHandle, consulte [SWS_PER_00052]) ou se for executado em simultâneo um restauro através de RecoverKeyValueStorage [SWS_PER_00333] no mesmo armazenamento [SWS_PER_00334].
• Uma execução paralela das operações globais UpdatePersistency [SWS_PER_00357], CleanUpPersistency [SWS_PER_00567], ResetPersistency [SWS_PER_00358] ou uma chamada concorrente de ResetKeyValueStorage noutra thread também resulta em kResourceBusy [SWS_PER_00334].

Como resultado, a função fornece um ara::core::Result<void> [SWS_PER_00334]. Em caso de erro, além de kResourceBusy ocorrem os seguintes códigos de erro específicos: PerErrc::kStorageNotFound (InstanceSpecifier inválido), PerErrc::kPhysicalStorageFailure (erro de acesso ao suporte de armazenamento, sem semântica de rollback), PerErrc::kOutOfStorageSpace (espaço de armazenamento insuficiente para valores iniciais, sem semântica de rollback), PerErrc::kEncryptionFailed (erro de encriptação), bem como PerErrc::kAuthenticationFailed (erro no cálculo do MAC) [SWS_PER_00334].

usar

A função síncrona ResetPersistency ([SWS_PER_00358]) do cabeçalho ara/per/update.h destina-se à redefinição completa de todos os Key-Value Storages e File Storages de uma aplicação. Durante a chamada, todos os conteúdos persistentes são completamente excluídos. Os próprios armazenamentos não são recriados imediatamente, mas apenas na próxima chamada respectiva de ara::per::OpenKeyValueStorage ([SWS_PER_00052]) ou ara::per::OpenFileStorage ([SWS_PER_00116]). Arquivos disponibilizados novamente após o reset recebem o status de criação FileCreationState::kCreatedDuringInstallation ([SWS_PER_00435]).

Tratamento de erros

Como valor de retorno, a função fornece um ara::core::Result<void> ([SWS_PER_00358]). Se o acesso ao meio de armazenamento físico falhar durante a operação, a função retorna kPhysicalStorageFailure sem semântica de rollback. Se recursos persistentes estiverem ocupados ou forem modificados em paralelo, a chamada é cancelada com kResourceBusy e semântica de rollback ativa ([SWS_PER_00358]). Além disso, podem ocorrer erros específicos do fabricante.

Simultaneidade e restrições

A interface está declarada como exception safe, mas explicitamente classificada como not thread-safe ([SWS_PER_00358]). Ela falha com kResourceBusy assim que:

• já estiverem sendo executadas operações globais como UpdatePersistency ([SWS_PER_00357]) ou CleanUpPersistency ([SWS_PER_00567]),
• um armazenamento individual estiver sendo editado em paralelo por meio de RecoverKeyValueStorage, ResetKeyValueStorage, RecoverAllFiles ([SWS_PER_00335]) ou ResetAllFiles ([SWS_PER_00336]),
• ou ainda existir pelo menos um SharedHandle ativo de um Key-Value Storage ou File Storage ([SWS_PER_00358]).

Enquanto ResetPersistency estiver em execução, tentativas simultâneas de abertura por meio de OpenKeyValueStorage ([SWS_PER_00052]) ou OpenFileStorage ([SWS_PER_00116]) em outras threads também resultam em kResourceBusy.

usar

A função síncrona ara::per::UpdatePersistency ([SWS_PER_00357], cabeçalho ara/per/update.h) atualiza, após a instalação de uma nova configuração de destino, todos os key-value storages e file storages de uma aplicação. Ela serve para atualizar os dados persistentes de uma Adaptive Application durante a fase de verificação [SWS_PER_00357]. A função não aceita parâmetros de entrada e retorna um ara::core::Result<void> [SWS_PER_00357].

Tratamento de erros

Em caso de erro, o Result retornado contém um código de erro específico ou um erro específico do fabricante [SWS_PER_00357]. Diferencia-se, neste contexto, entre operações com e sem semântica de reversão (rollback):

• Semântica de reversão: em kIntegrityCorrupted, kValidationFailed, kEncryptionFailed, kAuthenticationFailed, kTooManyFiles (excesso de maxNumberOfFiles), kQuotaExceeded (excesso de MaximumAllowedSize), bem como kResourceBusy, as alterações efetuadas são revertidas [SWS_PER_00357].
• Sem semântica de reversão: em caso de falhas físicas de memória (kPhysicalStorageFailure), bem como de espaço de armazenamento físico insuficiente (kOutOfStorageSpace), nenhuma reversão é garantida [SWS_PER_00357].

Simultaneidade e restrições

A função está especificada como segura contra exceções (exception safe), mas expressamente como não segura para threads (not thread-safe) [SWS_PER_00357]. Uma chamada falha com kResourceBusy assim que um SharedHandle de um key-value storage ou file storage ainda estiver em uso ou funções de manutenção como CleanUpPersistency [SWS_PER_00567], ResetPersistency [SWS_PER_00358], RecoverKeyValueStorage [SWS_PER_00333], ResetKeyValueStorage [SWS_PER_00334], RecoverAllFiles [SWS_PER_00335] ou ResetAllFiles [SWS_PER_00336] forem executadas em paralelo [SWS_PER_00357]. Por outro lado, chamadas simultâneas de OpenKeyValueStorage [SWS_PER_00052] e OpenFileStorage [SWS_PER_00116] a partir de outras threads durante a atualização também falham com kResourceBusy.

Interação

Se uma nova configuração de destino foi instalada pelo UCM durante a operação contínua e lida novamente através de ReloadPersistencyManifest [SWS_PER_00577], os armazenamentos fechados são atualizados via UpdatePersistency. Se anteriormente foram registrados callbacks via RegisterDataUpdateIndication [SWS_PER_00578] ou RegisterApplicationDataUpdateCallback [SWS_PER_00356], sua chamada ocorre de forma síncrona no contexto de UpdatePersistency [SWS_PER_00578].