clase ara::shwa::Queue

La clase no copiable ara::shwa::Queue sirve para la transferencia segura de tareas de cálculo a hardware de aceleración en interacción con devices y buffers SWS_SafeHardwareAcceleration p. 22 «Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Tras la creación mediante el método de factoría Create(), las tareas se envían con Submit() y se sincronizan a través de Wait() o WaitFor() [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00914]. Dado que los métodos del objeto no son seguros para hilos y en caso de errores de ejecución no se aplica semántica de rollback, se debe prestar atención a la sincronización externa de hilos y a la integridad de los datos [AP_SWS_SHWA_00912].

más ›

Contexto

La clase ara::shwa::Queue representa en la Adaptive Platform el canal central de ejecución para una aceleración de hardware segura. Como ilustra el diseño global, las aplicaciones interactúan típicamente con una combinación de varias queues, devices y buffers SWS_SafeHardwareAcceleration p. 22 «Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Dentro de esta interacción, la queue asume la tarea de recibir tareas de cálculo u órdenes de aceleración y reenviarlas al hardware device subyacente. A través de GetDevice() se puede consultar el device asignado [AP_SWS_SHWA_00910]. Además, a través de IsInOrder() se puede determinar si las órdenes se procesan de manera estrictamente secuencial dentro de la queue [AP_SWS_SHWA_00911]. Las capacidades o parámetros específicos de la queue pueden comprobarse previamente a través de HasProperty() [AP_SWS_SHWA_00915] y consultarse con GetProperty() [AP_SWS_SHWA_00916].

Diagrama de contexto: integración de Queue entre aplicación, hardware device y tratamiento de errores. Fuentes: 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

Las instancias de ara::shwa::Queue están sujetas a un estricto modelo de propiedad. Tanto el constructor por defecto [AP_SWS_SHWA_00902] como las operaciones de copia y movimiento están explícitamente eliminados: el constructor de copia [AP_SWS_SHWA_00903], la asignación por copia [AP_SWS_SHWA_00904], el constructor de movimiento [AP_SWS_SHWA_00905] y la asignación por movimiento [AP_SWS_SHWA_00906] no están disponibles. Por lo tanto, una queue no es ni copiable ni trasladable (interpretación: representa un recurso fijamente anclado). Pregunta Q-9ce33460e375c45f (abierta)

La creación se realiza exclusivamente a través de métodos de factoría estáticos Create(), los cuales devuelven el objeto encapsulado en un std::unique_ptr<Queue> dentro de un ara::core::Result. La instanciación puede llevarse a cabo bien a partir de una referencia de Device existente [AP_SWS_SHWA_00909], bien a través de un DeviceSelector genérico [AP_SWS_SHWA_00908]. Ambas variantes aceptan adicionalmente un ErrorHandler y una PropertyList opcional. En lo relativo a la concurrencia, las funciones de factoría Create() están especificadas como seguras para hilos [AP_SWS_SHWA_00908], [AP_SWS_SHWA_00909]. En cambio, todas las funciones miembro regulares de la instancia creada —entre ellas Submit(), Wait() y GetDevice()— están declaradas como no seguras para hilos [AP_SWS_SHWA_00910], [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914]; por consiguiente, los accesos simultáneos desde varios hilos deben sincronizarse del lado de la aplicación.

Ruta de uso

El desarrollo regular se divide en las fases de creación, planificación de órdenes y sincronización:

1. Crear queue: la aplicación crea la queue a través de Create() con un device concreto o DeviceSelector así como rutinas de tratamiento de errores [AP_SWS_SHWA_00909].
2. Configuración y comprobación: opcionalmente se validan propiedades con HasProperty() [AP_SWS_SHWA_00915] y IsInOrder() [AP_SWS_SHWA_00911].
3. Transmitir orden: con Submit() se transfiere una tarea al hardware. En este punto, se puede transferir un ErrorHandler dedicado [AP_SWS_SHWA_00912] o bien indicar una queue secundaria (secondaryQueue) para rutas alternativas o de continuación [AP_SWS_SHWA_00913]. El método devuelve un ara::core::Result<Event>.
4. Sincronizar: la aplicación se sincroniza con la finalización de las tareas enviadas. Para ello se dispone del Wait() ilimitado [AP_SWS_SHWA_00914] o del WaitFor() limitado temporalmente con indicación de una duración en milisegundos [AP_SWS_SHWA_00917].

Diagrama de secuencia: secuencia típica de llamadas desde la creación y el envío de órdenes hasta la sincronización. Fuentes: [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914].

Escenarios de error

Los métodos notifican casos de error a través del tipo de código de error ShwaErrorCode en el ara::core::Result:

• Conflictos de recursos y de parámetros: si falla Create(), pueden presentarse entre otros ShwaErrorCode::kResourceBusy, ShwaErrorCode::kInvalidParameter o ShwaErrorCode::kFeatureNotSupported [AP_SWS_SHWA_00909]. Para estos errores de creación se aplican semánticas de rollback.
• Invocación de objetos no válidos: si se ejecutan métodos como Submit(), Wait() o WaitFor() sobre objetos ya destruidos o no válidos, la API acusa esto con ShwaErrorCode::kInvalidObject [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914], [AP_SWS_SHWA_00917].
• Errores de ejecución e integridad de los datos: si se produce un error durante el procesamiento de la tarea (ShwaErrorCode::kTaskExecutionFailure o más generalmente ShwaErrorCode::kRuntime), explícitamente no existe semántica de rollback (no_rollback_semantics). La especificación exige en estos casos que los datos implicados en la ejecución deban considerarse modificados involuntariamente [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914].
• Tiempo de espera agotado: durante la espera sincronizadora mediante WaitFor(), ShwaErrorCode::kTimedOut señala la expiración del plazo predeterminado; también en este caso los datos afectados deben clasificarse como potencialmente inconsistentes [AP_SWS_SHWA_00917].