classe ara::shwa::Queue

A classe não copiável ara::shwa::Queue serve para a transferência segura de tarefas de computação para o hardware de aceleração em conjunto com devices e buffers SWS_SafeHardwareAcceleration p. 22 «Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Após a criação através do método factory Create(), as tarefas são submetidas com Submit() e sincronizadas através de Wait() ou WaitFor() [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00914]. Como os métodos de objeto não são thread-safe e nenhuma semântica de rollback se aplica em caso de erros de execução, deve-se atentar para a sincronização externa de threads e a integridade dos dados [AP_SWS_SHWA_00912].

mais ›

Contexto

A classe ara::shwa::Queue representa, na Adaptive Platform, o canal de execução central para aceleração de hardware segura. Conforme ilustra o design geral, as aplicações normalmente interagem com uma combinação de várias queues, devices e buffers SWS_SafeHardwareAcceleration p. 22 «Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Dentro dessa interação, a queue assume a tarefa de receber tarefas de computação ou ordens de aceleração e encaminhá-las para o hardware-device subjacente. Através de GetDevice(), é possível consultar o device associado [AP_SWS_SHWA_00910]. Além disso, pode-se determinar através de IsInOrder() se as ordens dentro da queue são processadas de forma estritamente sequencial [AP_SWS_SHWA_00911]. Capacidades ou parâmetros específicos da queue podem ser verificados previamente através de HasProperty() [AP_SWS_SHWA_00915] e obtidos com GetProperty() [AP_SWS_SHWA_00916].

Diagrama de contexto: integração da queue entre aplicação, hardware-device e tratamento de erros. Fontes: SWS_SafeHardwareAcceleration p. 22 «Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform», [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00910].

Ciclo de vida

Instâncias de ara::shwa::Queue estão sujeitas a um modelo de posse estrito. Tanto o construtor padrão [AP_SWS_SHWA_00902] quanto as operações de cópia e movimentação estão explicitamente excluídos: construtor de cópia [AP_SWS_SHWA_00903], atribuição por cópia [AP_SWS_SHWA_00904], construtor de movimentação [AP_SWS_SHWA_00905] e atribuição por movimentação [AP_SWS_SHWA_00906] não estão disponíveis. Uma queue, portanto, não é copiável nem movível (interpretação: ela representa um recurso fixamente ancorado). Pergunta Q-9ce33460e375c45f (aberta)

A instanciação ocorre exclusivamente através de métodos factory estáticos Create(), que retornam o objeto encapsulado em um std::unique_ptr<Queue> dentro de um ara::core::Result. A instanciação pode ser realizada tanto a partir de uma referência existente a Device [AP_SWS_SHWA_00909] quanto através de um DeviceSelector genérico [AP_SWS_SHWA_00908]. Ambas as variantes aceitam adicionalmente um ErrorHandler e uma PropertyList opcional. Em relação à concorrência, as funções factory Create() são especificadas como thread-safe [AP_SWS_SHWA_00908], [AP_SWS_SHWA_00909]. Todas as funções-membro regulares da instância criada — entre elas Submit(), Wait() e GetDevice() — são, por outro lado, declaradas como não thread-safe [AP_SWS_SHWA_00910], [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914]; acessos concorrentes a partir de múltiplas threads devem, portanto, ser sincronizados pelo lado da aplicação.

Caminho de utilização

O fluxo regular divide-se nas fases de criação, agendamento de tarefas e sincronização:

1. Criar queue: a aplicação cria a queue via Create() com um device concreto ou DeviceSelector, bem como rotinas de tratamento de erros [AP_SWS_SHWA_00909].
2. Configuração e verificação: opcionalmente, as propriedades são validadas com HasProperty() [AP_SWS_SHWA_00915] e IsInOrder() [AP_SWS_SHWA_00911].
3. Submeter ordem: com Submit(), uma tarefa é transferida para o hardware. Neste processo, pode-se passar um ErrorHandler dedicado [AP_SWS_SHWA_00912] ou indicar uma queue secundária (secondaryQueue) para caminhos de fallback ou subsequentes [AP_SWS_SHWA_00913]. O método retorna um ara::core::Result<Event>.
4. Sincronizar: a aplicação sincroniza na conclusão das tarefas submetidas. Para isso, está disponível o Wait() ilimitado [AP_SWS_SHWA_00914] ou o WaitFor() limitado no tempo com a especificação de uma duração em milissegundos [AP_SWS_SHWA_00917].

Diagrama de sequência: fluxo de chamada típico desde a criação, passando pelo envio da ordem, até a sincronização. Fontes: [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914].

Cenários de erro

Os métodos reportam casos de erro através do tipo de código de erro ShwaErrorCode no ara::core::Result:

• Conflitos de recursos e de parâmetros: se Create() falhar, podem ocorrer, entre outros, ShwaErrorCode::kResourceBusy, ShwaErrorCode::kInvalidParameter ou ShwaErrorCode::kFeatureNotSupported [AP_SWS_SHWA_00909]. Para esses erros de criação aplicam-se semânticas de rollback.
• Chamada de objetos inválidos: se métodos como Submit(), Wait() ou WaitFor() forem executados em objetos já destruídos ou inválidos, a API sinaliza isso com ShwaErrorCode::kInvalidObject [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914], [AP_SWS_SHWA_00917].
• Erros de execução e integridade de dados: se ocorrer um erro durante o processamento da tarefa (ShwaErrorCode::kTaskExecutionFailure ou, mais geralmente, ShwaErrorCode::kRuntime), não há explicitamente nenhuma semântica de rollback (no_rollback_semantics). A especificação exige, nesses casos, que os dados envolvidos na execução sejam considerados involuntariamente modificados [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914].
• Timeout: na espera sincronizadora via WaitFor(), ShwaErrorCode::kTimedOut sinaliza o término do prazo estipulado; também aqui os dados afetados devem ser classificados como potencialmente inconsistentes [AP_SWS_SHWA_00917].