classe ara::core::Result< void, E >

Utilização e contexto de chamada

A função-membro Bind da especialização ara::core::Result<void, E> de ara/core/result.h executa um cálculo subsequente em uma instância bem-sucedida sem valor de resultado [SWS_CORE_00870]. Se um valor estiver presente, o Callable f passado é chamado de forma síncrona e sem parâmetros. O Callable deve satisfazer a interface Result<XXX, E> f() ou XXX f(), sendo que XXX deve ser um tipo admissível para Result [SWS_CORE_00870]. Se o Callable fornecer um Result, o tipo de retorno corresponde a decltype(f()); se ele retornar diretamente XXX, o resultado é empacotado como Result<decltype(f()), E> [SWS_CORE_00870].

Tratamento de erros e simultaneidade

Se a instância não contiver nenhum valor, é retornado um novo Result<XXX, E> no qual o erro original é copiado [SWS_CORE_00870]. Interpretação: Neste caso, a execução do Callable f deverá ser omitida. Pergunta Q-6288a7106d2730c3 (aberta) Em relação à segurança de execução, a função é considerada not exception safe [SWS_CORE_00870]. A segurança de thread é condicional (conditional) e depende inteiramente da segurança de thread do Callable passado f [SWS_CORE_00870].

Interação com requisitos relacionados

Ao contrário das funções Result<T, E> primárias de [SWS_CORE_00768] e [SWS_CORE_00941], nas quais o Callable recebe o valor da instância via f(const T&), a presente sobrecarga [SWS_CORE_00870] vincula operações a resultados void e, portanto, espera um Callable sem parâmetros.

A função-membro EmplaceError da especialização ara::core::Result<void, E> constrói de forma síncrona um novo valor de erro diretamente in-place dentro da instância existente a partir dos argumentos passados args [SWS_CORE_00844]. A função de template disponibilizada através do arquivo de cabeçalho ara/core/result.h não possui valor de retorno e inicializa o objeto de erro do tipo E imediatamente no local [SWS_CORE_00844].

No que diz respeito ao tratamento de erros e à segurança contra exceções, a operação é classificada como condicionalmente segura contra exceções (conditionally exception safe) [SWS_CORE_00844]. Através do especificador noexcept(std::is_nothrow_constructible<E, Args...>::value), garante-se a isenção de exceções, desde que o tipo E possa ser construído com os tipos Args... sem exceção [SWS_CORE_00844].

Em relação a concorrência e condições de contorno, a função-membro é definida como não thread-safe (not thread-safe) [SWS_CORE_00844]. Se múltiplas threads acessarem concorrentemente a mesma instância de Result, presume-se que seja necessário um mecanismo de sincronização externo para evitar alterações de estado desordenadas. Pergunta Q-ffcb8ced860f6080 (aberta)

No contexto geral do módulo core, [SWS_CORE_00844] corresponde diretamente às demais variantes da mesma função: para o template primário ara::core::Result, o comportamento idêntico é especificado sob [SWS_CORE_00744], enquanto para tipos de referência ara::core::Result<T&, E> o requisito [SWS_CORE_00916] prescreve a mesma assinatura e semântica.

Utilização e contexto de chamada

A função-membro de template EmplaceValue pertence ao módulo core e é definida através do arquivo de cabeçalho #include "ara/core/result.h" para a especialização ara::core::Result<void, E> [SWS_CORE_00843]. O seu propósito é a criação ou definição direta de um novo valor na instância existente com base nos argumentos passados args [SWS_CORE_00843]. A execução ocorre de forma síncrona e não fornece nenhum valor de retorno (void) [SWS_CORE_00843]. Como o tipo de valor da especialização é void, a chamada transfere a instância para um estado de sucesso; como interpretação, a aceitação de args deverá servir primariamente para a compatibilidade genérica de assinatura com a classe de template primária. Pergunta Q-b53ca5908f2517fb (aberta)

Tratamento de erros e segurança de exceções

A função é declarada como noexcept e possui a especificação exception safe [SWS_CORE_00843]. Ela não retorna códigos de erro e não lança exceções. Se o objeto Result se encontrava anteriormente em um estado de erro, este é sobrescrito pela inserção do valor.

Simultaneidade e restrições

A operação é indicada como não thread-safe (not thread-safe) [SWS_CORE_00843]. No caso de acessos de leitura ou escrita potencialmente concorrentes à mesma instância de ara::core::Result, a sincronização externa pelo chamador é estritamente necessária.

Interação com especificações relacionadas

Em comparação com a implementação geral de EmplaceValue para ara::core::Result<T, E> em [SWS_CORE_00743], que é apenas condicionalmente segura contra exceções e cuja propriedade noexcept depende de std::is_nothrow_constructible<T, Args...>::value, a especialização void segundo [SWS_CORE_00843] oferece uma garantia irrestrita de noexcept e de segurança contra exceções.

A função-membro Err() const & da especialização de classe ara::core::Result<void, E> possibilita a consulta síncrona de um estado de erro possivelmente contido ([SWS_CORE_00868]). Ela é declarada através do arquivo de cabeçalho ara/core/result.h e não requer parâmetros de passagem durante a chamada ([SWS_CORE_00868]). Como valor de retorno, a função fornece um ara::core::Optional<E>, que contém o valor de erro concreto, caso o objeto represente um erro ([SWS_CORE_00868]).

Em relação à concorrência e às condições de contorno, a operação é explicitamente especificada como thread-safe ([SWS_CORE_00868]). No que tange à segurança contra exceções, o método é considerado condicionalmente seguro contra exceções (conditionally exception safe) ([SWS_CORE_00868]). A garantia noexcept é válida exatamente quando std::is_nothrow_constructible<Optional<E>, const E&>::value for atendido ([SWS_CORE_00868]).

No conjunto das interfaces, a sobrecarga rvalue Err() && ([SWS_CORE_00869]) complementa esta função dentro de ara::core::Result<void, E>. Pares comparáveis de sobrecargas lvalue e rvalue estão disponíveis também para o template primário ara::core::Result<T, E> ([SWS_CORE_00772], [SWS_CORE_00773]), bem como para a especialização de referência ara::core::Result<T&, E> ([SWS_CORE_00931], [SWS_CORE_00932]).

A função-membro Err() && da especialização ara::core::Result< void, E > extrai um erro eventualmente presente e o retorna como ara::core::Optional< E > [SWS_CORE_00869]. Ela é incluída através do arquivo de cabeçalho ara/core/result.h [SWS_CORE_00869].

Em relação ao uso e à semântica, aplicam-se as seguintes propriedades:

• Contexto de chamada e parâmetros: A função não recebe parâmetros e, como método qualificado como rvalue, vincula-se exclusivamente a instâncias rvalue de ara::core::Result< void, E > [SWS_CORE_00869]. Interpretação: Devido à semântica de rvalue (&&), o objeto de erro deve provavelmente ser movido para o Optional retornado durante a chamada. Pergunta Q-b5a0098f77686ca6 (aberta)
• Valor de retorno: O ara::core::Optional< E > resultante contém o valor de erro, desde que tal valor esteja presente no objeto [SWS_CORE_00869].
• Segurança contra exceções e concorrência: A operação é classificada como condicionalmente segura contra exceções (conditionally exception safe) e não lança exceções se std::is_nothrow_constructible< Optional< E >, E && >::value for atendido [SWS_CORE_00869]. Além disso, a função é especificada como segura para threads (thread-safe) [SWS_CORE_00869].

Na interação das interfaces, esta variante rvalue complementa a sobrecarga lvalue correspondente Err() const & da mesma especialização [SWS_CORE_00868]. Pares análogos de métodos lvalue e rvalue existem para o template primário ara::core::Result [SWS_CORE_00772], [SWS_CORE_00773], bem como para a especialização de referência ara::core::Result< T &, E > [SWS_CORE_00931], [SWS_CORE_00932].

A função-membro de template ErrorOr da especialização ara::core::Result<void, E> serve para a recuperação síncrona do erro contido ou de um erro padrão alternativo de acordo com [SWS_CORE_00863]. Se a instância já contiver um valor de erro do tipo E, este será retornado inalterado; caso contrário, o parâmetro passado defaultError será convertido por meio de static_cast para o tipo de erro E e retornado [SWS_CORE_00863].

Em relação ao tratamento de erros e à concorrência, aplicam-se as seguintes propriedades:

• Segurança contra exceções: A chamada é condicionalmente segura contra exceções (conditionally exception safe) e declarada como noexcept, desde que tanto a construção por cópia de E quanto a construção de E a partir do tipo de referência universal G&& não lancem exceções (std::is_nothrow_copy_constructible<E>::value && std::is_nothrow_constructible<E, G&&>::value) [SWS_CORE_00863].
• Segurança para threads: A operação é especificada como segura para threads (thread-safe) [SWS_CORE_00863]. Como se trata de uma sobrecarga de referência lvalue constante (const &), acessos simultâneos de leitura à mesma instância devem ser seguros. Pergunta Q-f95402c2e79ef590 (aberta)
• Cabeçalho: A função é disponibilizada através do arquivo de cabeçalho #include "ara/core/result.h" [SWS_CORE_00863].

Na interação dentro de ara::core::Result, [SWS_CORE_00863] constitui a contraparte lvalue constante para a sobrecarga rvalue [SWS_CORE_00864] para resultados void, na qual o erro é transferido via std::move. Sobrecargas equivalentes existem para o template de classe primário Result<T, E> via [SWS_CORE_00763] e [SWS_CORE_00764], bem como para tipos de referência Result<T &, E> via [SWS_CORE_00935] e [SWS_CORE_00936].

Utilização e semântica

A função-membro ErrorOr da especialização ara::core::Result<void, E> serve para a leitura síncrona de um erro a partir de uma instância rvalue ([SWS_CORE_00864]). Quando o método é chamado e o objeto Result contém um erro, este é movido por meio de std::move para o valor de retorno do tipo E. Se, por outro lado, houver um resultado bem-sucedido, o argumento passado defaultError é convertido via static_cast para E e retornado ([SWS_CORE_00864]).

Tratamento de erros e segurança de exceções

A função não dispara, por si mesma, mensagens de erro clássicas da AUTOSAR, como DET ou DEM. Em relação ao tratamento de exceções, ErrorOr é condicionalmente segura contra exceções (conditionally exception safe). Ela é protegida por uma expressão noexcept, desde que tanto o tipo de erro E possa ser movido sem exceções (std::is_nothrow_move_constructible<E>::value) quanto E possa ser construído a partir do tipo de referência universal G&& do erro padrão livre de exceções ([SWS_CORE_00864]).

Concorrência e interação

O método é especificado como thread-safe ([SWS_CORE_00864]). Devido ao qualificador de referência rvalue &&, a chamada pressupõe que o objeto Result seja passado como rvalue.

No módulo core, esta variante rvalue integra um conjunto com outras versões:

• Para ara::core::Result<void, E> existe, como contraparte lvalue, a sobrecarga const & [SWS_CORE_00863], que copia o erro em vez de movê-lo.
• Para resultados por valor e por referência, as especializações ara::core::Result<T, E> ([SWS_CORE_00763], [SWS_CORE_00764]) e ara::core::Result<T&, E> ([SWS_CORE_00935], [SWS_CORE_00936]) oferecem a mesma estrutura de assinaturas duais para semântica de cópia e de movimento.

usar

A função estática FromError é parte integrante da especialização de template ara::core::Result<void, E> e é incluída por meio do arquivo de cabeçalho ara/core/result.h [SWS_CORE_00834]. Ela serve como método factory síncrono para construir um novo Result a partir de um objeto de erro já existente [SWS_CORE_00834].

• Parâmetros: O parâmetro de entrada e recebe o erro como uma referência lvalue constante (const E &) [SWS_CORE_00834].
• Valor de retorno: Retorna uma instância de Result contendo o erro passado e [SWS_CORE_00834].

Tratamento de erros e segurança contra exceções

A especificação não define códigos de erro específicos e não prevê notificações para DET ou DEM [SWS_CORE_00834]. A função é condicionalmente segura para exceções (conditionally exception safe): ela é garantida como noexcept se, e somente se, o tipo de erro E for copiável sem lançar exceções (std::is_nothrow_copy_constructible<E>::value) [SWS_CORE_00834].

simultaneidade

A chamada é classificada como thread-safe [SWS_CORE_00834]. Interpretação: a segurança de thread provavelmente diz respeito ao fluxo interno da criação do objeto, mas pressupõe que o objeto de origem referenciado e não seja modificado por outras threads durante o processo de cópia. Pergunta Q-639cbb5cf8a64a0c (aberta)

Interação

Dentro da especialização ara::core::Result<void, E>, sobrecargas para referências rvalue (E&&) [SWS_CORE_00835] bem como para construção in-place via parameter pack [SWS_CORE_00836] complementam esta função; ambas são declaradas, diferentemente, como not thread-safe. Sobrecargas correspondentes também existem para o tipo incompletamente especializado ara::core::Result ([SWS_CORE_00734], [SWS_CORE_00735], [SWS_CORE_00736]) e para especializações de referência ([SWS_CORE_00905], [SWS_CORE_00906], [SWS_CORE_00907]).

usar

A função estática FromError cria de forma síncrona uma nova instância de ara::core::Result<void, E> a partir de um objeto de erro passado como rvalue e [SWS_CORE_00835]. A função é definida no cabeçalho ara/core/result.h e retorna um ara::core::Result contendo o valor de erro [SWS_CORE_00835].

Tratamento de erros e simultaneidade

A operação oferece segurança de exceção condicional (conditionally exception safe): garante ausência de exceções por meio de noexcept, desde que o tipo de erro E possua um construtor de movimento (move constructor) que não lance exceções (std::is_nothrow_move_constructible<E>::value) [SWS_CORE_00835]. A função é classificada como não segura para threads (not thread-safe) [SWS_CORE_00835]. Interpretação: isto provavelmente significa que o objeto rvalue a ser movido deve ser protegido contra acessos paralelos de outras threads. Pergunta Q-be29e8c3a7412b7a (aberta)

Interação

Dentro da especialização ara::core::Result<void, E>, esta sobrecarga representa a contrapartida de movimento (move) para a função de cópia de lvalue [SWS_CORE_00834] e para a construção in-place por meio de parameter packs [SWS_CORE_00836]. Sobrecargas rvalue comparáveis também existem no módulo core para tipos de valor [SWS_CORE_00735] e referências [SWS_CORE_00906], complementadas pelas respectivas variantes lvalue ([SWS_CORE_00734], [SWS_CORE_00905]) e in-place ([SWS_CORE_00736], [SWS_CORE_00907]).

A função de template estática FromError conforme [SWS_CORE_00836] destina-se a criar, dentro da especialização ara::core::Result<void, E>, um objeto Result com erro, cuja instância de erro do tipo E é construída diretamente no local («in-place») a partir dos argumentos passados args. A função só participa da resolução de sobrecarga se std::is_constructible<E, Args&&...>::value for verdadeiro, o primeiro tipo do parameter pack desempacotado não corresponder a E e também não for uma especialização de Result [SWS_CORE_00836].

Quanto à segurança de exceções, a função é especificada como condicionalmente segura para exceções («conditionally exception safe»): ela é declarada com noexcept(std::is_nothrow_constructible<E, Args...>::value) [SWS_CORE_00836]. Em relação à concorrência, a chamada é considerada não segura para threads («not thread-safe») [SWS_CORE_00836].

Na interação com outras funções da classe, este método complementa as sobrecargas para criação a partir de objetos de erro lvalue ([SWS_CORE_00834]) ou rvalue ([SWS_CORE_00835]) já existentes. Interpretação: as restrições SFINAE relativas a E e Result provavelmente visam assegurar que, ao passar erros já criados ou instâncias de Result, sejam selecionados preferencialmente os respectivos operadores de cópia ou movimento, evitando ambiguidades. Pergunta Q-2796f954bcaececa (aberta) Funções factory in-place análogas existem para o tipo genérico Result ([SWS_CORE_00736]) bem como para tipos de referência em Result<T&, E> ([SWS_CORE_00907]).

usar

A função-membro estática FromValue() serve para criar um objeto ara::core::Result bem-sucedido para a especialização de template ara::core::Result<void, E> [SWS_CORE_00831]. Como o tipo de resultado void não transporta dados úteis, a função não aceita parâmetros de entrada. A chamada ocorre de forma síncrona e retorna um Result que representa um valor void [SWS_CORE_00831]. A declaração ocorre no cabeçalho ara/core/result.h [SWS_CORE_00831].

Tratamento de erros e segurança contra exceções

A função é fornecida com a especificação noexcept e classificada como totalmente segura contra exceções (exception safe) [SWS_CORE_00831]. Como FromValue() representa, por definição, uma operação bem-sucedida, ela não gera estados de erro nem retorna códigos de erro. Mensagens de erro específicas via DET ou DEM não estão definidas para esta chamada.

simultaneidade

De acordo com a especificação, a função é classificada como thread-safe (thread-safe) [SWS_CORE_00831]. Ela pode ser chamada em paralelo a partir de múltiplas threads sem precauções adicionais de sincronização.

Interação

A assinatura sem parâmetros destina-se exclusivamente a Result<void, E> [SWS_CORE_00831]. Ela distingue-se das sobrecargas geradoras de valor:

• Para tipos de valor Result<T, E>, existem variantes para lvalues [SWS_CORE_00731], rvalues [SWS_CORE_00732] bem como construções in-place [SWS_CORE_00733].
• Para tipos de referência Result<T&, E>, FromValue vincula-se a uma referência de lvalue [SWS_CORE_00904].

A função-membro Resolve da classe de template ara::core::Result<void, E> destina-se ao tratamento de erros no âmbito da programação genérica [SWS_CORE_00867]. Se a instância de Result contiver um valor regular, a chamada não executa nenhuma operação [SWS_CORE_00867]. Se a instância contiver, em vez disso, um erro, o Callable f passado como parâmetro é chamado [SWS_CORE_00867].

O Callable f passado deve ser compatível com a assinatura de função void f(const E&), onde E representa o tipo de erro [SWS_CORE_00867]. A própria função Resolve não fornece nenhum valor de retorno (void) [SWS_CORE_00867]. Quanto à segurança de execução, a função é especificada como não segura contra exceções (“not exception safe”) [SWS_CORE_00867]. A sua segurança de thread é condicional e depende diretamente da segurança de thread do Callable passado f [SWS_CORE_00867].

No sistema global, esta especialização difere das funções Resolve regulares para tipos de valor em ara::core::Result<T, E> [SWS_CORE_00767] bem como tipos de referência em ara::core::Result<T&, E> [SWS_CORE_00939], [SWS_CORE_00940]: enquanto essas variantes retornam o valor contido ou o resultado da chamada do Callable, a sobrecarga void sem valor de retorno existe exclusivamente como um bloco de construção genérico para padronização de chamadas de interface [SWS_CORE_00867].

A função-membro Swap permuta o conteúdo da instância atual de forma síncrona com a referência passada other [SWS_CORE_00845]. Ela pertence ao escopo da especialização ara::core::Result<void, E> do arquivo de cabeçalho ara/core/result.h e não possui valor de retorno [SWS_CORE_00845].

Em relação ao tratamento de erros, a operação é classificada como condicionalmente segura contra exceções (conditionally exception safe) [SWS_CORE_00845]. A garantia noexcept entra em vigor exatamente quando o tipo de erro E é tanto nothrow-move-constructible (std::is_nothrow_move_constructible<E>::value) quanto nothrow-move-assignable (std::is_nothrow_move_assignable<E>::value) [SWS_CORE_00845]. Códigos de erro específicos ou notificações para DET ou DEM não estão previstos para esta chamada [SWS_CORE_00845].

No tocante à concorrência, Swap é expressamente especificada como não thread-safe (not thread-safe) [SWS_CORE_00845]. Portanto, um acesso concorrente às mesmas instâncias sem sincronização externa deverá levar a condições de corrida (data races). Pergunta Q-a8d4f130648765df (aberta)

Na interação dentro de ara::core, o método forma a base para a função de template livre ara::core::swap, cuja condição noexcept está diretamente acoplada à função-membro [SWS_CORE_00796]. Operações de troca comparáveis existem para o tipo genérico ara::core::Result<T, E> [SWS_CORE_00745], a especialização de referência ara::core::Result<T&, E> [SWS_CORE_00917] bem como para objetos Promise [SWS_CORE_00352] [SWS_CORE_06352].

A função-membro ValueOr da especialização ara::core::Result<void, E> serve primariamente para facilitar padrões de programação genérica e não executa nenhuma operação durante a sua execução ([SWS_CORE_00861]). Disponibilizada através do cabeçalho ara/core/result.h, o método aceita de forma síncrona um parâmetro defaultValue do tipo de encaminhamento U&& e não fornece valor de retorno (void) ([SWS_CORE_00861]).

Quanto à concorrência e ao comportamento perante exceções, a função-membro é especificada como thread-safe (thread-safe) e declarada com a sintaxe de especificador noexcept, o que garante total segurança contra exceções ([SWS_CORE_00861]). Como nenhuma verificação do estado de erro e nenhuma ação ocorrem, não existem códigos de erro nem mensagens para DET ou DEM.

Na interação com as demais variantes de Result, esta função complementa as sobrecargas baseadas em valor ([SWS_CORE_00761], [SWS_CORE_00762]) e baseadas em referência ([SWS_CORE_00933], [SWS_CORE_00934]) de ValueOr. Enquanto essas funções retornam o valor definido ou, caso contrário, entregam o valor substituto passado de forma convertida, esta variante representa uma contrapartida neutra para operações sem retorno de valor ([SWS_CORE_00861]). Interpretação: O valor passado defaultValue deverá ser descartado sem uso na implementação. Isto permite que desenvolvedores escrevam algoritmos de template genéricos sem ramificações especiais para Result<void, E>. Pergunta Q-6097af779219e859 (aberta)

A função-membro ValueOrThrow da especialização de template ara::core::Result<void, E> serve para a verificação síncrona do resultado da operação [SWS_CORE_00866]. Dado que o tipo de valor é void, a função não possui parâmetros e não fornece valor de retorno [SWS_CORE_00866]. A declaração é fornecida através do cabeçalho ara/core/result.h [SWS_CORE_00866].

Em caso de sucesso, o método retorna normalmente; caso contrário, existindo um estado de erro, ele lança uma exceção do tipo de exceção associado ao erro contido (noexcept(false)) [SWS_CORE_00866]. Em relação à segurança de exceção, a operação é especificada como not exception safe [SWS_CORE_00866].

Para o contexto de chamada e a concorrência aplicam-se as seguintes condições marginais:

• A função está classificada como thread-safe [SWS_CORE_00866].
• Se as exceções de C++ estiverem desativadas na toolchain do compilador, esta função não participa na resolução de sobrecarga [SWS_CORE_00866].

Na interação com o módulo core, esta especialização void complementa as sobrecargas genéricas de ara::core::Result<T, E>, as quais retornam referências a valores contidos ([SWS_CORE_00766], [SWS_CORE_00769], [SWS_CORE_00778]), bem como as especializações para tipos de referência ara::core::Result<T&, E> ([SWS_CORE_00938], [SWS_CORE_00949]).

A função-membro de template CheckError da especialização ara::core::Result<void, E> verifica de forma síncrona se a instância atual contém um determinado erro [SWS_CORE_00865]. Para isso, o argumento passado error é convertido através de static_cast no tipo de erro E e comparado com o valor de retorno do estado de erro interno Error() [SWS_CORE_00865]. A chamada ocorre através do cabeçalho #include "ara/core/result.h" [SWS_CORE_00865].

Para a utilização e o contexto de chamada, aplicam-se as seguintes propriedades:

• Parâmetro e valor de retorno: O parâmetro de referência universal error do tipo G&& aceita o erro a ser verificado [SWS_CORE_00865]. A função retorna true se a instância contiver um erro equivalente a error, caso contrário false [SWS_CORE_00865].
• Concorrência e segurança contra exceções: A operação é declarada como const noexcept, considerada segura contra exceções (exception safe) e passível de ser chamada de forma irrestritamente thread-safe (thread-safe) [SWS_CORE_00865].

Na interação com o módulo core, existem sobrecargas análogas de CheckError: a classe de template primária ara::core::Result disponibiliza a mesma assinatura, igualmente thread-safe e segura contra exceções com noexcept [SWS_CORE_00765]. Em contrapartida, a especialização de referência ara::core::Result<T&, E>, embora possua o mesmo mecanismo de comparação e seja thread-safe, é explicitamente especificada sem noexcept como não segura contra exceções (not exception safe) [SWS_CORE_00937].