clase ara::shwa::Id

La clase plantilla ara::shwa::Id encapsula identificadores multidimensionales en el módulo shwa y fuerza una instanciación controlada mediante métodos de fábrica estáticos como Create [AP_SWS_SHWA_00707]. Como objeto de valor copiable y desplazable, permite el acceso a índices de dimensión individuales mediante Get y Set [AP_SWS_SHWA_00710]. Dado que los accesos de lectura y escritura, así como las fábricas multidimensionales, no son seguros para subprocesos, la sincronización necesaria recae en la aplicación que realiza la llamada.

más ›

Contexto

La clase plantilla ara::shwa::Id representa dentro del módulo shwa una identificación o indexación multidimensional para estructuras de aceleradores de hardware o de memoria compartida. Encapsula coordenadas o índices de dimensión que pueden instanciarse mediante métodos de fábrica estáticos y, a continuación, consultarse o modificarse. La clase está declarada como final y parametriza el número de dimensiones a través del parámetro de plantilla Dimensions con el valor predeterminado 1. Como interlocutores intervienen típicamente componentes de aplicación que deben direccionar accesos estructurados a búferes de acelerador o recursos de memoria. En este proceso, un objeto de instancia de ara::shwa::Id sirve como objeto de valor compacto para el direccionamiento referido a dimensiones.

Ciclo de vida

La instanciación de ara::shwa::Id está sujeta a requisitos estrictos: el constructor predeterminado está explícitamente eliminado [AP_SWS_SHWA_00702]. Por lo tanto, queda descartada una creación de objetos directa y no inicializada. En su lugar, la creación se realiza de forma controlada a través de funciones de fábrica estáticas Create, que devuelven el objeto encapsulado en un ara::core::Result [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Según la dimensionalidad requerida, están disponibles sobrecargas para una dimensión [AP_SWS_SHWA_00707], dos dimensiones [AP_SWS_SHWA_00708] o tres dimensiones [AP_SWS_SHWA_00709].

En cuanto a las relaciones de propiedad, ara::shwa::Id se comporta como un objeto de valor regular. Implementa tanto el constructor de copia [AP_SWS_SHWA_00703] como el operador de asignación por copia [AP_SWS_SHWA_00704] como estandarizados (default) y seguros frente a excepciones (noexcept). Asimismo, están disponibles el constructor de movimiento [AP_SWS_SHWA_00705] y el operador de asignación por movimiento [AP_SWS_SHWA_00706] con noexcept. Por consiguiente, las instancias pueden almacenarse eficazmente en contenedores, pasarse por valor o moverse entre partes del programa. La seguridad de subprocesos requiere especial atención: mientras que el método de fábrica unidimensional está especificado como seguro para subprocesos [AP_SWS_SHWA_00707], los métodos de fábrica bidimensionales y tridimensionales se designan explícitamente como no seguros para subprocesos [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. En caso de inicializaciones paralelas de índices multidimensionales, los llamadores deben prever las medidas de sincronización correspondientes.

Ruta de uso

El flujo de uso típico comprende la instanciación controlada a través de la llamada a la fábrica adecuada, la verificación del objeto Result, así como las posteriores operaciones de lectura y escritura en las dimensiones individuales. En primer lugar, la aplicación llama a Create con los límites de dimensión o valores de índice deseados. Tras la devolución satisfactoria de un ara::core::Result<Id>, se desempaqueta el valor contenido en él. Mediante el método constante Get se puede consultar el valor de índice para una dimensión determinada [AP_SWS_SHWA_00710]. Si es necesario, el valor de una dimensión determinada se puede modificar posteriormente a través de Set [AP_SWS_SHWA_00711]. Ambos métodos (Get y Set) están clasificados como no seguros para subprocesos; los accesos simultáneos a la misma instancia desde varios subprocesos deben sincronizarse externamente.

Diagrama de secuencia: flujo típico de creación por fábrica, consulta de valores y modificación posterior de un objeto Id. Fuentes: [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]

Escenarios de error

Durante la creación a través de los métodos estáticos Create pueden producirse errores de tiempo de ejecución. Si la instanciación falla, el método de fábrica suministra un ara::core::Result que contiene el código de error ShwaErrorCode::kRuntime [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Por lo tanto, los llamadores deben comprobar obligatoriamente el valor de retorno mediante HasValue() antes de acceder a la instancia. Todas las funciones Create garantizan semántica de reversión (rollback) y están declaradas como seguras frente a excepciones (noexcept).

En el funcionamiento continuo con los métodos Get y Set debe tenerse en cuenta que, según la especificación, estos no son seguros frente a excepciones (not exception safe) y no operan de forma segura para subprocesos [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]. Interpretación: la transmisión de valores de dimensión inadmisibles fuera del rango de valores válido probablemente provoque un comportamiento indefinido o excepciones, ya que no se han definido códigos de error independientes para parámetros erróneos en estos métodos. Pregunta Q-6983f5f27702e6e8 (abierta) Los llamadores deben asegurarse antes de la llamada de que el argumento dimension se encuentre dentro de los límites válidos de la instancia.