class ara::shwa::Id

Die Template-Klasse ara::shwa::Id kapselt mehrdimensionale Identifikatoren im Modul shwa und erzwingt eine kontrollierte Instanziierung über statische Fabrikmethoden wie Create [AP_SWS_SHWA_00707]. Als kopier- und verschiebbares Wertobjekt erlaubt sie den Zugriff auf einzelne Dimensionsindizes mittels Get und Set [AP_SWS_SHWA_00710]. Da Lese- und Schreibzugriffe sowie mehrdimensionale Fabriken nicht threadsicher sind, obliegt die notwendige Synchronisation der aufrufenden Anwendung.

mehr ›

Kontext

Die Template-Klasse ara::shwa::Id repräsentiert innerhalb des Moduls shwa eine mehrdimensionale Identifikation oder Indexierung für Shared-Memory- bzw. Hardware-Beschleunigerstrukturen. Sie kapselt Koordinaten bzw. Dimensionsindizes, die über statische Fabrikmethoden instanziiert und anschließend abgefragt oder modifiziert werden können. Die Klasse ist als final deklariert und parametrisiert die Anzahl der Dimensionen über den Template-Parameter Dimensions mit dem Standardwert 1. Als Interaktionspartner treten typischerweise Anwendungskomponenten auf, die strukturierte Zugriffe auf Beschleuniger-Puffer oder Speicherressourcen adressieren müssen. Dabei dient ein Instanzobjekt von ara::shwa::Id als kompaktes Wertobjekt zur dimensionsbezogenen Adressierung.

Lebenszyklus

Die Instanziierung von ara::shwa::Id unterliegt strengen Vorgaben: Der Standardkonstruktor ist explizit gelöscht [AP_SWS_SHWA_00702]. Eine direkte, uninitialisierte Objekterzeugung ist damit ausgeschlossen. Stattdessen erfolgt die Erzeugung kontrolliert über statische Fabrikfunktionen Create, welche das Objekt gekapselt in einem ara::core::Result zurückgeben [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Je nach geforderter Dimensionalität stehen Überladungen für eine Dimension [AP_SWS_SHWA_00707], zwei Dimensionen [AP_SWS_SHWA_00708] oder drei Dimensionen [AP_SWS_SHWA_00709] bereit.

Hinsichtlich der Besitzverhältnisse verhält sich ara::shwa::Id wie ein reguläres Wertobjekt. Es implementiert sowohl den Kopierkonstruktor [AP_SWS_SHWA_00703] als auch den Kopierzuweisungsoperator [AP_SWS_SHWA_00704] als standardisiert (default) und ausnahmesicher (noexcept). Ebenso stehen der Bewegungskonstruktor [AP_SWS_SHWA_00705] und der Bewegungszuweisungsoperator [AP_SWS_SHWA_00706] mit noexcept zur Verfügung. Instanzen können somit effizient in Containern abgelegt, per Wert übergeben oder zwischen Programmteilen verschoben werden. Besondere Beachtung erfordert die Thread-Sicherheit: Während die eindimensionale Fabrikmethode als threadsicher spezifiziert ist [AP_SWS_SHWA_00707], sind die zwei- und dreidimensionalen Fabrikmethoden explizit als nicht threadsicher ausgewiesen [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Bei parallelen Initialisierungen mehrdimensionaler Indizes müssen Aufrufer entsprechende Synchronisationsmaßnahmen vorsehen.

Nutzungspfad

Der typische Nutzungsablauf umfasst die kontrollierte Instanziierung über den passenden Fabrikaufruf, die Überprüfung des Result-Objekts sowie anschließende Lese- und Schreiboperationen auf den einzelnen Dimensionen. Zunächst ruft die Anwendung Create mit den gewünschten Dimensionsgrenzen bzw. Indexwerten auf. Nach erfolgreicher Rückgabe eines ara::core::Result<Id> wird der darin enthaltene Wert entpackt. Über die konstante Methode Get kann der Indexwert für eine bestimmte Dimension abgefragt werden [AP_SWS_SHWA_00710]. Bei Bedarf lässt sich der Wert einer bestimmten Dimension über Set nachträglich verändern [AP_SWS_SHWA_00711]. Beide Methoden (Get und Set) sind als nicht threadsicher eingestuft; gleichzeitige Zugriffe auf dieselbe Instanz aus mehreren Threads müssen extern synchronisiert werden.

Sequenzdiagramm: Typischer Ablauf von Fabrikerzeugung, Werteabfrage und nachträglicher Modifikation eines Id-Objekts. Quellen: [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]

Fehlerszenarien

Bei der Erzeugung über die statischen Create-Methoden können Laufzeitfehler auftreten. Schlägt die Instanziierung fehl, liefert die Fabrikmethode ein ara::core::Result, das den Fehlercode ShwaErrorCode::kRuntime enthält [AP_SWS_SHWA_00707], [AP_SWS_SHWA_00708], [AP_SWS_SHWA_00709]. Aufrufer müssen daher zwingend den Rückgabewert mittels HasValue() prüfen, bevor auf die Instanz zugegriffen wird. Sämtliche Create-Funktionen garantieren Rollback-Semantik und sind als ausnahmesicher (noexcept) deklariert.

Im laufenden Betrieb bei den Methoden Get und Set ist darauf zu achten, dass diese laut Spezifikation nicht ausnahmesicher sind (not exception safe) und nicht threadsicher arbeiten [AP_SWS_SHWA_00710], [AP_SWS_SHWA_00711]. Interpretation: Die Übergabe unzulässiger Dimensionswerte außerhalb des gültigen Wertebereichs dürfte zu undefiniertem Verhalten oder Ausnahmen führen, da für fehlerhafte Parameter an diesen Methoden keine separaten Fehlercodes definiert sind. Frage Q-6983f5f27702e6e8 (offen) Aufrufer müssen vor dem Aufruf sicherstellen, dass das Argument dimension innerhalb der gültigen Grenzen der Instanz liegt.