classe ara::shwa::Id

La classe template ara::shwa::Id encapsule des identifiants multidimensionnels dans le module shwa et impose une instanciation contrôlée via des méthodes fabriques statiques telles que Create [AP_SWS_SHWA_00707]. En tant qu'objet-valeur copiable et déplaçable, elle permet l'accès à des indices de dimensions individuels au moyen de Get et Set [AP_SWS_SHWA_00710]. Dans la mesure où les accès en lecture et en écriture ainsi que les fabriques multidimensionnelles ne sont pas thread-safe, la synchronisation nécessaire incombe à l'application appelante.

plus ›

Contexte

La classe modèle ara::shwa::Id représente, au sein du module shwa, une identification ou une indexation multidimensionnelle pour les structures d'accélérateur matériel ou de mémoire partagée. Elle encapsule des coordonnées ou des indices de dimensions qui peuvent être instanciés via des méthodes de fabrique statiques, puis interrogés ou modifiés. La classe est déclarée en tant que final et paramètre le nombre de dimensions via le paramètre de modèle Dimensions avec la valeur par défaut 1. Les partenaires d'interaction typiques sont des composants d'application qui doivent adresser des accès structurés à des mémoires tampons d'accélérateur ou à des ressources mémoire. Un objet instance de ara::shwa::Id sert alors d'objet-valeur compact pour l'adressage lié aux dimensions.

Cycle de vie

L'instanciation de ara::shwa::Id est soumise à des exigences strictes : le constructeur par défaut est explicitement supprimé [AP_SWS_SHWA_00702]. Une création d'objet directe et non initialisée est donc exclue. La création s'effectue plutôt de manière contrôlée via des fonctions de fabrique statiques Create, qui renvoient l'objet encapsulé dans un ara::core::Result [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Selon la dimensionnalité requise, des surcharges sont disponibles pour une dimension [AP_SWS_SHWA_00707], deux dimensions [AP_SWS_SHWA_00708] ou trois dimensions [AP_SWS_SHWA_00709].

En ce qui concerne les relations de possession, ara::shwa::Id se comporte comme un objet-valeur standard. Elle implémente à la fois le constructeur de copie [AP_SWS_SHWA_00703] et l'opérateur d'assignation par copie [AP_SWS_SHWA_00704] comme standardisés (default) et sûrs face aux exceptions (noexcept). De même, le constructeur de déplacement [AP_SWS_SHWA_00705] et l'opérateur d'assignation par déplacement [AP_SWS_SHWA_00706] sont disponibles avec noexcept. Les instances peuvent ainsi être efficacement stockées dans des conteneurs, transmises par valeur ou déplacées entre différentes parties du programme. La sécurité des threads requiert une attention particulière : alors que la méthode de fabrique unidimensionnelle est spécifiée comme sûre au niveau des threads [AP_SWS_SHWA_00707], les méthodes de fabrique bi- et tridimensionnelles sont explicitement indiquées comme non sûres au niveau des threads [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. En cas d'initialisations parallèles d'indices multidimensionnels, les appelants doivent prévoir des mesures de synchronisation appropriées.

Parcours d'utilisation

Le flux d'utilisation typique comprend l'instanciation contrôlée via l'appel de fabrique approprié, la vérification de l'objet Result ainsi que les opérations de lecture et d'écriture consécutives sur les différentes dimensions. Dans un premier temps, l'application appelle Create avec les limites de dimension ou les valeurs d'indice souhaitées. Après le retour réussi d'un ara::core::Result<Id>, la valeur qu'il contient est désencapsulée. La méthode constante Get permet de consulter la valeur d'indice pour une dimension donnée [AP_SWS_SHWA_00710]. Si nécessaire, la valeur d'une dimension spécifique peut être modifiée ultérieurement via Set [AP_SWS_SHWA_00711]. Les deux méthodes (Get et Set) sont classées comme non sûres au niveau des threads ; les accès simultanés à la même instance depuis plusieurs threads doivent être synchronisés de manière externe.

Diagramme de séquence : flux typique de création par fabrique, de consultation de valeur et de modification ultérieure d'un objet Id. Sources : [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]

Scénarios d'erreur

Des erreurs d'exécution peuvent survenir lors de la création via les méthodes statiques Create. Si l'instanciation échoue, la méthode de fabrique renvoie un ara::core::Result contenant le code d'erreur ShwaErrorCode::kRuntime [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Les appelants doivent donc impérativement vérifier la valeur de retour au moyen de HasValue() avant d'accéder à l'instance. Toutes les fonctions Create garantissent une sémantique de retour arrière (rollback) et sont déclarées sûres face aux exceptions (noexcept).

En cours d'exploitation avec les méthodes Get et Set, il convient de veiller à ce que celles-ci ne soient pas sûres face aux exceptions (not exception safe) et ne fonctionnent pas de manière sûre au niveau des threads d'après la spécification [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]. Interprétation : la transmission de valeurs de dimension non autorisées en dehors de la plage de valeurs valide devrait entraîner un comportement indéfini ou des exceptions, étant donné qu'aucun code d'erreur distinct n'est défini pour les paramètres erronés sur ces méthodes. Question Q-6983f5f27702e6e8 (ouverte) Avant l'appel, les appelants doivent s'assurer que l'argument dimension se situe dans les limites valides de l'instance.