clase ara::shwa::Range

La clase encapsula dimensiones de rango multidimensionales y suprime por completo una instanciación sin parámetros [AP_SWS_SHWA_01002]. Los objetos se originan de forma controlada a través de métodos estáticos de fábrica que, en caso de error, devuelven ShwaErrorCode::kRuntime y, en caso de éxito, proporcionan objetos de valor seguros frente a excepciones con semántica de copia y movimiento [AP_SWS_SHWA_01007]. La lectura de dimensiones individuales no es segura para subprocesos y requiere sincronización externa [AP_SWS_SHWA_01010].

más ›

Contexto

La clase de plantilla ara::shwa::Range representa, dentro del módulo de la Adaptive Platform shwa, una indicación de rango o de tamaño multidimensional (parametrizada de forma predeterminada mediante Dimensions = 1). En arquitecturas cercanas al hardware o de memoria compartida, un objeto de rango sirve típicamente como descripción estructurada de extensiones geométricas o dimensiones de búfer a lo largo de hasta tres ejes. Los interlocutores de interacción son principalmente componentes de aplicación y servicios de controlador que deben asignar, particionar o direccionar áreas de memoria. La clase encapsula las medidas discretas de las dimensiones y las protege frente a una construcción directa defectuosa, impidiendo objetos inicializados de forma incompleta o no válida mediante restricciones en la interfaz.

Ciclo de vida

El ciclo de vida de una instancia de ara::shwa::Range viene determinado por estrictas especificaciones de construcción. El constructor predeterminado sin parámetros está explícitamente eliminado [AP_SWS_SHWA_01002]. Con ello queda excluida una creación directa sin especificar las dimensiones. En su lugar, la creación se realiza exclusivamente a través de métodos estáticos de fábrica Create sobrecargados para variantes unidimensionales, bidimensionales o tridimensionales: para una dimensión con dim0 [AP_SWS_SHWA_01007], para dos dimensiones con dim0 y dim1 [AP_SWS_SHWA_01008], así como para tres dimensiones con dim0, dim1 y dim2 [AP_SWS_SHWA_01009]. Cada una de estas funciones de fábrica devuelve un ara::core::Result<Range>.

Tras una creación exitosa, la clase se comporta como un tipo de valor (Value Type) completo. Proporciona tanto el constructor de copia [AP_SWS_SHWA_01003] como el operador de asignación por copia [AP_SWS_SHWA_01004] como operaciones estandarizadas y seguras frente a excepciones (noexcept = default). De forma complementaria, están disponibles un constructor de movimiento [AP_SWS_SHWA_01005] y un operador de asignación por movimiento [AP_SWS_SHWA_01006] con la misma seguridad frente a excepciones. De este modo, las instancias poseen una clara semántica de valor y pueden transferirse o mantenerse en contenedores sin problemas. En cuanto a la concurrencia, los métodos estáticos de fábrica están diseñados para ser seguros para subprocesos, mientras que los métodos de inspección de lectura GetDimension0 [AP_SWS_SHWA_01010], GetDimension1 [AP_SWS_SHWA_01011] y GetDimension2 [AP_SWS_SHWA_01012] están clasificados por la especificación como no seguros para subprocesos.

Ruta de uso

Una ruta de uso típica comprende la creación de una instancia de rango a través de la interfaz estática, la validación del resultado y la posterior lectura de las dimensiones para pasos de configuración o de asignación. El siguiente diagrama de secuencia ilustra este flujo.

Diagrama de secuencia: flujo de uso típico durante la creación y consulta de dimensiones. Fuentes: [AP_SWS_SHWA_01007], [AP_SWS_SHWA_01010]

En el primer paso, la aplicación llama a una de las sobrecargas de fábrica, por ejemplo Create(dim0) [AP_SWS_SHWA_01007] para un rango unidimensional o Create(dim0, dim1) [AP_SWS_SHWA_01008] y Create(dim0, dim1, dim2) [AP_SWS_SHWA_01009] para configuraciones multidimensionales. A continuación, la capa llamadora comprueba si el ara::core::Result devuelto ha tenido éxito. Si se dispone de un valor válido, el objeto Range se desreferencia o se mueve. Posteriormente, las funciones descendentes pueden consultar los tamaños de los ejes contenidos a través de GetDimension0 [AP_SWS_SHWA_01010], así como según sea necesario a través de GetDimension1 [AP_SWS_SHWA_01011] y GetDimension2 [AP_SWS_SHWA_01012], y utilizarlos para operaciones de búfer.

Escenarios de error

Al realizar la creación mediante Create, pueden presentarse condiciones de error que tengan como consecuencia el fallo de la inicialización. En este caso, la fábrica no devuelve un objeto inicializado, sino un resultado de error de tipo ShwaErrorCode::kRuntime («General runtime error») [AP_SWS_SHWA_01007], [AP_SWS_SHWA_01008], [AP_SWS_SHWA_01009]. Para todas las variantes de fábrica, la especificación garantiza una semántica de reversión y seguridad frente a excepciones (noexcept), de modo que, en caso de error, no queden estados parciales ni se originen inconsistencias.

Para los métodos inspectores GetDimension0 [AP_SWS_SHWA_01010], GetDimension1 [AP_SWS_SHWA_01011] y GetDimension2 [AP_SWS_SHWA_01012] no se contemplan códigos de error de retorno; no obstante, la especificación los identifica como no seguros frente a excepciones (not exception safe) y no seguros para subprocesos (not thread-safe). Por lo tanto, el llamador asume la precondición de asegurar el acceso entre diferentes subprocesos. Además, es probable que invocar una consulta de dimensiones que exceda el número de dimensiones instanciado con el parámetro de plantilla Dimensions (por ejemplo, GetDimension2 en una configuración unidimensional) no esté permitido y genere errores. Pregunta Q-794519baf2ea8a5e (abierta)