classe ara::shwa::Range

La classe encapsule les dimensions de plages multidimensionnelles et empêche complètement toute instanciation sans paramètre [AP_SWS_SHWA_01002]. Les objets sont créés de manière contrôlée via des méthodes factory statiques qui renvoient ShwaErrorCode::kRuntime en cas d'erreur et fournissent, en cas de succès, des objets valeurs sûrs vis-à-vis des exceptions dotés d'une sémantique de copie et de déplacement [AP_SWS_SHWA_01007]. La lecture de dimensions individuelles n'est pas thread-safe et requiert une synchronisation externe [AP_SWS_SHWA_01010].

plus ›

Contexte

La classe template ara::shwa::Range représente, au sein du module shwa de l'Adaptive Platform, une indication de plage ou de taille multidimensionnelle (paramétrée par défaut via Dimensions = 1). Dans les architectures proches du matériel ou à mémoire partagée, un objet de plage sert typiquement de description structurée d'étendues géométriques ou de dimensions de tampons sur jusqu'à trois axes. Les partenaires d'interaction sont avant tout des composants applicatifs et des services de pilotes qui doivent allouer, partitionner ou adresser des zones mémoire. La classe encapsule les dimensions discrètes des axes et les protège contre une construction directe incorrecte, les objets incomplètement ou invalidement initialisés étant empêchés par des restrictions d'interface.

Cycle de vie

Le cycle de vie d'une instance de ara::shwa::Range est déterminé par des règles de construction strictes. Le constructeur par défaut sans paramètre est explicitement supprimé [AP_SWS_SHWA_01002]. Une création directe sans spécification des dimensions est ainsi exclue. Au lieu de cela, la création s'effectue exclusivement via des méthodes factory statiques Create surchargées pour des variantes à une, deux ou trois dimensions : pour une dimension avec dim0 [AP_SWS_SHWA_01007], pour deux dimensions avec dim0 et dim1 [AP_SWS_SHWA_01008], et pour trois dimensions avec dim0, dim1 et dim2 [AP_SWS_SHWA_01009]. Chacune de ces fonctions factory renvoie un ara::core::Result<Range>.

Après une création réussie, la classe se comporte comme un type valeur à part entière (Value Type). Elle met à disposition aussi bien le constructeur de copie [AP_SWS_SHWA_01003] que l'opérateur d'assignation par copie [AP_SWS_SHWA_01004] sous forme d'opérations standardisées et sûres vis-à-vis des exceptions (noexcept = default). En complément, un constructeur de déplacement [AP_SWS_SHWA_01005] et un opérateur d'assignation par déplacement [AP_SWS_SHWA_01006] présentant la même sécurité vis-à-vis des exceptions sont disponibles. Les instances possèdent ainsi une sémantique de valeur claire et peuvent être transmises sans difficulté ou conservées dans des conteneurs. Concernant la concurrence, les méthodes factory statiques sont conçues pour être thread-safe, tandis que les méthodes d'inspection en lecture GetDimension0 [AP_SWS_SHWA_01010], GetDimension1 [AP_SWS_SHWA_01011] et GetDimension2 [AP_SWS_SHWA_01012] sont classées comme non thread-safe par la spécification.

Parcours d'utilisation

Un chemin d'utilisation typique comprend la création d'une instance de plage via l'interface statique, la validation du résultat, puis l'extraction des dimensions pour les étapes de configuration ou d'allocation. Le diagramme de séquence suivant illustre ce déroulement.

Diagramme de séquence : déroulement d'utilisation typique lors de la création et de l'interrogation de dimensions. Sources : [AP_SWS_SHWA_01007], [AP_SWS_SHWA_01010]

Dans un premier temps, l'application appelle l'une des surcharges de la factory, par exemple Create(dim0) [AP_SWS_SHWA_01007] pour une plage unidimensionnelle ou Create(dim0, dim1) [AP_SWS_SHWA_01008] voire Create(dim0, dim1, dim2) [AP_SWS_SHWA_01009] pour des configurations multidimensionnelles. La couche appelante vérifie ensuite le succès du ara::core::Result retourné. Si une valeur valide est présente, l'objet Range est déréférencé ou déplacé. Ensuite, des fonctions en aval peuvent interroger les grandeurs d'axe contenues via GetDimension0 [AP_SWS_SHWA_01010] ainsi que, selon les besoins, via GetDimension1 [AP_SWS_SHWA_01011] et GetDimension2 [AP_SWS_SHWA_01012], et les utiliser pour des opérations sur les tampons.

Scénarios d'erreur

Lors de la création au moyen de Create, des conditions d'erreur peuvent survenir et entraîner l'échec de l'initialisation. Dans ce cas, la factory ne renvoie pas d'objet initialisé, mais un résultat d'erreur de type ShwaErrorCode::kRuntime (« General runtime error ») [AP_SWS_SHWA_01007], [AP_SWS_SHWA_01008], [AP_SWS_SHWA_01009]. Pour toutes les variantes de la factory, la spécification garantit une sémantique de rollback et une sécurité vis-à-vis des exceptions (noexcept), de sorte qu'aucun état partiel ne subsiste et qu'aucune incohérence ne soit générée en cas d'erreur.

Aucun code d'erreur de retour n'est prévu pour les méthodes d'inspection GetDimension0 [AP_SWS_SHWA_01010], GetDimension1 [AP_SWS_SHWA_01011] et GetDimension2 [AP_SWS_SHWA_01012] ; cependant, la spécification les désigne comme non sûres vis-à-vis des exceptions (not exception safe) et non thread-safe (not thread-safe). Il incombe donc à l'appelant de respecter la précondition consistant à sécuriser l'accès entre les threads. De plus, l'appel d'une interrogation de dimension dépassant le nombre de dimensions instancié avec le paramètre template Dimensions (par exemple GetDimension2 dans le cas d'une configuration unidimensionnelle) devrait être non autorisé et entraîner des erreurs. Question Q-794519baf2ea8a5e (ouverte)