class <SI-Namespace>::skeleton:: events::<Event>

Die Methode Allocate wird auf Skeleton-Ebene für ein Event aufgerufen ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 „Skeleton Class API’s“), um Speicher für die Übertragung von Event-Daten zu allozieren, wenn das Communication Management (ara::com) für die Verwaltung der Daten verantwortlich ist ([SWS_CM_90438]). Sie liefert eine Instanz vom Typ ara::com::SampleAllocateePtr<SampleType> zurück ([SWS_CM_90438]). Dieser Zeigertyp verhält sich konzeptionell wie ein std::unique_ptr<T>, sodass zu jedem Zeitpunkt nur eine Partei Eigentümer des Zeigers ist (ARAComAPI §6 „Event Allocate/Send sample Binding implementer hint“).

Hinsichtlich der Fehlerbehandlung und Ausnahme-Sicherheit ist Allocate als not exception safe spezifiziert ([SWS_CM_90438]). Die Spezifikation definiert zwei mögliche Verletzungen (Violations):

• SampleAllocationViolation: Es stehen nicht genügend Speicherressourcen zur Verfügung, um die Daten zu allozieren ([SWS_CM_90438]).
• AllocateUsageViolation: Die Allokation erfolgte unzulässigerweise über einen benutzerdefinierten Allokator ([SWS_CM_90438]).

Das Konzept hinter Allocate zielt primär auf die Unterstützung von Zero-Copy-Mechanismen ab, insbesondere bei Shared-Memory-basiertem IPC-Transport, wobei eine strikte Synchronisation zwischen Lesern und Schreibern vorausgesetzt wird (ARAComAPI §6 „Event Allocate/Send sample Binding implementer hint“). Implementierer müssen beachten, dass Serialisierungsanforderungen Zero-Copy zunichtemachen können, sofern Datentypen im Deployment nicht binärkompatibel konfiguriert sind oder eine Erkennungslogik dies ausschließt (ARAComAPI §6 „Event Allocate/Send sample Binding implementer hint“).

Im Zusammenspiel mit dem Senden von Events wird der über Allocate erhaltene Speicherzeiger an Send(ara::com::SampleAllocateePtr<SampleType> data) übergeben ([SWS_CM_90437]). Nach dem Aufruf von Send darf die Dienstanwendung nicht mehr auf die Daten zugreifen, sobald das Communication Management die Daten an alle abonnierenden Anwendungen versendet ([SWS_CM_90437]).

Die Funktion [SWS_CM_00162] dient auf Service-Provider-Seite innerhalb von <SI-Namespace>::skeleton::events::<Event> dem Versenden von Event-Daten an alle abonnierenden Applikationen. Bei dieser Variante verbleibt die Verantwortung für die Datenallokation vollständig bei der anwendenden Applikation. Über den Parameter data wird das Datenobjekt übergeben, woraufhin die Binding-Implementierung während des Aufrufs eine interne Kopie anfertigt (ARAComAPI, Figure 6.17 „BrakeEvent Class“). Nach Rückkehr des synchronen Methodenaufrufs kann die Applikation den ursprünglichen Speicherbereich unmittelbar modifizieren oder freigeben.

Die Methode ist mit noexcept deklariert und als ausnahmesicher spezifiziert. Sie liefert ein ara::core::Result<void> zurück, welches im Erfolgsfall void enthält und im Fehlerfall Fehlercodes aus [SWS_CM_10432] meldet ([SWS_CM_00162]):

• ComErrc::kServiceNotOffered: Tritt auf, wenn die Service-Instanz noch nicht über OfferService() bereitgestellt wurde.
• ComErrc::kMinimumSendIntervalViolationError: Tritt auf, wenn die Sendeanforderung schneller als das konfigurierte Mindestsendeintervall (ServiceInterfaceDeploymentElement.minimumSendInterval) abgesetzt wurde.

Im Gegensatz zur Zero-Copy-Alternative [SWS_CM_90437], welche über Allocate() bezogene Zeiger vom Typ ara::com::SampleAllocateePtr voraussetzt, erfordert dieser Aufruf keine Speicherbindung an das Framework. Dasselbe Übertragungsverhalten und dieselben Fehlerbedingungen gelten gemäß [SWS_CM_00119] auch für die Aktualisierungsmethode Update von Feldern.

Verwendung und Aufrufkontext

Die Methode Send wird auf einer Event-Instanz im Service-Skelett (<SI-Namespace>::skeleton::events::<Event>) aufgerufen ([SWS_CM_90437]). Sie überträgt Event-Daten, für deren Speicherverwaltung das Communication Management zuständig ist. Der Parameter data vom Typ ara::com::SampleAllocateePtr<SampleType> muss zuvor über Allocate() bezogen worden sein ([SWS_CM_90437]). Dieser Zeigertyp verhält sich semantisch wie ein std::unique_ptr, wodurch das Eigentum an den Daten beim Aufruf an die Kommunikationsschicht übergeht (ARAComAPI §6.17 „BrakeEvent Class“). Nach der Übergabe ist der sendenden Anwendung jeder weitere Zugriff auf die Daten untersagt ([SWS_CM_90437]).

Fehlerbehandlung und Randbedingungen

Die Funktion ist als noexcept deklariert und gibt ein ara::core::Result<void> zurück ([SWS_CM_90437]). Schlägt das Senden fehl, enthält das Resultat einen Fehlercode aus ara::com::ComErrc ([SWS_CM_10432]):

• ComErrc::kServiceNotOffered: Der zugehörige Service wurde vorab noch nicht mit OfferService() bereitgestellt ([SWS_CM_90437]).
• ComErrc::kMinimumSendIntervalViolationError: Das für das Service-Element konfigurierte Mindestsendeintervall (minimumSendInterval) ist seit der letzten Übertragung noch nicht abgelaufen ([SWS_CM_90437]).

Beide Fehlerfälle besitzen Rollback-Semantik ([SWS_CM_90437]). Vor dem Aufruf muss der Service daher zwingend angeboten worden sein, und aufeinanderfolgende Sendeaufrufe müssen den konfigurierten Mindestabstand einhalten.

Zusammenspiel und Optimierung

Im Vergleich zur Signatur [SWS_CM_00162], bei der anwendungsverwaltete Daten übergeben und vom Communication Management kopiert werden, zielt diese Variante auf Zero-Copy-Kommunikation über Shared Memory ab (ARAComAPI §6.18 „Event Allocate/Send sample“). Dabei wird eine strikte Synchronisation zwischen Schreibern und Lesern vorausgesetzt, wobei mögliche Serialisierungsanforderungen zwischen den Kommunikationspartnern zu beachten sind (ARAComAPI §6.18 „Event Allocate/Send sample“).

Verwendung

Die Funktion SetSubscriptionStateChangeHandler registriert im Skeleton-Scope (skeleton::events) einen Callback-Handler zur Überwachung des Subskriptionsstatus eines Events [SWS_CM_12008]. Der Parameter handler muss ein aufrufbares Objekt nach Typ SubscriptionStateChangeHandler gemäß [SWS_CM_00311] sein. Die Methode liefert keinen Rückgabewert und ist als noexcept spezifiziert [SWS_CM_12008].

Das Communication Management ruft den registrierten Handler auf, sobald sich der Subskriptionsstatus des Events ändert [SWS_CM_12012]. Auf der Skeleton-Seite geschieht dies mit dem Zustand kSubscribed, sobald die Anzahl aktiver Abonnements größer als null wird [SWS_CM_12013], bzw. mit kNotSubscribed, wenn keine aktiven Subskriptionen mehr vorhanden sind [SWS_CM_12014] SWS CommunicationManagement §7.5.4 „Query Service Event Subscription State on Skeleton side“.

Fehlerbehandlung und Nebenläufigkeit

Die Operation ist als exception safe klassifiziert [SWS_CM_12008]. Ist das übergebene Callable ungültig oder null, liegt eine InvalidHandlerViolation vor [SWS_CM_12008]. Interpretation: Da die Funktion weder Exceptions wirft noch einen Fehlercode zurückgibt, dürfte diese Spezifikationsverletzung über plattformspezifische Laufzeitmechanismen abgefangen werden. Frage Q-a7b7b54f0d538b40 (offen)

Der Handler darf zur Laufzeit überschrieben werden [SWS_CM_12012]. Für die Ausführung in einem dedizierten Thread- bzw. Aufgabenkontext existiert die Überladung mit dem Template-Parameter executor [SWS_CM_12009]. Eine analoge Registrierung für Trigger-Elemente des Skeletons definiert [SWS_CM_01110].

Die Template-Funktion SetSubscriptionStateChangeHandler dient auf Skeleton-Ebene ([SWS_CM_12009]) im Namensraum eines Events der Registrierung eines Callbacks für Zustandsänderungen eingehender Abonnements. Gegenüber der Basisfunktion ohne Executor ([SWS_CM_12008]) nimmt sie zusätzlich einen Ausführungskontext (executor) entgegen, in dem der registrierte Handler ausgeführt wird ([SWS_CM_12009]). Die Funktion besitzt keinen Rückgabewert, ist als noexcept deklariert und gilt als ausnahmesicher ([SWS_CM_12009]).

Hinsichtlich des Fehlerverhaltens führt die Übergabe eines ungültigen oder nullwertigen Callables zu einer InvalidHandlerViolation ([SWS_CM_12009]). Der registrierte Handler kann zur Laufzeit der Anwendung jederzeit durch einen erneuten Aufruf überschrieben werden ([SWS_CM_12012]).

Das Communication Management ruft den Handler auf, sobald sich der Zustand der Abonnements für das jeweilige Event ändert (SWS CommunicationManagement §7.5.4 „Query Service Event Subscription State on Skeleton side“, [SWS_CM_12012]):

• Der Aufruf erfolgt mit dem Status kSubscribed, wenn die Anzahl aktiver Abonnements von null auf mehr als null ansteigt ([SWS_CM_12013]).
• Sinkt die Zahl aktiver Abonnenten wieder auf null, wird der Handler mit kNotSubscribed benachrichtigt ([SWS_CM_12014]).

Interpretation: Durch die Übergabe von executor dürfte die Ausführung des Handlers gezielt an anwendungseigene Thread- oder Dispatching-Kontexte gebunden werden ([SWS_CM_12009]), um die nebenläufige Benachrichtigung des Skeleton-Codes sauber von internen Kommunikations-Threads zu trennen. Frage Q-b11f3bc97069f2ec (offen)

Die Funktion UnsetSubscriptionStateChangeHandler dient auf Skeleton-Ebene im Namensraum ::skeleton::events::{<event-name>} dazu, einen zuvor registrierten Zustandsänderungs-Handler für den ara::com::SubscriptionState eines Events zu deregistrieren [SWS_CM_12010]. Die Funktion nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert (void) [SWS_CM_12010]. Die Einbindung erfolgt über den Header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010].

Hinsichtlich des Ausnahmeverhaltens ist die Methode mit noexcept deklariert und als ausnahmesicher (exception safe) spezifiziert [SWS_CM_12010]. Es werden keine spezifischen Fehlercodes zurückgegeben oder C++-Exceptions geworfen [SWS_CM_12010]. Interpretation: Etwaige interne Fehlerzustände bei der Deregistrierung dürften von der Kommunikationsverwaltung intern abgefangen werden, da die Signatur keine Fehlerrückmeldung vorsieht. Frage Q-7e986a15e552ca19 (offen)

Im Zusammenspiel mit verwandten Schnittstellen existieren analoge Funktionen zur Handler-Deregistrierung:

• Auf Skeleton-Ebene stellt ::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler die entsprechende Deregistrierung für Trigger bereit [SWS_CM_01112].
• Auf Proxy-Ebene existieren äquivalente Methoden zur Deregistrierung von Zustandsänderungs-Handlern für Events [SWS_CM_00334], Fields [SWS_CM_11609] sowie Trigger [SWS_CM_01108] innerhalb des Namensraums proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 „Proxy Class API’s“.