klasse <SI-Namespace>::skeleton::<SI>Skeleton

De methode OfferService() wordt aangeroepen op een instantie van de skeleton-klasse om een geleverde dienst in het systeem aan te bieden en voor consumenten via de Service Discovery vindbaar te maken [SWS_CM_00101], ARAComAPI §6.5 “Service Discovery”. De aanroep geschiedt parameterloos en synchroon, zodra de service-implementatie volledig is geïnstantieerd en in een operationele toestand is gebracht AUTOSAR_AP_EXP_ARAComAPI §5.4.4 “Offering Service instance”. De functie is gedeclareerd als noexcept en retourneert een ara::core::Result<void> [SWS_CM_00101].

Het aanbieden is een dwingende vereiste voor de functionele communicatie via methoden, events, velden of triggers AUTOSAR_AP_EXP_ARAComAPI §4.2 “Means of Communication”. Wordt bijvoorbeeld geprobeerd een trigger te verzenden zonder voorafgaand aanbieden, dan mislukt dit met ComErrc::kServiceNotOffered [SWS_CM_00721]. Wat betreft concurrency geldt: zodra OfferService() wordt aangeroepen, kunnen inkomende methode-aanroepen al worden afgeleverd aan de service-instantie – zelfs wanneer de aanroep van OfferService() nog niet is teruggekeerd AUTOSAR_AP_EXP_ARAComAPI §5.4.4 “Offering Service instance”.

Mislukt het aanbieden, dan bevat de geretourneerde ara::core::Result een overeenkomstige foutcode uit ComErrc [SWS_CM_00101], [SWS_CM_10432]:

• ComErrc::kFieldValueNotInitialized: Ten minste één geconfigureerde veldwaarde was voorafgaand aan het aanbieden nog niet geïnitialiseerd [SWS_CM_00101].
• ComErrc::kFieldSetHandlerNotSet: Voor een veld met setter-ondersteuning is nog geen handler geregistreerd via RegisterSetHandler() [SWS_CM_00101].
• ComErrc::kCommunicationFailure: De netwerkkoppeling meldt een herstelbare communicatiefout of het mislukken van veilige communicatie [SWS_CM_00101].

Moet de levering van de dienst worden beëindigd, dan moet StopOfferService() worden aangeroepen AUTOSAR_AP_EXP_ARAComAPI §5.4.4 “Offering Service instance”.

De methode ProcessNextMethodCall() dient er voor serviceproviders in de skeleton toe om inkomende methode-aanroepen in pollingmodus deterministisch af te handelen [SWS_CM_00199]. Zij mag uitsluitend worden gebruikt wanneer de skeleton-instantie is geconfigureerd met de modus ara::com::MethodCallProcessingMode::kPoll EXP ARAComAPI §2 “Polling”.

Gebruik en semantiek

De functie accepteert geen parameters en voert een openstaand verzoek voor een methode-aanroep synchroon uit in de threadcontext van de aanroeper [SWS_CM_00199], [SWS_CM_00191]. Dit stelt met name realtime-applicaties in staat om serviceverzoeken zonder ongecontroleerde threadcontextwisselingen binnen hun toegewezen tijdbudget te verwerken EXP ARAComAPI §5.4 “ProcessNextMethodCall”. De retourwaarde signaleert het resultaat van het ophalen:

• true: Ten minste één openstaand verzoek bevond zich in de wachtrij en is afgehandeld [SWS_CM_00199].
• false: Er was geen openstaand verzoek aanwezig; de wachtrij was leeg [SWS_CM_00199]. Een directe vervolgaanroep na een false blijft doorgaans zonder effect EXP ARAComAPI §5.4 “ProcessNextMethodCall”.

Foutafhandeling en randvoorwaarden

De functie is gespecificeerd als noexcept en exception safe [SWS_CM_00199]. Een aanroep op een skeleton die is geïnstantieerd met kEvent of kEventSingleThread vormt een schending (WrongMethodCallProcessingModeViolation) [SWS_CM_00199]. Interpretatie: aangezien reguliere C++-exceptions door noexcept zijn uitgesloten, wordt een dergelijke schending aan platformzijde vermoedelijk behandeld als een ernstige runtimefout. Vraag Q-61661dbd6cc37bc7 (open)

Gebruik

De functie SetTransportFaultConditionHandler dient voor de registratie van een callback van het type ara::com::e2e::TransportFaultConditionHandler in de namespace van de skeleton-klasse (<SI-Namespace>::skeleton::<SI>) [SWS_CM_00093]. Via deze handler worden transportfouten voor alle methoden van de desbetreffende service-instantie gemeld AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 “End-to-end communication protection for SOMEIP”. De functie neemt het aanroepbare object handler over en heeft geen retourwaarde (void) [SWS_CM_00093].

Foutafhandeling

De bewerking is gedeclareerd met noexcept en exceptieveilig (exception safe) [SWS_CM_00093]. Indien de overgedragen aanroepbare eenheid niet bestaat of null is, wordt een InvalidHandlerViolation gegenereerd [SWS_CM_00093]. In geval van een fout meldt de geconfigureerde handler opgetreden transportstoringen zoals TransportFaultCondition::kSampleRejected, wanneer verzoeken door gebrek aan resources of corruptie in de transportlaag worden verworpen AUTOSAR_AP_SWS_CommunicationManagement §7.4.2.3 “Methods”.

Gelijktijdigheid en beperkingen

Interpretatie: Aangezien deze basisinterface geen uitvoeringscontext accepteert, wordt de callback vermoedelijk synchroon aangeroepen vanuit de interne thread van Communication Management. Vraag Q-e4007fa72de6aa12 (open) Indien de uitvoering van de handler in een gedefinieerde threadpool of worker moet plaatsvinden, dient de overbelasting met ExecutorT&& executor te worden gebruikt [SWS_CM_00094].

Samenspel

De registratie koppelt de foutafhandeling centraal aan alle methoden van een skeleton-instantie [SWS_CM_00093]. Ze past binnen de overkoepelende foutafhandeling van ara::com:

• Terwijl skeleton-methoden transportfouten via deze handler melden, signaleren client-methoden transportuitvallen asynchroon via hun resulterende ara::core::Future met ComErrc::kCommunicationFailure [SWS_CM_00090].
• Voor veldbewerkingen (Get/Set) op skeleton-niveau bestaan afzonderlijke interfaces [SWS_CM_00096].
• Op proxy-niveau staan analoge registratiefuncties voor events [SWS_CM_00099], triggers [SWS_CM_00106] en notifiers [SWS_CM_00109] gereed.

De template-functie SetTransportFaultConditionHandler in de namespace van de skeleton-klasse dient voor de registratie van een fout-handler voor transportfouten van alle methoden van een service-instantie [SWS_CM_00094]. Zij breidt de parameterloze basisfunctie [SWS_CM_00093] uit met een uitvoeringscontext:

• Aanroep en parameters: meegegeven worden een callable handler van het type ara::com::e2e::TransportFaultConditionHandler en een universele referentie executor [SWS_CM_00094]. In dit executor-object moeten alle asynchrone berekeningen en callback-uitvoeringen worden gestart. De functie heeft geen retourwaarde.
• Foutafhandeling: de interface is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig [SWS_CM_00094]. Als het meegegeven callable niet bestaat of null is, is er sprake van een InvalidHandlerViolation [SWS_CM_00094].
• Interactie: het geldigheidsbereik omvat alle methoden van het skeleton [SWS_CM_00094], terwijl voor field-get- en set-operaties afzonderlijke registratiefuncties beschikbaar zijn ([SWS_CM_00096], [SWS_CM_00097]). In de DDS-netwerkbinding meldt de geconfigureerde handler transportfouten zoals TransportFaultCondition::kSampleRejected [SWS_CM_00216]; aan clientzijde worden dergelijke fouten daarentegen gesignaleerd via ComErrc::kCommunicationFailure in de resultaats-futures [SWS_CM_00090].
• Concurrency: interpretatie: het doorgeven van de executor ontkoppelt de foutafhandeling van de interne context van de communicatielaag; vermoedelijk moet de registratie vroegtijdig plaatsvinden bij de initialisatie van het skeleton voordat de eerste methode-aanroepen binnenkomen. Vraag Q-e56b2a1928cf32ad (open)

De constructor [SWS_CM_00130] instantieert een service-skeleton aan de hand van een concrete ara::com::InstanceIdentifier. Het skeleton koppelt de service-implementatie aan applicatiezijde aan de transportlaag van het Communication Management, zodat gedistribueerde service-consumers hier toegang toe hebben (ARAComAPI §5.1 “Proxy Skeleton Pattern”).

Via de parameter mode wordt vastgelegd hoe inkomende methode-aanroepen worden verwerkt. Als standaardwaarde is de gebeurtenisgestuurde modus ara::com::MethodCallProcessingMode::kEvent voorgeschreven [SWS_CM_00130]. Wordt in plaats daarvan een polling-gebaseerde modus gekozen, dan vindt de uitvoering van openstaande methode-aanroepen synchroon plaats in de aanroepcontext van ProcessNextMethodCall() [SWS_CM_00199].

Foutafhandeling en randvoorwaarden

De constructorfunctie is gedeclareerd met noexcept en werpt geen C++-exceptions op [SWS_CM_00130]. Mogelijke schendingen worden gesignaleerd via het runtimesysteem: als het aanmaken door grant enforcement wordt geweigerd, is er sprake van een InsufficientPermissionsViolation; bij doorgifte van een ongeldige verwerkingsmodus resulteert dit in een WrongMethodCallProcessingModeViolation [SWS_CM_00130]. Interpretatie: De validatie van de verwerkingsmodus vindt vermoedelijk direct tijdens de uitvoering van de constructor plaats. Vraag Q-80e02c0079757082 (open)

Kopieerbewerkingen zijn voor het skeleton expliciet verwijderd [SWS_CM_00134], terwijl move-constructie wordt ondersteund [SWS_CM_00135]. Om de service vindbaar te maken op het netwerk, moet na de instantiëring OfferService() worden aangeroepen [SWS_CM_00101] (ARAComAPI §6.5 “Service Discovery”). Vóór het vernietigen van de instantie [SWS_CM_11370] kan de beschikbaarstelling met behulp van StopOfferService() [SWS_CM_00111] weer worden beëindigd.

De constructor instantieert een service-skeleton aan de hand van een instantie-identifier [SWS_CM_00152]. Deze dient ertoe een concrete service-implementatie te koppelen aan de transportlaag van Communication Management. Als parameters worden een ara::core::InstanceSpecifier en optioneel de verwerkingsmodus ara::com::MethodCallProcessingMode overgedragen, die standaard is ingesteld op kEvent [SWS_CM_00152].

Wat betreft foutafhandeling en exceptiegedrag is de constructor gedeclareerd als noexcept en exception safe [SWS_CM_00152]. Bij foutieve configuraties of modelleringsafwijkingen zijn de volgende violations gespecificeerd:

• InstanceSpecifierMappingIntegrityViolation, indien de identifier in de uitvoeringscontext niet kan worden herleid of niet verwijst naar een PortPrototype [SWS_CM_00152].
• PortInterfaceMappingViolation en ProcessMappingViolation, wanneer mappingtype en interfacetype niet overeenkomen [SWS_CM_00152].
• InstanceSpecifierAlreadyInUseViolation, wanneer de InstanceSpecifier reeds wordt gebruikt [SWS_CM_00152].
• WrongMethodCallProcessingModeViolation evenals InsufficientPermissionsViolation bij ontoereikende rechten [SWS_CM_00152].

Interpretatie: Aangezien de constructor is gedeclareerd als noexcept, zullen de gespecificeerde violations vermoedelijk niet als geworpen C++-excepties tijdens runtime worden gepropageerd, maar door controles aan platformzijde of Grant Enforcement worden opgevangen. Vraag Q-f1a1a0baeb56e482 (open)

Voor levenscyclus en gelijktijdigheid geldt dat de copy constructor is verwijderd [SWS_CM_00134], terwijl er een move constructor beschikbaar is [SWS_CM_00135]. De vrijgave vindt plaats via de virtuele destructor [SWS_CM_11370]. Na succesvolle constructie wordt de service doorgaans via [SWS_CM_00101] (OfferService) op het netwerk aangeboden. Werd als verwerkingsmodus kPoll gekozen, dan moet de applicatie binnenkomende aanroepen van de servicemethoden [SWS_CM_00191] expliciet via [SWS_CM_00199] (ProcessNextMethodCall) verwerken.

Gebruik

De constructor instantieert een service-skeleton aan de hand van een container van instantie-identifiers (instanceIDs) en verbindt de service-implementatie aan serverzijde met de transportlaag van Communication Management [SWS_CM_00153], ARAComAPI §5.1 “Proxy Skeleton Pattern”. Via de parameter mode wordt vastgelegd hoe inkomende methodeaanroepen worden verwerkt; standaard verloopt de afhandeling gebeurtenisgestuurd via kEvent [SWS_CM_00153]. Als alternatief zijn er constructoren beschikbaar voor afzonderlijke instantie-identifiers [SWS_CM_00130] of instantiespecificaties [SWS_CM_00152].

Foutafhandeling en gelijktijdigheid

De functie is gedeclareerd als noexcept en gespecificeerd als exceptieveilig (exception safe) [SWS_CM_00153]. Mogelijke schendingen bij de creatie zijn WrongMethodCallProcessingModeViolation bij overdracht van een ontoelaatbare verwerkingsmodus en InsufficientPermissionsViolation indien de autorisatiecontrole (Grant Enforcement) mislukt [SWS_CM_00153].

Indien voor mode het polling-model (kPoll) wordt geconfigureerd, moet de serverapplicatie openstaande methodeaanroepen door het aanroepen van ProcessNextMethodCall() synchroon in de eigen threadcontext afhandelen [SWS_CM_00199]. De copy-constructor van de skeleton-klasse is verwijderd (delete) [SWS_CM_00134]; verplaatsingen worden daarentegen ondersteund via de move-constructor [SWS_CM_00135].

Samenspel

Na succesvolle instantiatie wordt de service via OfferService() beschikbaar gesteld voor remote of lokale consumenten [SWS_CM_00101], ARAComAPI §6.5 “Service Discovery”. Voorafgaand aan het vernietigen van de skeleton met behulp van de destructor [SWS_CM_11370] moet de beschikbaarstelling via StopOfferService() worden beëindigd [SWS_CM_00111]. Inkomende methodeaanroepen retourneren aan serverzijde telkens een ara::core::Future [SWS_CM_00191].

De virtuele destructor ~<SI>Skeleton() [SWS_CM_11370] beëindigt de levenscyclus van een service-skeleton-instantie. Het service-skeleton verbindt als gegenereerd artefact de concrete service-implementatie met de transportlaag van Communication Management, zodat service-consumenten de aangeboden methoden en functionaliteiten kunnen bereiken (ARAComAPI §5.1 “Proxy Skeleton Pattern”).

De vernietiging vindt synchroon plaats bij het afbreken van de afgeleide implementatieklasse. De methode accepteert geen parameters en declareert geen retourwaarde. In tegenstelling tot de constructors van het skeleton zoals [SWS_CM_00130] of [SWS_CM_00152] is de destructor in de specificatie expliciet geclassificeerd als not exception safe [SWS_CM_11370].

Wat betreft foutafhandeling en randvoorwaarden is vastgelegd dat bij een geschonden voorwaarde een DanglingSamplesViolation kan optreden [SWS_CM_11370]. Werd de service voorheen middels OfferService() [SWS_CM_00101] naar buiten toe aangeboden (ARAComAPI §6.5 “Service Discovery”), dan zal vóór de destructor-aanroep vermoedelijk de methode StopOfferService() [SWS_CM_00111] moeten worden aangeroepen om lopende communicatierelaties netjes te beëindigen. Vraag Q-c430a7f0fc838eba (open)

Voor het skeleton is de copy constructor verwijderd [SWS_CM_00134], terwijl move-bewerkingen worden ondersteund [SWS_CM_00135]. Lopende verwerkingsprocessen – zoals de afhandeling van openstaande aanroepen via ProcessNextMethodCall() [SWS_CM_00199] – dienen vóór aanvang van de vernietiging te zijn afgerond.

De methode [SWS_CM_00111] beëindigt het aanbieden van een service-instantie door de service-provider-applicatie in ara::com. De aanroep geschiedt parameterloos op de concrete skeleton-instantie in de namespace <SI-Namespace>::skeleton::<SI> en levert geen retourwaarde op (EXP_ARAComAPI §5.4.1 “Skeleton Class API’s”).

Voor het gebruik en het runtime-gedrag gelden de volgende voorwaarden:

• Aanroepcontext en randvoorwaarde: De methode wordt aangeroepen wanneer een eerder middels OfferService() beschikbaar gestelde instantie – bijvoorbeeld als gevolg van toestandswijzigingen – niet langer beschikbaar moet zijn (EXP_ARAComAPI §5.4.4 “Offering Service instance”).
• Garantie (contract): Zodra StopOfferService() is teruggekeerd, worden contractueel geen verdere methode-aanroepen meer doorgestuurd naar deze service-instantie (EXP_ARAComAPI §5.4.4 “Offering Service instance”).
• Levenscyclus en destructor: Indien een service-instantie bij het aanroepen van de destructor van de skeleton-klasse nog actief wordt aangeboden, voert de destructor StopOfferService() intern verplicht uit (EXP_ARAComAPI §5.4.4 “Offering Service instance”).
• Service Discovery: Door de aanroep wordt de lokale registry respectievelijk het Service Discovery-protocol van de middleware bijgewerkt over het intrekken van de service (EXP_ARAComAPI §7.2.1 “Central vs Distributed approach”).

De functie is gedeclareerd als noexcept en geldt als uitzonderingsveilig ([SWS_CM_00111]). Deze signaleert fouten noch via exceptions, noch via foutmeldingen of retourcodes.