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

Gebruik

De methode RegisterGetHandler wordt aan serverzijde aangeroepen op het field-object van een skeleton ([SWS_CM_00114]). Deze bestaat uitsluitend dan in de gegenereerde code als er in de interfacebeschrijving voor het desbetreffende field een getter is geconfigureerd (Field.hasGetter == TRUE) (EXP ARAComAPI §5.4.8.1 “Registering Getters”). Meegegeven wordt een callback handler van het type std::function<ara::core::Future<FieldType>()>, die bij een inkomende Get()-aanvraag van een proxy door de binding-implementatie wordt aangeroepen.

De registratie van een dergelijke handler is volledig optioneel (EXP ARAComAPI §5.4.8.1 “Registering Getters”). Gewoonlijk heeft de service-implementatie geen getter-handler nodig, aangezien Communication Management de laatst via Update() ingestelde waarde buffert en proxy-aanvragen zelfstandig beantwoordt. Een handler is vooral zinvol wanneer het bepalen van de field-waarde tijdsintensief of rekenkundig zwaar is en daarom pas bij daadwerkelijke behoefte asynchroon via het promise/future-patroon moet plaatsvinden.

Foutafhandeling en randvoorwaarden

De functie heeft geen retourwaarde, is gedeclareerd als noexcept en is uitzonderingsveilig (exception safe) ([SWS_CM_00114]). Indien het meegegeven callable niet bestaat of null is, is er sprake van de fout InvalidHandlerViolation ([SWS_CM_00114]).

Samenspel

In tegenstelling tot RegisterSetHandler, waarvan de aanroep bij een aanwezige setter verplicht is (EXP ARAComAPI §5.4.8.2 “Registering Setters”), blijft RegisterGetHandler puur optioneel. Indien de handler in een specifieke uitvoeringscontext asynchroon moet worden verwerkt, staat aanvullend de overladen templatefunctie met ExecutorT ter beschikking ([SWS_CM_11360]).

Gebruik

De methode RegisterGetHandler in de namespace <SI-Namespace>::skeleton::fields::<Field> registreert een callback aan applicatiezijde (handler), die bij een inkomende Get()-aanroep van een proxy wordt aangeroepen door de communicatiebinding ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 “Registering Getters”). In tegenstelling tot de parameterloze basisoverbelasting [SWS_CM_00114] accepteert de methode een uitvoeringscontext executor van het type ExecutorT, waarin de callback-uitvoering asynchroon plaatsvindt ([SWS_CM_11360]). Als uitvoerder kan de gestandaardiseerde ara::core::Executor of een gebruikersspecifiek type met dezelfde interface worden ingezet ([SWS_CM_11360]).

De geregistreerde handler retourneert een ara::core::Future<FieldType>, waardoor de berekening van de veldwaarde via het promise/future-patroon wordt ontkoppeld ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 “Registering Getters”). De registratie is volledig optioneel: voor zover er geen handler is geregistreerd, beantwoordt Communication Management verzoeken zelfstandig met de waarde die het laatst via Update() is ingesteld (EXP ARAComAPI §5.4.8.1 “Registering Getters”). Een getter-handler is primair geschikt voor het vraaggestuurd bepalen van complexe of tijdrovende veldwaarden (EXP ARAComAPI §5.4.8.1 “Registering Getters”).

Beperkingen en foutafhandeling

De methode bestaat in het skeleton uitsluitend wanneer er in de IDL een getter is geconfigureerd voor het veld (Field.hasGetter == TRUE, [SWS_CM_00114], EXP ARAComAPI §5.4.8.1 “Registering Getters”). RegisterGetHandler is gedeclareerd als noexcept; wordt echter een ongeldige of lege callable doorgegeven, dan is er sprake van een InvalidHandlerViolation ([SWS_CM_11360]). Interpretatie: de doorgegeven executor moet vermoedelijk geldig blijven gedurende de gehele gebruiksduur van de handler, aangezien inkomende verzoeken asynchroon naar de context ervan worden geleid. Vraag Q-c58eb22b06a8c27c (open)

Gebruik

De methode RegisterSetHandler dient aan de serverzijde (skeleton) om een callback-functie te registreren die wordt aangeroepen bij ontvangst van een Set()-verzoek van een client voor een veld [SWS_CM_00116]. De methode bestaat uitsluitend wanneer het aangeboden veld met setter-ondersteuning is geconfigureerd (Field.hasSetter == TRUE) [SWS_CM_00116]. In tegenstelling tot de getter-registratie is de aanroep van RegisterSetHandler verplicht, omdat de serverimplementatie nieuwe of bijgewerkte veldwaarden van anonieme clients vooraf moet valideren EXP ARAComAPI §5.4.8.2 “Registering Setters”.

De geregistreerde handler ontvangt de nieuwe waarde als argument en retourneert een ara::core::Future<FieldType> met de effectieve, eventueel gecorrigeerde waarde [SWS_CM_00116], EXP ARAComAPI §5.4.8.2 “Registering Setters”. Deze effectieve waarde wordt door het communicatiebeheer impliciet overgenomen en naar clients gepubliceerd; een expliciete aanroep van Update() binnen de handler is daarom overbodig EXP ARAComAPI §5.4.8.2 “Registering Setters”.

Foutafhandeling en randvoorwaarden

De functie is gedefinieerd als noexcept en exceptieveilig [SWS_CM_00116]. Wordt een niet-bestaand of ongeldig (null) callable meegegeven, dan is er sprake van een specificatieovertreding in de vorm van een InvalidHandlerViolation [SWS_CM_00116]. Interpretatie: De registratie zal moeten plaatsvinden vóór de beschikbaarstelling van de dienst via OfferService(), om binnenkomende client-verzoeken vanaf het begin te kunnen ontvangen. Vraag Q-d45be0a899ddb6dd (open)

Samenspel

Naast de basismethode bestaat een template-overload [SWS_CM_11362], waarmee de uitvoering van de handler aan een specifieke uitvoeringscontext (ExecutorT conform [SWS_CM_11360]) kan worden gebonden EXP ARAComAPI.

De templatefunctie RegisterSetHandler registreert op het server- resp. skeletonniveau van een veld een callbackfunctie die wordt aangeroepen zodra een client een Set()-verzoek verzendt ([SWS_CM_11362], [SWS_CM_00116]). De interface bestaat alleen als het geconfigureerde serviceveld ondersteuning voor setters (Field.hasSetter == TRUE) voorziet ([SWS_CM_00116]). In tegenstelling tot de get-registratie is het registreren van een set-handler verplicht, omdat de serverimplementatie nieuwe veldwaarden van anonieme clients altijd moet valideren (EXP ARAComAPI §5.4.8.2 “Registering Setters”).

Ten opzichte van de standaardregistratie conform [SWS_CM_00116] accepteert deze overload aanvullend een uitvoeringscontext executor van het type ExecutorT&& ([SWS_CM_11362], [SWS_CM_11360]). Interpretatie: De executor regelt vermoedelijk in welke thread- of task-schedulercontext de callback wordt uitgevoerd. Vraag Q-6dec4c0005c388dd (open) De meegegeven handler heeft de signatuur std::function<ara::core::Future<FieldType>(<SFieldDerivedType> value)>; deze ontvangt de door de client ingestelde waarde en retourneert asynchroon via ara::core::Future de effectieve – eventueel gevalideerde of gecorrigeerde – waarde ([SWS_CM_11362], EXP ARAComAPI §5.4.8.2 “Registering Setters”).

Het Communication Management neemt de door de handler geretourneerde effectieve waarde impliciet over alsof de serverapplicatie zelf Update() had aangeroepen; een handmatige aanroep van Update() binnen de handler is daarom overbodig (EXP ARAComAPI §5.4.8.2 “Registering Setters”, EXP ARAComAPI §4.6 “Data Type Abstractions”).

Foutafhandeling en gelijktijdigheid:

• Exception-veiligheid: De functie is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig (exception safe) ([SWS_CM_11362]).
• Overtredingen: Indien het meegegeven callable setHandler niet bestaat of nullptr is, is er sprake van de overtreding InvalidHandlerViolation ([SWS_CM_11362]).
• Context: De methode waarborgt dat de uitvoering van de handler in de beschikbaar gestelde context van de executor plaatsvindt ([SWS_CM_11362]).

De functie SetTransportFaultConditionHandler dient voor het registreren van een foutafhandelaar van het type ara::com::e2e::TransportFaultConditionHandler voor get- en set-aanvragen van een field op skeleton-niveau in de namespace <SI-Namespace>::skeleton::fields::<Field> [SWS_CM_00096]. De aanroep wordt synchroon uitgevoerd, heeft geen retourwaarde (void) en garandeert exception-safety door de specificatie als noexcept [SWS_CM_00096]. Voor scenario's waarin de handler-uitvoering moet worden gedelegeerd naar een expliciete uitvoeringscontext, staat de template-overload met een executor-object ExecutorT&& executor ter beschikking [SWS_CM_00097].

Als foutvoorwaarde is de schending InvalidHandlerViolation gedefinieerd; deze treedt op wanneer het meegegeven callable handler niet bestaat of null is [SWS_CM_00096]. Terwijl aan clientzijde fouten bij methode- en field-aanvragen via ComErrc::kCommunicationFailure in de desbetreffende ara::core::Future-instanties worden gemeld [SWS_CM_00090], stelt deze functie de serverinstantie in staat transportfouten bij inkomende get- en set-aanroepen te ontvangen [SWS_CM_00096].

Het concept correspondeert met overeenkomstige registratiemechanismen voor alle methoden van een skeleton-service-instantie [SWS_CM_00093] en met handlers aan proxyzijde voor events [SWS_CM_00099], triggers [SWS_CM_00106] en field-notifiers [SWS_CM_00109]. Interpretatie: De registratie van de handler vindt redelijkerwijs plaats tijdens de initialisatiefase vóór het aanbieden van het skeleton, om fouten bij initiële field-toegangen naadloos te kunnen registreren. Vraag Q-627229896b666532 (open)

De functie SetTransportFaultConditionHandler in de namespace <SI-Namespace>::skeleton::fields::<Field> registreert een foutafhandelingsfunctie voor transportstoringen bij Get- en Set-verzoeken van een veld op skeleton-niveau [SWS_CM_00097]. Deze wordt via de header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h opgenomen [SWS_CM_00097].

Gebruik en parameters

De aanroep vindt synchroon plaats en heeft geen retourwaarde (void) [SWS_CM_00097]. Als parameters worden de aanroepbare foutcallback handler van het type ara::com::e2e::TransportFaultConditionHandler en een doorstuurreferentie (forwarding reference) executor van het generieke type ExecutorT&& meegegeven [SWS_CM_00097]. De parameter executor duidt het uitvoeringsobject aan in de context waarvan eventuele asynchrone berekeningen worden uitgevoerd [SWS_CM_00097].

Foutafhandeling en gelijktijdigheid

De methode is gedeclareerd als noexcept en garandeert volledige uitzonderingsveiligheid (exception safe) [SWS_CM_00097]. Indien het doorgegeven handler-callable niet bestaat of null is, wordt een InvalidHandlerViolation geactiveerd [SWS_CM_00097]. Interpretatie: Via het meegegeven executor-object wordt vermoedelijk bepaald in welke thread- of taakcontext de asynchrone melding bij transportfouten wordt verwerkt. Vraag Q-4101faaa8d6a3130 (open)

Samenspel

De methode breidt de standaardregistratie [SWS_CM_00096] uit met een dedicated uitvoeringscontext voor skeleton-velden [SWS_CM_00097]. Overeenkomstige overbelastingen met executor bestaan ook voor skeleton-methoden ([SWS_CM_00094]) en aan client- respectievelijk proxy-zijde voor events ([SWS_CM_00100]) en field-notifiers ([SWS_CM_00110]).

De functie UnsetTransportFaultConditionHandler dient aan de skeleton-zijde van een service-interface om een eerder geregistreerde ara::com::e2e::TransportFaultConditionHandler voor Get- en Set-verzoeken van een veld op te heffen ([SWS_CM_00098]). Deze is gedefinieerd in de namespace <SI-Namespace>::skeleton::fields::<Field> en opgenomen via de header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h (AUTOSAR_AP_SWS_CommunicationManagement §8.4.3.2.1.3 “UnsetTransportFaultConditionHandler”). De aanroep verloopt synchroon, accepteert geen overdrachtsparameters en levert geen retourwaarde op (void).

Door het opheffen wordt de applicatiespecifieke callback voor transportfouttoestanden bij veldverzoeken gedeactiveerd (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 “End-to-end communication protection for SOMEIP”). De interface is gedeclareerd als noexcept en garandeert exceptieveiligheid (exception safe) ([SWS_CM_00098]). Foutcodes of specifieke foutmeldingen via DET of DEM zijn niet gespecificeerd; de bewerking is zo ontworpen dat deze foutloos wordt voltooid.

Wat betreft gelijktijdigheid en re-entrantie bevat de specificatie geen afzonderlijke voorschriften. Bijgevolg zal de deregistratie bij voorkeur plaatsvinden tijdens de-initialisatiefasen of buiten gelijktijdige Get-/Set-verwerkingen, om inconsistenties bij lopende communicatieprocessen te voorkomen. Vraag Q-06bc8d90f1891904 (open)

De bewerking maakt deel uit van de end-to-end-communicatiebeveiliging voor service-instanties (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 “End-to-end communication protection for SOMEIP”). Deze vormt de veldgerelateerde tegenhanger van [SWS_CM_00095], die de handler voor alle methoden van een skeleton de-registreert. Aan de proxy-zijde correspondeert deze met overeenkomstige deregistraties voor events ([SWS_CM_00105]), triggers ([SWS_CM_00108]) en field notifiers ([SWS_CM_00126]).

De methode Update() wordt aan serverzijde aangeroepen in scope <SI-Namespace>::skeleton::fields::<Field> om de interne waarde van een field bij te werken en de overdracht van de nieuwe gegevens naar geabonneerde clients te initiëren ([SWS_CM_00119], AUTOSAR_AP_EXP_ARAComAPI §4.6 “Data Type Abstractions”). Een notificatie wordt naar abonnees verzonden als voor het field hasNotifier == TRUE is geconfigureerd ([SWS_CM_00119], [SWS_CM_00120], [SWS_CM_00162]). De parameter value wordt via referentie doorgegeven; de binding-implementatie maakt tijdens de aanroep een doorgaans geserialiseerde kopie, zodat de applicatiegegevens na terugkeer aan aanroeperszijde kunnen worden gewijzigd of vrijgegeven (AUTOSAR_EXP_ARAComAPI “UpdateRate Class”).

De functie is gedefinieerd als noexcept en exception safe en levert synchroon een ara::core::Result<void> op ([SWS_CM_00119]). Treedt er een fout op, dan bevat het resultaat een foutcode uit ara::com::ComErrc ([SWS_CM_00119], [SWS_CM_10432]). Concreet wordt ComErrc::kMinimumSendIntervalViolationError met rollback-semantiek teruggegeven indien verzendverzoeken sneller plaatsvinden dan voorgeschreven door het geconfigureerde minimale verzendinterval ServiceInterfaceDeploymentElement.minimumSendInterval ([SWS_CM_00119]).

In de service-levenscyclus is een initiële aanroep van Update() vóór het aanbieden van de dienst vereist: als OfferService() wordt aangeroepen voordat de field-waarde is geïnitialiseerd, mislukt de beschikbaarstelling met ComErrc::kFieldValueNotInitialized ([SWS_CM_00101], [SWS_CM_00128]). Wegens het ontbreken van een expliciete re-entrancy-garantie in de standaard moeten gelijktijdige aanroepen op dezelfde field-instantie vermoedelijk applicatiezijdig worden gesynchroniseerd. Vraag Q-67b174ef05867989 (open)