classe ara::core::Future

usar

O método get() obtém de forma síncrona o resultado do tipo T a partir de um ara::core::Future [SWS_CORE_00326]. A função comporta-se de forma idêntica à contraparte em std::future; caso o cálculo assíncrono ainda esteja a decorrer, a chamada bloqueia até à conclusão ou até à ocorrência de um erro [SWS_CORE_00336]. Através da chamada, o objeto perde o seu estado, de modo que o future fica imediatamente inválido (valid() == false) [SWS_CORE_00326]. Uma chamada sem bloqueio pode ser previamente assegurada através de is_ready() [SWS_CORE_00332].

Tratamento de erros

As falhas são comunicadas através de exceções C++ [SWS_CORE_00326]:

• Se tiver sido registado um erro no Promise associado através de SetError() ou SetResult(), é lançada uma exceção do tipo de erro correspondente [SWS_CORE_00326].
• Se o estado partilhado (shared state) for abandonado prematuramente pela operação assíncrona, tal resulta no erro kBrokenPromise em conformidade com FutureErrc [SWS_CORE_00326], [SWS_CORE_00400].
• Se a chamada ocorrer numa instância inválida, é lançada uma FutureException com o código de erro kNoState [SWS_CORE_00326].

Simultaneidade e restrições

A operação não é segura para threads nem segura quanto a exceções (not exception safe) [SWS_CORE_00326]. Acessos simultâneos ao mesmo future a partir de múltiplas threads requerem sincronização externa. Se as exceções estiverem desativadas na toolchain do compilador, get() não participa na resolução de sobrecargas [SWS_CORE_00326]; para este caso, existe a alternativa isenta de exceções GetResult() [SWS_CORE_00336]. Para instâncias sem valor de retorno, está disponível a especialização Future<void, E>::get() [SWS_CORE_06226].

A função-membro then destina-se ao encadeamento de cálculos assíncronos e regista um objeto invocável func como continuação (continuation) numa instância de ara::core::Future [SWS_CORE_00331]. Após o retorno da chamada, a Future original fica inválida (valid() == false). O destino da chamada recebe o resultado da instância obtido através de GetResult() transmitido como rvalue do tipo Result<T, E> [SWS_CORE_00331].

O tipo de retorno de then rege-se pelo tipo de retorno U da continuação [SWS_CORE_00331]:

• Se func devolver um Future<T2, E2>, ocorre o desempacotamento implícito de future (future unwrapping) para Future<T2, E2> [SWS_CORE_00331].
• Se func devolver um Result<T2, E2>, ocorre o desempacotamento implícito de result (result unwrapping) para Future<T2, E2> [SWS_CORE_00331].
• Em todos os restantes casos, o tipo de retorno é Future<U, E> [SWS_CORE_00331].

A execução de func pode ter lugar de forma síncrona no contexto da chamada de then, no contexto de Promise::set_result ou Promise::SetError, ou noutro contexto [SWS_CORE_00331]. A chamada está especificada como não sendo segura para threads. A continuação é registada no Future devolvido; após o retorno do seu destruidor, nenhuma continuação poderá ser executada, enquanto uma execução já em curso continuará até ao fim [SWS_CORE_00331].

Não existem códigos de erro normalizados [SWS_CORE_00331]. Os erros devem ser intercetados pelos utilizadores e reencaminhados como código de erro num Result devolvido ou numa Future, dado que as exceções não podem sair da continuação. Uma chamada numa Future inválida desencadeia FutureInvalidViolation; se a continuação lançar uma exceção, tal resulta em FutureContinuationHasThrownViolation [SWS_CORE_00331].

Para execuções num contexto de execução explícito, está disponível a sobrecarga com executor [SWS_CORE_00337], enquanto para operações sem valor de retorno se aplica a especialização void [SWS_CORE_06231].

Utilização e semântica

O método then regista uma continuação (func) que é executada assincronamente no contexto do executor passado assim que o resultado da instância atual de Future estiver disponível [SWS_CORE_00337]. A unidade invocável recebe o resultado da instância como uma expressão rvalue do tipo Result<T,E> [SWS_CORE_00337]. O tipo de retorno rege-se pelo tipo de retorno U da continuação:

• Se a continuação devolver um Future<T2,E2>, ocorre um desempacotamento implícito para Future<T2,E2> [SWS_CORE_00337].
• Se a continuação devolver um Result<T2,E2>, este também é resolvido implicitamente para Future<T2,E2> [SWS_CORE_00337].
• Em todos os outros casos, a chamada fornece Future<U,E> [SWS_CORE_00337].

Concorrência e ciclo de vida

Imediatamente após o retorno da chamada do método, a instância original de Future fica inválida (valid() == false) [SWS_CORE_00337]. A função está declarada como não segura para threads [SWS_CORE_00337]. As continuações registadas são geridas no Future recentemente devolvido. Após o término do seu destrutor, já nenhuma continuação pode ser iniciada; uma execução já em curso é concluída, pelo que o destrutor pode bloquear [SWS_CORE_00337].

Tratamento de erros e interação

Não estão definidos códigos de erro normalizados [SWS_CORE_00337]. Uma chamada numa instância inválida desencadeia a violação FutureInvalidViolation [SWS_CORE_00337]. Se a continuação lançar uma exceção, tal resulta numa FutureContinuationHasThrownViolation; as exceções devem, portanto, ser capturadas e reencaminhadas como erros através de ara::core::Result ou ara::core::Future [SWS_CORE_00337]. Em comparação com a sobrecarga sem contexto de execução [SWS_CORE_00331], esta variante força a execução no executor passado; para tipos de resultados void, existe a especialização análoga [SWS_CORE_06237].

A função de consulta síncrona valid() verifica, sem parâmetros, se uma instância de ara::core::Future possui um estado partilhado (Shared State) e se, por conseguinte, está utilizável [SWS_CORE_00327]. Retorna true caso o objeto esteja pronto para utilização e false se não existir nenhum estado partilhado [SWS_CORE_00327]. O comportamento corresponde à função standard std::future::valid e aplica-se da mesma forma à especialização de template ara::core::Future<void, E> [SWS_CORE_06227].

A função é declarada como noexcept, é considerada segura face a exceções (exception safe) e está expressamente especificada como segura para threads (thread-safe) [SWS_CORE_00327]. Não desencadeia por si própria quaisquer códigos de erro ou exceções e pode, portanto, ser utilizada em segurança para a verificação de estado [SWS_CORE_00327].

Na interação com outros métodos de Future, a verificação de validade é crucial, uma vez que operações chamadoras como wait() [SWS_CORE_00328] ou is_ready() [SWS_CORE_00332] desencadeiam uma FutureInvalidViolation em caso de estado inválido (valid() == false). Uma Future anteriormente válida torna-se automaticamente inválida assim que o seu resultado for consumido através de get() [SWS_CORE_00326] ou GetResult() [SWS_CORE_00336], ou assim que for registado um processamento posterior através de then() [SWS_CORE_00331], [SWS_CORE_00337].

A função-membro wait da classe ara::core::Future bloqueia a thread chamadora de forma síncrona até que um valor de resultado ou um erro da operação assíncrona esteja disponível [SWS_CORE_00328]. A função não aceita parâmetros, não retorna nenhum valor e se comporta, de acordo com a especificação, de forma análoga à função correspondente de std::future [SWS_CORE_00328]. O mesmo comportamento se aplica à especialização de template ara::core::Future<void, E> [SWS_CORE_06228].

Em relação ao tratamento de erros e à concorrência, estão definidos os seguintes requisitos:

• Condição de erro: Se o objeto Future for inválido (valid == FALSE), ocorre uma FutureInvalidViolation [SWS_CORE_00328], [SWS_CORE_06228]. Ainda assim, a função é declarada como noexcept e classificada como segura para exceções (exception safe) [SWS_CORE_00328].
• Segurança de thread: A chamada é classificada explicitamente como not thread-safe [SWS_CORE_00328]. O acesso concorrente ao mesmo objeto Future sem sincronização externa é inadmissível.

Na interação com interfaces relacionadas, recomenda-se a verificação por meio de is_ready antes da chamada [SWS_CORE_00332], [SWS_CORE_06232]: se esta retornar true, a chamada de wait garantidamente não mais bloqueará. Caso seja necessária uma operação de bloqueio limitada no tempo em vez de uma espera indefinida, estão disponíveis alternativamente wait_for com uma duração relativa [SWS_CORE_00329], [SWS_CORE_06229] e wait_until com um instante absoluto [SWS_CORE_00330], [SWS_CORE_06230].

usar

A função-membro wait_for da classe ara::core::Future bloqueia a thread chamadora por no máximo o intervalo de tempo fornecido timeoutDuration ou até que um valor de resultado ou um erro esteja disponível no estado compartilhado [SWS_CORE_00329]. Seu comportamento corresponde ao da função correspondente de std::future [SWS_CORE_00329]. Como valor de retorno, fornece um FutureStatus [SWS_CORE_00329], que indica se o estado compartilhado está disponível (kReady) ou se o tempo de espera especificado expirou (kTimeout) [SWS_CORE_00361].

Tratamento de erros e condições de contorno

A função é declarada como noexcept e especificada como segura contra exceções (exception safe) [SWS_CORE_00329]. Se o objeto Future for inválido (valid == FALSE), ocorre uma violação na forma de FutureInvalidViolation [SWS_CORE_00329]. Interpretação: Como nenhuma exceção C++ pode ser lançada, tal violação provavelmente deve ser tratada do lado da plataforma como um erro fatal de tempo de execução. Pergunta Q-2f22a07f6e143856 (aberta)

Concorrência e interação

A operação é classificada como not thread-safe [SWS_CORE_00329]; acessos simultâneos à mesma instância requerem, portanto, sincronização externa. A semântica e a assinatura aplicam-se de forma idêntica à especialização de template ara::core::Future<void, E> [SWS_CORE_06229]. Ao contrário de std::future_status, não existe entrada para deferred no tipo de enumeração FutureStatus [SWS_CORE_00361].

A função-membro wait_until bloqueia a thread chamadora até que o instante absoluto especificado deadline seja alcançado ou até que o ara::core::Future disponibilize um resultado ou erro [SWS_CORE_00330]. O comportamento orienta-se pela função correspondente de std::future [SWS_CORE_00330].

Como valor de retorno, a função fornece um FutureStatus [SWS_CORE_00330]. Este tipo de enum sinaliza, por meio do estado kReady, que o estado compartilhado está pronto (valor ou erro disponível) ou, por meio de kTimeout, que o prazo expirou sem resultado [SWS_CORE_00361]. Um estado análogo a std::future_status::deferred não existe em FutureStatus [SWS_CORE_00361].

No que diz respeito ao tratamento de erros e à segurança de exceções, a função é especificada como segura contra exceções (exception safe) e noexcept [SWS_CORE_00330]. No entanto, se a função for chamada em uma instância inválida (valid == FALSE), ocorre uma violação sob a forma de FutureInvalidViolation [SWS_CORE_00330].

Em relação à concorrência, wait_until é classificada como não segura para threads (not thread-safe) [SWS_CORE_00330]. Acessos paralelos ao mesmo objeto ara::core::Future devem, portanto, ser sincronizados externamente. A mesma semântica e assinatura aplicam-se à especialização ara::core::Future<void, E> [SWS_CORE_06230].