clase ara::shwa::Buffer

La plantilla de clase sirve para la gestión de búferes de memoria multidimensionales para la aceleración segura por hardware en la Adaptive Platform SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform». Dado que todas las operaciones por defecto, de copia y de movimiento están eliminadas, la creación se realiza exclusivamente a través de métodos de fábrica estáticos como [AP_SWS_SHWA_00209] como puntero retenido en exclusiva. La memoria se puede adaptar mediante propiedades y asignadores configurables, mientras que los accesos de lectura a las propiedades no están diseñados para ser seguros para hilos (thread-safe). Las reservas de memoria fallidas se notifican al llamante mediante códigos de error definidos.

más ›

Contexto

La clase plantilla ara::shwa::Buffer constituye en el módulo Safe Hardware Acceleration (SHWA) de la Adaptive Platform una abstracción central para el encapsulamiento y la gestión de regiones de memoria multidimensionales. Como se expone en la arquitectura del sistema, las Adaptive Applications, así como los clústeres funcionales, interactúan típicamente con una combinación de múltiples colas (Queues), dispositivos aceleradores (Devices) y búferes (SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform»). En este contexto, los búferes proporcionan la memoria requerida para las operaciones de aceleración a nivel de host o de dispositivo, y pueden configurarse opcionalmente mediante asignadores específicos de la aplicación ([AP_SWS_SHWA_00210]) o punteros de datos del host.

Diagrama de contexto: integración del búfer en la interacción funcional de aplicaciones, dispositivos, colas y asignadores. Fuentes: SWS_SafeHardwareAcceleration §7.1 «High Level Design of Safe Hardware Acceleration in an Adaptive Platform», [AP_SWS_SHWA_00210].

Ciclo de vida

El ciclo de vida de una instancia de búfer está sujeto a estrictas restricciones semánticas. Para garantizar relaciones de propiedad inequívocas, tanto el constructor por defecto ([AP_SWS_SHWA_00202]) como el constructor de copia ([AP_SWS_SHWA_00203]) y el operador de asignación por copia ([AP_SWS_SHWA_00204]) están eliminados. Asimismo, el constructor de movimiento ([AP_SWS_SHWA_00205]) y el operador de asignación por movimiento ([AP_SWS_SHWA_00206]) están explícitamente eliminados. Interpretación: Es probable que esto impida que los recursos de búfer o las relaciones de hardware se dupliquen o desplacen en la memoria de manera incontrolada. Pregunta Q-dcabd66fa9f3ec2a (abierta)

Por consiguiente, la creación se realiza exclusivamente a través de métodos de fábrica estáticos de la familia de sobrecargas Create, los cuales, en caso de éxito, devuelven un std::unique_ptr<Buffer> encapsulado en un ara::core::Result. Para ello se dispone de diferentes rutas de construcción:

• Creación con región de búfer y lista opcional de propiedades: segura para hilos (thread-safe) ([AP_SWS_SHWA_00209]).
• Creación con región de búfer, asignador dedicado y lista de propiedades: segura para hilos (thread-safe) ([AP_SWS_SHWA_00210]).
• Creación sobre la base de punteros de datos de host existentes con región de búfer: segura para hilos (thread-safe) tanto para punteros modificables ([AP_SWS_SHWA_00211]) como para punteros a datos constantes ([AP_SWS_SHWA_00213]).
• Creación con puntero constante a datos de host, región de búfer y asignador: segura para hilos (thread-safe) ([AP_SWS_SHWA_00214]).
• Creación directa únicamente a través de un asignador: no segura para hilos (no thread-safe) ([AP_SWS_SHWA_00212]).

El control permanece en el contexto llamante tras una creación exitosa a través de std::unique_ptr. Es de esperar que la destrucción del objeto al expirar el puntero inteligente libere automáticamente la región de memoria subyacente a través del asignador respectivo. Pregunta Q-aa2b5642b8527803 (abierta)

Ruta de uso

Una ruta de uso típica comienza con la asignación e inicialización del búfer a través de uno de los métodos de fábrica seguros para hilos (thread-safe), como [AP_SWS_SHWA_00209]. Tras una instanciación exitosa, la aplicación puede verificar si se han depositado propiedades específicas para este búfer invocando HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]). Si la propiedad deseada está presente, su valor concreto se puede leer de forma síncrona a través de GetProperty<PropertyT>() ([AP_SWS_SHWA_00216]). Debe tenerse en cuenta que tanto HasProperty como GetProperty están declarados como no seguros para hilos (no thread-safe); por tanto, las consultas concurrentes sobre el mismo objeto de búfer deben sincronizarse en la aplicación.

Diagrama de secuencia: secuencia típica durante la instanciación mediante la fábrica y posterior consulta de propiedades. Fuentes: [AP_SWS_SHWA_00209], [AP_SWS_SHWA_00215], [AP_SWS_SHWA_00216].

Escenarios de error

Todos los métodos de fábrica y de inspección están declarados con noexcept y ofrecen una seguridad contra excepciones (exception safe) sin restricciones. Los errores se señalizan a través de ara::core::Result:

• Si en una llamada a Create falla la asignación de memoria en el lado del host o del acelerador, se devuelve el error ShwaErrorCode::kMemoryNotAllocated ([AP_SWS_SHWA_00209], [AP_SWS_SHWA_00210], [AP_SWS_SHWA_00211], [AP_SWS_SHWA_00212], [AP_SWS_SHWA_00213], [AP_SWS_SHWA_00214]). En este caso, se define ShwaErrorCode::kRuntime como semántica de reversión (rollback).
• Si a través de GetProperty<PropertyT>() se consulta una propiedad no soportada por el búfer o por la plataforma, el resultado devuelve el código de error ShwaErrorCode::kFeatureNotSupported ([AP_SWS_SHWA_00216]). Para evitar este error, se recomienda realizar una comprobación previa mediante HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]).