classe ara::shwa::Range

A classe encapsula dimensões de intervalos multidimensionais e impede completamente a instanciação sem parâmetros [AP_SWS_SHWA_01002]. Os objetos são criados de forma controlada por meio de métodos estáticos de fábrica, que retornam ShwaErrorCode::kRuntime em caso de erro e, em caso de sucesso, disponibilizam objetos de valor seguros contra exceções com semântica de cópia e movimentação [AP_SWS_SHWA_01007]. A leitura de dimensões individuais não é thread-safe e requer sincronização externa [AP_SWS_SHWA_01010].

mais ›

Contexto

A classe template ara::shwa::Range representa, dentro do módulo shwa da Adaptive Platform, uma especificação multidimensional de intervalo ou tamanho (parametrizada por padrão por meio de Dimensions = 1). Em arquiteturas próximas ao hardware ou com compartilhamento de memória, um objeto de intervalo serve tipicamente como descrição estruturada de extensões geométricas ou dimensões de buffer em até três eixos. Os parceiros de interação são principalmente componentes de aplicação e serviços de driver que precisam alocar, particionar ou endereçar áreas de memória. A classe encapsula as medidas discretas das dimensões e as protege contra construção direta errônea, impedindo, por meio de restrições de interface, objetos inicializados de forma incompleta ou inválida.

Ciclo de vida

O ciclo de vida de uma instância de ara::shwa::Range é determinado por diretrizes estritas de construção. O construtor padrão sem parâmetros é explicitamente excluído [AP_SWS_SHWA_01002]. Uma criação direta sem especificação das dimensões está, portanto, descartada. Em vez disso, a criação ocorre exclusivamente por meio de métodos estáticos de fábrica Create, que são sobrecarregados para variantes uni, bi ou tridimensionais: para uma dimensão com dim0 [AP_SWS_SHWA_01007], para duas dimensões com dim0 e dim1 [AP_SWS_SHWA_01008], bem como para três dimensões com dim0, dim1 e dim2 [AP_SWS_SHWA_01009]. Cada uma dessas funções de fábrica retorna um ara::core::Result<Range>.

Após a criação bem-sucedida, a classe comporta-se como um tipo por valor (Value Type) completo. Ela disponibiliza tanto o construtor de cópia [AP_SWS_SHWA_01003] quanto o operador de atribuição por cópia [AP_SWS_SHWA_01004] como operações padronizadas e seguras contra exceções (noexcept = default). Complementarmente, estão disponíveis um construtor de movimentação [AP_SWS_SHWA_01005] e um operador de atribuição por movimentação [AP_SWS_SHWA_01006] com a mesma segurança contra exceções. As instâncias possuem, assim, semântica de valor clara e podem ser transferidas ou mantidas em contêineres sem problemas. Em relação à concorrência, os métodos estáticos de fábrica são projetados como thread-safe, ao passo que os métodos inspetores de leitura GetDimension0 [AP_SWS_SHWA_01010], GetDimension1 [AP_SWS_SHWA_01011] e GetDimension2 [AP_SWS_SHWA_01012] são classificados pela especificação como não thread-safe.

Caminho de utilização

Um caminho de uso típico abrange a criação de uma instância de intervalo por meio da interface estática, a validação do resultado e a subsequente leitura das dimensões para etapas de configuração ou alocação. O seguinte diagrama de sequência ilustra esse fluxo.

Diagrama de sequência: fluxo de uso típico na criação e consulta de dimensões. Fontes: [AP_SWS_SHWA_01007], [AP_SWS_SHWA_01010]

No primeiro passo, a aplicação chama uma das sobrecargas da fábrica, por exemplo Create(dim0) [AP_SWS_SHWA_01007] para um intervalo unidimensional ou Create(dim0, dim1) [AP_SWS_SHWA_01008] ou Create(dim0, dim1, dim2) [AP_SWS_SHWA_01009] para configurações multidimensionais. A camada chamadora verifica em seguida o sucesso do ara::core::Result retornado. Se houver um valor válido, o objeto Range é desreferenciado ou movido. Subsequentemente, funções a jusante podem consultar os tamanhos de eixos contidos através de GetDimension0 [AP_SWS_SHWA_01010] bem como, conforme a necessidade, através de GetDimension1 [AP_SWS_SHWA_01011] e GetDimension2 [AP_SWS_SHWA_01012] e utilizá-los para operações de buffer.

Cenários de erro

Durante a criação por meio de Create, podem ocorrer condições de erro que resultem na falha da inicialização. Neste caso, a fábrica não fornece um objeto inicializado, mas sim um resultado de erro do tipo ShwaErrorCode::kRuntime («General runtime error») [AP_SWS_SHWA_01007], [AP_SWS_SHWA_01008], [AP_SWS_SHWA_01009]. Para todas as variantes da fábrica, a especificação garante semântica de rollback e segurança contra exceções (noexcept), de modo que, em caso de erro, não permaneçam estados parciais nem sejam causadas inconsistências.

Para os métodos de inspeção GetDimension0 [AP_SWS_SHWA_01010], GetDimension1 [AP_SWS_SHWA_01011] e GetDimension2 [AP_SWS_SHWA_01012], não estão previstos códigos de erro de retorno; no entanto, a especificação classifica-os como não seguros contra exceções (not exception safe) e não thread-safe (not thread-safe). O chamador tem, portanto, a pré-condição de proteger o acesso entre threads. Além disso, a chamada de uma consulta de dimensão que ultrapasse o número de dimensões instanciado com o parâmetro de template Dimensions (por exemplo GetDimension2 numa configuração unidimensional) deverá ser inadmissível e levar a erros. Pergunta Q-794519baf2ea8a5e (aberta)