class <SI-Namespace>::skeleton::fields::<Field>

Verwendung

Die Methode RegisterGetHandler wird serverseitig am Feldobjekt eines Skeletons aufgerufen ([SWS_CM_00114]). Sie existiert ausschließlich dann im generierten Code, wenn in der Schnittstellenbeschreibung für das betreffende Feld ein Getter konfiguriert wurde (Field.hasGetter == TRUE) (EXP ARAComAPI §5.4.8.1 „Registering Getters“). Übergeben wird ein Callback handler vom Typ std::function<ara::core::Future<FieldType>()>, welcher bei einer eingehenden Get()-Anfrage eines Proxys von der Binding-Implementierung aufgerufen wird.

Die Registrierung eines solchen Handlers ist vollständig optional (EXP ARAComAPI §5.4.8.1 „Registering Getters“). Üblicherweise benötigt die Service-Implementierung keinen Getter-Handler, da das Communication Management den zuletzt per Update() gesetzten Wert zwischenspeichert und Proxy-Anfragen eigenständig beantwortet. Ein Handler ist vor allem dann sinnvoll, wenn die Ermittlung des Feldwerts zeitintensiv oder rechenaufwendig ist und daher erst bei tatsächlichem Bedarf asynchron über das Promise/Future-Muster erfolgen soll.

Fehlerbehandlung und Randbedingungen

Die Funktion besitzt keinen Rückgabewert, ist als noexcept deklariert und ausnahmesicher (exception safe) ([SWS_CM_00114]). Falls das übergebene Callable nicht existiert oder null ist, liegt der Fehler InvalidHandlerViolation vor ([SWS_CM_00114]).

Zusammenspiel

Im Gegensatz zu RegisterSetHandler, dessen Aufruf bei vorhandenem Setter verpflichtend ist (EXP ARAComAPI §5.4.8.2 „Registering Setters“), bleibt RegisterGetHandler rein optional. Soll der Handler in einem spezifischen Ausführungskontext asynchron verarbeitet werden, steht ergänzend die überladene Template-Funktion mit ExecutorT zur Verfügung ([SWS_CM_11360]).

Verwendung

Die Methode RegisterGetHandler im Namensraum <SI-Namespace>::skeleton::fields::<Field> registriert einen anwendungsseitigen Callback (handler), der bei einem eingehenden Get()-Aufruf eines Proxys von der Kommunikationsbindung aufgerufen wird ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 „Registering Getters“). Im Unterschied zur parameterlosen Basisüberladung [SWS_CM_00114] nimmt die Methode einen Ausführungskontext executor vom Typ ExecutorT entgegen, in dem die Callback-Ausführung asynchron erfolgt ([SWS_CM_11360]). Als Ausführer kann der standardisierte ara::core::Executor oder ein anwenderspezifischer Typ mit gleicher Schnittstelle eingesetzt werden ([SWS_CM_11360]).

Der registrierte Handler gibt ein ara::core::Future<FieldType> zurück, wodurch die Berechnung des Feldwerts über das Promise/Future-Muster entkoppelt wird ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 „Registering Getters“). Die Registrierung ist vollständig optional: Sofern kein Handler registriert ist, beantwortet das Communication Management Anfragen autark mit dem zuletzt über Update() gesetzten Wert (EXP ARAComAPI §5.4.8.1 „Registering Getters“). Ein Getter-Handler eignet sich primär zur bedarfsgesteuerten Ermittlung aufwendiger oder zeitintensiver Feldwerte (EXP ARAComAPI §5.4.8.1 „Registering Getters“).

Einschränkungen und Fehlerbehandlung

Die Methode existiert im Skeleton ausschließlich dann, wenn in der IDL für das Feld ein Getter konfiguriert wurde (Field.hasGetter == TRUE, [SWS_CM_00114], EXP ARAComAPI §5.4.8.1 „Registering Getters“). RegisterGetHandler ist als noexcept deklariert; wird jedoch ein ungültiges oder leeres Callable übergeben, liegt eine InvalidHandlerViolation vor ([SWS_CM_11360]). Interpretation: Der übergebene Executor dürfte während der gesamten Nutzungsdauer des Handlers gültig bleiben müssen, da eingehende Anfragen asynchron in dessen Kontext geleitet werden. Frage Q-c58eb22b06a8c27c (offen)

Verwendung

Die Methode RegisterSetHandler dient auf Serverseite (Skeleton) dazu, eine Callback-Funktion zu registrieren, die beim Eintreffen einer Set()-Anfrage eines Clients für ein Feld aufgerufen wird [SWS_CM_00116]. Die Methode existiert ausschließlich dann, wenn das angebotene Feld mit Setter-Unterstützung konfiguriert ist (Field.hasSetter == TRUE) [SWS_CM_00116]. Im Gegensatz zur Getter-Registrierung ist der Aufruf von RegisterSetHandler verpflichtend, da die Server-Implementierung neue oder aktualisierte Feldwerte anonymer Clients vorab validieren muss EXP ARAComAPI §5.4.8.2 „Registering Setters“.

Der registrierte Handler erhält den neuen Wert als Argument und gibt ein ara::core::Future<FieldType> mit dem effektiven, gegebenenfalls korrigierten Wert zurück [SWS_CM_00116], EXP ARAComAPI §5.4.8.2 „Registering Setters“. Dieser Effektivwert wird von der Kommunikationsverwaltung implizit übernommen und an Clients publiziert; ein expliziter Aufruf von Update() innerhalb des Handlers ist daher überflüssig EXP ARAComAPI §5.4.8.2 „Registering Setters“.

Fehlerbehandlung und Randbedingungen

Die Funktion ist als noexcept definiert und ausnahmesicher [SWS_CM_00116]. Wird ein nicht existentes oder ungültiges (null) Callable übergeben, liegt eine Spezifikationsverletzung in Form einer InvalidHandlerViolation vor [SWS_CM_00116]. Interpretation: Die Registrierung dürfte vor der Bereitstellung des Dienstes über OfferService() erfolgen müssen, um eingehende Client-Anfragen von Beginn an entgegennehmen zu können. Frage Q-d45be0a899ddb6dd (offen)

Zusammenspiel

Neben der Basismethode existiert eine Template-Überladung [SWS_CM_11362], mit der die Ausführung des Handlers an einen spezifischen Ausführungskontext (ExecutorT gemäß [SWS_CM_11360]) gebunden werden kann EXP ARAComAPI.

Die Template-Funktion RegisterSetHandler registriert auf der Server- bzw. Skeleton-Ebene eines Feldes eine Callback-Funktion, die aufgerufen wird, sobald ein Client eine Set()-Anforderung übermittelt ([SWS_CM_11362], [SWS_CM_00116]). Die Schnittstelle existiert nur, wenn das konfigurierte Service-Feld Setter-Unterstützung (Field.hasSetter == TRUE) vorsieht ([SWS_CM_00116]). Im Unterschied zur Get-Registrierung ist das Registrieren eines Set-Handlers verpflichtend, da die Server-Implementierung neue Feldwerte anonymer Clients stets validieren muss (EXP ARAComAPI §5.4.8.2 „Registering Setters“).

Gegenüber der Standardregistrierung nach [SWS_CM_00116] nimmt diese Überladung zusätzlich einen Ausführungskontext executor vom Typ ExecutorT&& entgegen ([SWS_CM_11362], [SWS_CM_11360]). Interpretation: Der executor dürfte steuern, in welchem Thread- oder Task-Scheduler-Kontext der Callback ausgeführt wird. Frage Q-6dec4c0005c388dd (offen) Der übergebene Handler besitzt die Signatur std::function<ara::core::Future<FieldType>(<SFieldDerivedType> value)>; er empfängt den vom Client gesetzten Wert und gibt asynchron über ara::core::Future den effektiven – gegebenenfalls validierten oder korrigierten – Wert zurück ([SWS_CM_11362], EXP ARAComAPI §5.4.8.2 „Registering Setters“).

Das Communication Management übernimmt den vom Handler zurückgelieferten effektiven Wert implizit so, als ob die Server-Applikation selbst Update() aufgerufen hätte; ein manueller Aufruf von Update() innerhalb des Handlers ist daher überflüssig (EXP ARAComAPI §5.4.8.2 „Registering Setters“, EXP ARAComAPI §4.6 „Data Type Abstractions“).

Fehlerbehandlung und Nebenläufigkeit:

• Exception-Sicherheit: Die Funktion ist als noexcept deklariert und ausnahmesicher (exception safe) spezifiziert ([SWS_CM_11362]).
• Verletzungen: Falls das übergebene Callable setHandler nicht existiert oder nullptr ist, liegt die Verletzung InvalidHandlerViolation vor ([SWS_CM_11362]).
• Kontext: Die Methode stellt sicher, dass die Ausführung des Handlers im bereitgestellten Kontext des executor erfolgt ([SWS_CM_11362]).

Die Funktion SetTransportFaultConditionHandler dient der Registrierung eines Fehlerbehandlers vom Typ ara::com::e2e::TransportFaultConditionHandler für Get- und Set-Anfragen eines Felds auf Skeleton-Ebene im Namensraum <SI-Namespace>::skeleton::fields::<Field> [SWS_CM_00096]. Der Aufruf wird synchron ausgeführt, besitzt keinen Rückgabewert (void) und garantiert Exception-Sicherheit durch die Spezifikation als noexcept [SWS_CM_00096]. Für Szenarien, in denen die Handler-Ausführung an einen expliziten Ausführungskontext delegiert werden soll, steht die Template-Überladung mit einem Executor-Objekt ExecutorT&& executor zur Verfügung [SWS_CM_00097].

Als Fehlerbedingung ist die Verletzung InvalidHandlerViolation definiert; sie tritt ein, wenn das übergebene Callable handler nicht existiert oder null ist [SWS_CM_00096]. Während clientseitig Fehler bei Methoden- und Feldanfragen über ComErrc::kCommunicationFailure in den jeweiligen ara::core::Future-Instanzen gemeldet werden [SWS_CM_00090], ermöglicht diese Funktion der Server-Instanz das Entgegennehmen von Transportfehlern bei eingehenden Get- und Set-Aufrufen [SWS_CM_00096].

Das Konzept korrespondiert mit entsprechenden Registrierungsmechanismen für alle Methoden einer Skeleton-Service-Instanz [SWS_CM_00093] sowie proxyseitigen Handlern für Events [SWS_CM_00099], Trigger [SWS_CM_00106] und Feld-Notifier [SWS_CM_00109]. Interpretation: Die Registrierung des Handlers dürfte sinnvollerweise während der Initialisierungsphase vor der Bereitstellung des Skeletons erfolgen, um Fehler bei initialen Feldzugriffen nahtlos erfassen zu können. Frage Q-627229896b666532 (offen)

Die Funktion SetTransportFaultConditionHandler im Namensbereich <SI-Namespace>::skeleton::fields::<Field> registriert einen Fehler-Handler für Transportstörungen bei Get- und Set-Anfragen eines Felds auf Skeleton-Ebene [SWS_CM_00097]. Sie wird über den Header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h eingebunden [SWS_CM_00097].

Verwendung und Parameter

Der Aufruf erfolgt synchron und besitzt keinen Rückgabewert (void) [SWS_CM_00097]. Als Parameter werden das aufrufbare Fehler-Callback handler vom Typ ara::com::e2e::TransportFaultConditionHandler sowie eine Weiterleitungsreferenz executor vom generischen Typ ExecutorT&& übergeben [SWS_CM_00097]. Der Parameter executor bezeichnet das Ausführungsobjekt, in dessen Kontext etwaige asynchrone Berechnungen ausgeführt werden [SWS_CM_00097].

Fehlerbehandlung und Nebenläufigkeit

Die Methode ist als noexcept deklariert und garantiert vollständige Exception-Sicherheit (exception safe) [SWS_CM_00097]. Wenn das übergebene handler-Callable nicht existiert oder null ist, wird eine InvalidHandlerViolation ausgelöst [SWS_CM_00097]. Interpretation: Über das übergebene executor-Objekt wird vermutlich bestimmt, in welchem Thread- oder Task-Kontext die asynchrone Benachrichtigung bei Transportfehlern verarbeitet wird. Frage Q-4101faaa8d6a3130 (offen)

Zusammenspiel

Die Methode erweitert die Standard-Registrierung [SWS_CM_00096] um einen dedizierten Ausführungskontext für Skeleton-Felder [SWS_CM_00097]. Entsprechende Überladungen mit Executor existieren auch für Skeleton-Methoden ([SWS_CM_00094]) sowie auf Client- bzw. Proxy-Seite für Events ([SWS_CM_00100]) und Field-Notifier ([SWS_CM_00110]).

Die Funktion UnsetTransportFaultConditionHandler dient auf der Skeleton-Seite eines Service-Interfaces dazu, einen zuvor registrierten ara::com::e2e::TransportFaultConditionHandler für Get- und Set-Anfragen eines Felds aufzuheben ([SWS_CM_00098]). Sie ist im Namensraum <SI-Namespace>::skeleton::fields::<Field> definiert und über den Header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h eingebunden (AUTOSAR_AP_SWS_CommunicationManagement §8.4.3.2.1.3 „UnsetTransportFaultConditionHandler“). Der Aufruf erfolgt synchron, akzeptiert keine Übergabeparameter und liefert keinen Rückgabewert (void).

Durch das Aufheben wird der anwendungsspezifische Callback für Transportfehlerzustände bei Feld-Anfragen deaktiviert (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 „End-to-end communication protection for SOMEIP“). Die Schnittstelle ist als noexcept deklariert und garantiert Exception-Sicherheit (exception safe) ([SWS_CM_00098]). Fehlercodes oder spezifische Fehlermeldungen über DET oder DEM sind nicht spezifiziert; der Vorgang ist so ausgelegt, dass er fehlerfrei abschließt.

Hinsichtlich Nebenläufigkeit und Reentranz enthält die Spezifikation keine gesonderten Vorgaben. Infolgedessen dürfte die Deregistrierung vorzugsweise während Deinitialisierungsphasen oder außerhalb nebenläufiger Get-/Set-Verarbeitungen erfolgen, um Inkonsistenzen bei laufenden Kommunikationsvorgängen zu vermeiden. Frage Q-06bc8d90f1891904 (offen)

Die Operation ist Teil der End-to-End-Kommunikationsabsicherung für Service-Instanzen (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 „End-to-end communication protection for SOMEIP“). Sie bildet das feldbezogene Gegenstück zu [SWS_CM_00095], welches den Handler für alle Methoden eines Skeletts deregistriert. Auf Proxy-Seite korrespondiert sie mit entsprechenden Deregistrierungen für Events ([SWS_CM_00105]), Trigger ([SWS_CM_00108]) und Field-Notifier ([SWS_CM_00126]).

Die Methode Update() wird serverseitig im Scope <SI-Namespace>::skeleton::fields::<Field> aufgerufen, um den internen Wert eines Feldes zu aktualisieren und die Übertragung der neuen Daten an abonnierte Clients zu initiieren ([SWS_CM_00119], AUTOSAR_AP_EXP_ARAComAPI §4.6 „Data Type Abstractions“). Eine Benachrichtigung wird an Abonnenten gesendet, wenn für das Feld hasNotifier == TRUE konfiguriert ist ([SWS_CM_00119], [SWS_CM_00120], [SWS_CM_00162]). Der Parameter value wird per Referenz übergeben; die Binding-Implementierung erstellt während des Aufrufs eine typischerweise serialisierte Kopie, sodass die Anwendungsdaten nach Rückkehr auf Aufruferseite verändert oder freigegeben werden können (AUTOSAR_EXP_ARAComAPI „UpdateRate Class“).

Die Funktion ist als noexcept sowie exception safe definiert und liefert synchron ein ara::core::Result<void> zurück ([SWS_CM_00119]). Tritt ein Fehler auf, enthält das Ergebnis einen Fehlercode aus ara::com::ComErrc ([SWS_CM_00119], [SWS_CM_10432]). Konkret wird ComErrc::kMinimumSendIntervalViolationError mit Rollback-Semantik zurückgegeben, falls Sendeanforderungen schneller erfolgen als durch das konfigurierte Mindestsendeintervall ServiceInterfaceDeploymentElement.minimumSendInterval vorgegeben ([SWS_CM_00119]).

Im Service-Lebenszyklus ist ein initialer Aufruf von Update() vor dem Anbieten des Dienstes erforderlich: Wird OfferService() aufgerufen, bevor der Feldwert initialisiert wurde, schlägt die Bereitstellung mit ComErrc::kFieldValueNotInitialized fehl ([SWS_CM_00101], [SWS_CM_00128]). Mangels expliziter Reentranz-Garantie im Standard dürften gleichzeitige Aufrufe auf derselben Feldinstanz anwendungsseitig zu synchronisieren sein. Frage Q-67b174ef05867989 (offen)