classe ara::shwa::Buffer

O modelo de classe serve para gerir buffers de memória multidimensionais para a aceleração segura de hardware na Adaptive Platform SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Visto que todas as operações predefinidas, de cópia e de movimento foram eliminadas, a criação efetua-se exclusivamente através de métodos de fábrica estáticos como [AP_SWS_SHWA_00209] sob a forma de ponteiro detido em regime de exclusividade. Através de propriedades e alocadores configuráveis, a memória pode ser adaptada, ao passo que os acessos de leitura às propriedades não estão concebidos como thread-safe. As reservas de memória mal-sucedidas são reportadas ao chamador através de códigos de erro definidos.

mais ›

Contexto

A classe de modelo ara::shwa::Buffer constitui, no módulo Safe Hardware Acceleration (SHWA) da Adaptive Platform, uma abstração central para o encapsulamento e gestão de áreas de memória multidimensionais. Conforme exposto na arquitetura de sistema, as Adaptive Applications bem como os clusters funcionais interagem tipicamente com uma combinação de múltiplas filas (Queues), dispositivos aceleradores (Devices) e buffers (SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform»). Os buffers disponibilizam aqui a memória necessária para operações de aceleração ao nível do host ou do device, podendo ser configurados opcionalmente através de alocadores específicos da aplicação ([AP_SWS_SHWA_00210]) ou de ponteiros de dados do host.

Diagrama de contexto: integração do buffer na interação funcional entre aplicações, dispositivos, filas e alocadores. Fontes: SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform», [AP_SWS_SHWA_00210].

Ciclo de vida

O ciclo de vida de uma instância de buffer está sujeito a restrições semânticas rigorosas. Para assegurar relações de posse inequívocas, tanto o construtor predefinido ([AP_SWS_SHWA_00202]) como o construtor de cópia ([AP_SWS_SHWA_00203]) e o operador de atribuição por cópia ([AP_SWS_SHWA_00204]) estão eliminados. De igual modo, o construtor de movimento ([AP_SWS_SHWA_00205]) e o operador de atribuição por movimento ([AP_SWS_SHWA_00206]) estão explicitamente eliminados. Interpretação: isto deverá impedir que recursos de buffer ou relações de hardware sejam duplicados ou deslocados na memória de forma descontrolada. Pergunta Q-dcabd66fa9f3ec2a (aberta)

A criação realiza-se, por conseguinte, exclusivamente através de métodos de fábrica estáticos da família de sobrecargas Create, os quais retornam, em caso de sucesso, um std::unique_ptr<Buffer> encapsulado num ara::core::Result. Para tal, encontram-se disponíveis diferentes caminhos de construção:

• Criação com região de buffer e lista opcional de propriedades: thread-safe ([AP_SWS_SHWA_00209]).
• Criação com região de buffer, alocador dedicado e lista de propriedades: thread-safe ([AP_SWS_SHWA_00210]).
• Criação com base em ponteiros de dados do host existentes com intervalo de buffer: thread-safe tanto para ponteiros modificáveis ([AP_SWS_SHWA_00211]) quanto para ponteiros de dados constantes ([AP_SWS_SHWA_00213]).
• Criação com ponteiro de dados do host constante, intervalo de buffer e alocador: thread-safe ([AP_SWS_SHWA_00214]).
• Criação direta exclusivamente por meio de um alocador: não thread-safe ([AP_SWS_SHWA_00212]).

Após a criação bem-sucedida, a posse permanece com o contexto chamador via std::unique_ptr. A destruição do objeto no término do smart pointer deve liberar automaticamente a área de memória subjacente por meio do respectivo alocador. Pergunta Q-aa2b5642b8527803 (aberta)

Caminho de utilização

Um caminho de utilização típico começa com a alocação e inicialização do buffer por meio de um dos métodos de fábrica thread-safe, como [AP_SWS_SHWA_00209]. Após a instanciação bem-sucedida, a aplicação pode verificar se propriedades específicas estão definidas para este buffer chamando HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]). Se a propriedade desejada estiver presente, seu valor concreto poderá ser lido de forma síncrona via GetProperty<PropertyT>() ([AP_SWS_SHWA_00216]). Deve-se observar que tanto HasProperty quanto GetProperty estão declarados como não thread-safe; consultas concorrentes no mesmo objeto de buffer devem, portanto, ser sincronizadas pelo lado da aplicação.

Diagrama de sequência: sequência típica na instanciação por meio da fábrica e posterior consulta de propriedades. Fontes: [AP_SWS_SHWA_00209], [AP_SWS_SHWA_00215], [AP_SWS_SHWA_00216].

Cenários de erro

Todos os métodos de fábrica e de inspeção são declarados com noexcept e oferecem segurança irrestrita contra exceções (exception safe). Os erros são sinalizados por meio do ara::core::Result:

• Se a alocação de memória no lado do host ou do acelerador falhar durante uma chamada de Create, o erro ShwaErrorCode::kMemoryNotAllocated será retornado ([AP_SWS_SHWA_00209], [AP_SWS_SHWA_00210], [AP_SWS_SHWA_00211], [AP_SWS_SHWA_00212], [AP_SWS_SHWA_00213], [AP_SWS_SHWA_00214]). A semântica de reversão definida para isso é ShwaErrorCode::kRuntime.
• Se for consultada via GetProperty<PropertyT>() uma propriedade não suportada pelo buffer ou pela plataforma, o resultado fornecerá o código de erro ShwaErrorCode::kFeatureNotSupported ([AP_SWS_SHWA_00216]). Para evitar este erro, recomenda-se a verificação prévia por meio de HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]).