klasse ara::shwa::Queue

De niet-kopieerbare klasse ara::shwa::Queue dient voor de veilige overdracht van rekentaken aan versnellingshardware in samenspel met devices en buffers SWS_SafeHardwareAcceleration p. 22 “Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform”. Na de creatie via de factory-methode Create() worden taken met Submit() ingediend en via Wait() of WaitFor() gesynchroniseerd [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00914]. Aangezien objectmethoden niet thread-safe zijn en bij uitvoeringsfouten geen rollback-semantiek van kracht is, moet worden gelet op externe thread-synchronisatie en data-integriteit [AP_SWS_SHWA_00912].

meer ›

Context

De klasse ara::shwa::Queue vormt in het Adaptive Platform het centrale uitvoeringskanaal voor veilige hardwareversnelling. Zoals het totale ontwerp illustreert, interageren applicaties typisch met een combinatie van meerdere queues, devices en buffers SWS_SafeHardwareAcceleration p. 22 “Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform”. Binnen dit samenspel neemt de queue de taak op zich om rekentaken of versnellingsopdrachten in ontvangst te nemen en door te sturen naar het onderliggende hardware-device. Via GetDevice() kan het toegewezen device worden opgevraagd [AP_SWS_SHWA_00910]. Bovendien kan via IsInOrder() worden bepaald of opdrachten binnen de queue strikt sequentieel worden verwerkt [AP_SWS_SHWA_00911]. Specifieke capaciteiten of parameters van de queue kunnen vooraf via HasProperty() worden gecontroleerd [AP_SWS_SHWA_00915] en met GetProperty() worden opgehaald [AP_SWS_SHWA_00916].

Contextdiagram: inbedding van de queue tussen applicatie, hardware-device en foutafhandeling. Bronnen: SWS_SafeHardwareAcceleration p. 22 “Figure 7.1: High Level Design of Safe Hardware Acceleration in an Adaptive Platform”, [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00910].

Levenscyclus

Instanties van ara::shwa::Queue zijn onderworpen aan een strikt eigendomsmodel. Zowel de standaardconstructor [AP_SWS_SHWA_00902] als kopieer- en verplaatsingsoperaties zijn expliciet verwijderd: copy-constructor [AP_SWS_SHWA_00903], copy-assignment [AP_SWS_SHWA_00904], move-constructor [AP_SWS_SHWA_00905] en move-assignment [AP_SWS_SHWA_00906] zijn niet beschikbaar. Een queue is zodoende noch kopieerbaar noch verplaatsbaar (interpretatie: ze vertegenwoordigt een vast verankerde resource). Vraag Q-9ce33460e375c45f (open)

De creatie vindt uitsluitend plaats via statische factory-methoden Create(), die het object ingekapseld in een std::unique_ptr<Queue> binnen een ara::core::Result retourneren. De instantiatie kan hetzij aan de hand van een bestaande Device-referentie [AP_SWS_SHWA_00909], hetzij via een generieke DeviceSelector [AP_SWS_SHWA_00908] worden uitgevoerd. Beide varianten accepteren daarnaast een ErrorHandler en een optionele PropertyList. Met betrekking tot concurrency zijn de factory-functies Create() gespecificeerd als thread-safe [AP_SWS_SHWA_00908], [AP_SWS_SHWA_00909]. Alle reguliere elementfuncties van de gecreëerde instantie – waaronder Submit(), Wait() en GetDevice() – zijn daarentegen gedeclareerd als niet thread-safe [AP_SWS_SHWA_00910], [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914]; gelijktijdige toegangen vanuit meerdere threads moeten bijgevolg aan applicatiezijde worden gesynchroniseerd.

Gebruikspad

Het reguliere verloop is onderverdeeld in de fasen creatie, opdrachtinplanning en synchronisatie:

1. Queue creëren: De applicatie creëert de queue via Create() met een concreet device of DeviceSelector evenals foutafhandelingsroutines [AP_SWS_SHWA_00909].
2. Configuratie en controle: Optioneel worden eigenschappen gevalideerd met HasProperty() [AP_SWS_SHWA_00915] en IsInOrder() [AP_SWS_SHWA_00911].
3. Opdracht verzenden: Met Submit() wordt een taak aan de hardware overgedragen. Hierbij kan hetzij een dedicated ErrorHandler worden doorgegeven [AP_SWS_SHWA_00912], hetzij een secundaire queue (secondaryQueue) voor uitwijk- resp. vervolgpaden worden opgegeven [AP_SWS_SHWA_00913]. De methode retourneert een ara::core::Result<Event>.
4. Synchroniseren: De applicatie synchroniseert op de voltooiing van de ingediende taken. Hiervoor staat de onbegrensde Wait() [AP_SWS_SHWA_00914] of de in tijd gelimiteerde WaitFor() onder opgave van een duur in milliseconden ter beschikking [AP_SWS_SHWA_00917].

Sequentiediagram: typisch aanroepverloop van creatie via opdrachtafgifte tot synchronisatie. Bronnen: [AP_SWS_SHWA_00909], [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914].

Foutscenario's

De methoden melden foutsituaties via het foutcodetype ShwaErrorCode in ara::core::Result:

• Resource- en parameterconflicten: Faalt Create(), dan kunnen onder andere ShwaErrorCode::kResourceBusy, ShwaErrorCode::kInvalidParameter of ShwaErrorCode::kFeatureNotSupported optreden [AP_SWS_SHWA_00909]. Voor deze creatiefouten gelden rollback-semantieken.
• Aanroep van ongeldige objecten: Worden methoden zoals Submit(), Wait() of WaitFor() uitgevoerd op reeds vernietigde of ongeldige objecten, dan beantwoordt de API dit met ShwaErrorCode::kInvalidObject [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914], [AP_SWS_SHWA_00917].
• Uitvoeringsfouten en gegevensintegriteit: Als tijdens de taakverwerking een fout optreedt (ShwaErrorCode::kTaskExecutionFailure of algemener ShwaErrorCode::kRuntime), geldt er expliciet geen rollback-semantiek (no_rollback_semantics). De specificatie vereist in deze gevallen dat de bij de uitvoering betrokken gegevens als onbedoeld gewijzigd moeten worden beschouwd [AP_SWS_SHWA_00912], [AP_SWS_SHWA_00914].
• Time-out: Bij synchroon wachten via WaitFor() signaleert ShwaErrorCode::kTimedOut het verstrijken van de opgegeven termijn; ook hier moeten getroffen gegevens als potentieel inconsistent worden geclassificeerd [AP_SWS_SHWA_00917].