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

A especialização ara::core::Promise< void, E > serve como ponto terminal produtor assíncrono para sinalizar a conclusão de uma operação sem valor de retorno ou para transmitir um erro ([SWS_CORE_06341]). Após a instanciação, o Future correspondente é obtido exatamente uma vez para o consumidor através de get_future() ([SWS_CORE_06344]). A disponibilização ocorre de forma thread-safe através de set_value(), SetError() ou SetResult(), marcando o estado partilhado como pronto. Como a classe possui semântica exclusiva de movimento, definições múltiplas ou estados partilhados ausentes levam a violações especificadas.

mais ›

Contexto

A classe ara::core::Promise< void, E > representa uma especialização de modelo para fluxos assíncronos sem valor de dados úteis (tipo de retorno void). Constitui o lado produtor (producer) de um canal de comunicação e sincroniza cálculos ou operações assíncronas com o lado consumidor (consumer). Através de um estado interno partilhado (shared state), permite sinalizar quer a conclusão bem-sucedida de uma operação, quer a ocorrência de um erro do tipo E. O objeto recetor correspondente é disponibilizado sob a forma de ara::core::Future< void, E > ([SWS_CORE_06344]). De acordo com os requisitos da AUTOSAR Adaptive Platform, a implementação exige que o tipo de erro E seja compatível com ara::core::ErrorCode; qualquer discrepância resulta num erro de compilação.

Ciclo de vida

A criação de uma instância ocorre através do construtor predefinido sem parâmetros [SWS_CORE_06341], o qual cria um novo estado partilhado e se comporta de forma análoga à função padrão do C++ std::promise. A classe modela uma posse exclusiva e implementa semântica estrita de movimento: tanto o construtor de cópia ([SWS_CORE_06350]) como o operador de atribuição por cópia ([SWS_CORE_06351]) foram eliminados (delete).

Um estado existente pode ser transferido para outras instâncias através do construtor de movimento ([SWS_CORE_06342]) ou do operador de atribuição por movimento ([SWS_CORE_06343]). Na atribuição por movimento, um estado partilhado detido até então é abandonado e o estado é transferido como por Promise(std::move(other)).swap(*this) ([SWS_CORE_06343]). Além disso, a função swap ([SWS_CORE_06352]) permite a troca direta de dois estados.

O destrutor [SWS_CORE_06349] liberta qualquer estado partilhado que ainda esteja a ser mantido. Interpretação: o abandono prematuro do estado partilhado aquando da destruição de uma Promise ainda não satisfeita deverá levar a um estado órfão no Future associado. Pergunta Q-e89b32fa3e5994e2 (aberta) No que respeita à concorrência, a criação predefinida ([SWS_CORE_06341]), bem como a definição do resultado ([SWS_CORE_06345], [SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]) são thread-safe. Em contrapartida, as operações de movimento, swap, a obtenção do Future ([SWS_CORE_06344]) e a destruição não são thread-safe e requerem coordenação externa no acesso partilhado.

Caminho de utilização

A utilização típica de ara::core::Promise< void, E > compreende a preparação da execução assíncrona, a passagem do canal de receção e a subsequente notificação do resultado:

1. Inicialização: o produtor instancia o objeto Promise ([SWS_CORE_06341]).
2. Obter o Future: através de get_future(), o ara::core::Future< void, E > associado é criado exatamente uma vez ([SWS_CORE_06344]) e transmitido ao lado consumidor.
3. Definir o resultado: após a conclusão da operação assíncrona, o produtor coloca o estado partilhado no estado pronto (ready):
   • Em caso de sucesso, chamando set_value() sem argumentos ([SWS_CORE_06345]).
   • Em caso de erro, armazenando um erro via SetError, seja por movimentação ([SWS_CORE_06353]) ou por cópia ([SWS_CORE_06354]).
   • Alternativamente, passando um Result< void, E > completo por meio de SetResult por cópia ([SWS_CORE_06355]) ou movimentação ([SWS_CORE_06356]).
4. Resolução: assim que o estado estiver pronto, o consumidor pode consumir o resultado por meio do future; o objeto promise é liberado ao final de seu escopo ([SWS_CORE_06349]).

Diagrama de sequência: fluxo típico da sincronização assíncrona desde a criação até a disponibilização do resultado. Fontes: [SWS_CORE_06341], [SWS_CORE_06344], [SWS_CORE_06345], [SWS_CORE_06349]

Cenários de erro

Violações das pré-condições levam a situações de erro definidas (violações):

• IsoStdFutureErrcFutureAlreadyRetrievedViolation: é acionado se get_future() for chamado várias vezes para o mesmo estado compartilhado ([SWS_CORE_06344]).
• IsoStdFutureErrcNoStateViolation: ocorre quando get_future() é chamado sem que a promise disponha de um estado compartilhado ([SWS_CORE_06344]), por exemplo, após uma operação de movimentação ([SWS_CORE_06342]).
• IsoStdFutureErrcPromiseAlreadySatisfiedViolation: ocorre quando set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) ou SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) é chamado, embora um valor ou erro já esteja armazenado no estado compartilhado.
• PromiseNoSharedStateToSetViolation: sinaliza que set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) ou SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) foram chamados sem um estado compartilhado existente.

Com relação à segurança contra exceções, os métodos SetError e SetResult são condicionalmente seguros contra exceções (conditionally exception safe): eles garantem noexcept apenas se o tipo E for classificado como construtível por movimentação sem lançamento de exceções (nothrow-move-constructible) ou construtível por cópia sem lançamento de exceções (nothrow-copy-constructible) ([SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]).