klasse ara::shwa::Buffer

De class-template dient voor het beheer van meerdimensionale geheugenbuffers voor veilige hardwareversnelling in het Adaptive Platform SWS_SafeHardwareAcceleration §7.1 “High Level Design of Safe Hardware Acceleration in an Adaptive Platform”. Omdat alle standaard-, kopieer- en verplaatsbewerkingen zijn verwijderd, vindt het aanmaken uitsluitend plaats via statische factory-methoden zoals [AP_SWS_SHWA_00209] als exclusief gehouden pointer. Via configureerbare eigenschappen en allocators kan het geheugen worden aangepast, terwijl leestoegangen tot eigenschappen niet-thread-safe zijn opgezet. Mislukte geheugenreserveringen worden via gedefinieerde foutcodes teruggemeld aan de aanroeper.

meer ›

Context

De template-klasse ara::shwa::Buffer vormt in de module Safe Hardware Acceleration (SHWA) van het Adaptive Platform een centrale abstractie voor de inkapseling en het beheer van meerdimensionale geheugengebieden. Zoals uiteengezet in de systeemarchitectuur, interageren Adaptive Applications en functionele clusters typisch met een combinatie van meerdere wachtrijen (queues), versnellerapparaten (devices) en buffers (SWS_SafeHardwareAcceleration §7.1 “High Level Design of Safe Hardware Acceleration in an Adaptive Platform”). Buffers stellen daarbij het geheugen ter beschikking dat nodig is voor versnellingsoperaties op host- of device-niveau, en kunnen optioneel worden geconfigureerd met applicatiespecifieke allocators ([AP_SWS_SHWA_00210]) of host-datapointer.

Contextdiagram: Inbedding van de buffer in de functionele wisselwerking van applicaties, apparaten, wachtrijen en allocators. Bronnen: SWS_SafeHardwareAcceleration §7.1 “High Level Design of Safe Hardware Acceleration in an Adaptive Platform”, [AP_SWS_SHWA_00210].

Levenscyclus

De levenscyclus van een bufferinstantie is onderhevig aan strikte semantische beperkingen. Om eenduidige eigendomsverhoudingen te waarborgen, zijn zowel de standaardconstructor ([AP_SWS_SHWA_00202]) als de kopieerconstructor ([AP_SWS_SHWA_00203]) en kopiertoewijzingsoperator ([AP_SWS_SHWA_00204]) verwijderd. Eveneens zijn de move-constructor ([AP_SWS_SHWA_00205]) en de move-toewijzingsoperator ([AP_SWS_SHWA_00206]) expliciet verwijderd. Interpretatie: Dit voorkomt vermoedelijk dat bufferbronnen of hardwarerelaties ongecontroleerd in het geheugen worden gedupliceerd of verplaatst. Vraag Q-dcabd66fa9f3ec2a (open)

Het aanmaken vindt daarom uitsluitend plaats via statische factory-methoden uit de overladingsfamilie Create, die bij succes een std::unique_ptr<Buffer> ingekapseld in een ara::core::Result retourneren. Daarbij staan verschillende constructiepaden ter beschikking:

• Aanmaken met bufferbereik en optionele eigenschappenlijst: thread-safe ([AP_SWS_SHWA_00209]).
• Aanmaken met bufferbereik, toegewijde allocator en eigenschappenlijst: thread-safe ([AP_SWS_SHWA_00210]).
• Aanmaken op basis van bestaande host-datapointer met bufferbereik: thread-safe zowel voor modificeerbare pointers ([AP_SWS_SHWA_00211]) als voor constante datapointer ([AP_SWS_SHWA_00213]).
• Aanmaken met constante host-datapointer, bufferbereik en allocator: thread-safe ([AP_SWS_SHWA_00214]).
• Direct aanmaken uitsluitend via een allocator: niet thread-safe ([AP_SWS_SHWA_00212]).

Het eigendom blijft na succesvol aanmaken bij de aanroepende context via std::unique_ptr. De vernietiging van het object bij het verlopen van de smart pointer geeft vermoedelijk het onderliggende geheugengebied automatisch vrij via de desbetreffende allocator. Vraag Q-aa2b5642b8527803 (open)

Gebruikspad

Een typisch gebruikspad begint met de allocatie en initialisatie van de buffer via een van de thread-safe factory-methoden zoals [AP_SWS_SHWA_00209]. Na succesvolle instantiëring kan de applicatie verifiëren of specifieke eigenschappen voor deze buffer zijn vastgelegd door HasProperty<PropertyT>() aan te roepen ([AP_SWS_SHWA_00215]). Is de gewenste eigenschap aanwezig, dan kan de concrete waarde ervan synchroon via GetProperty<PropertyT>() worden uitgelezen ([AP_SWS_SHWA_00216]). Men dient er rekening mee te houden dat zowel HasProperty als GetProperty als niet thread-safe zijn gedeclareerd; gelijktijdige bevragingen op hetzelfde bufferobject moeten daarom aan applicatiezijde worden gesynchroniseerd.

Sequentiediagram: Typische volgorde bij instantiëring via de factory en aansluitende bevraging van eigenschappen. Bronnen: [AP_SWS_SHWA_00209], [AP_SWS_SHWA_00215], [AP_SWS_SHWA_00216].

Foutscenario's

Alle factory- en inspectiemethoden zijn met noexcept gedeclareerd en bieden onbeperkte exceptieveiligheid (exception safe). Fouten worden via de ara::core::Result gesignaleerd:

• Mislukt bij een aanroep van Create de geheugenallocatie aan host- of versnellerzijde, dan wordt de fout ShwaErrorCode::kMemoryNotAllocated geretourneerd ([AP_SWS_SHWA_00209], [AP_SWS_SHWA_00210], [AP_SWS_SHWA_00211], [AP_SWS_SHWA_00212], [AP_SWS_SHWA_00213], [AP_SWS_SHWA_00214]). Als rollback-semantiek is hierbij ShwaErrorCode::kRuntime gedefinieerd.
• Wordt via GetProperty<PropertyT>() een eigenschap opgevraagd die niet door de buffer of het platform wordt ondersteund, dan levert het resultaat de foutcode ShwaErrorCode::kFeatureNotSupported op ([AP_SWS_SHWA_00216]). Om deze fout te voorkomen, wordt een voorafgaande controle middels HasProperty<PropertyT>() aanbevolen ([AP_SWS_SHWA_00215]).