namespace ara::com

De enumeratie ComErrc definieert volgens [SWS_CM_10432] de gestandaardiseerde foutcodes van ara::com::ComErrorDomain voor herstelbare fouten (Recoverable Errors) conform EXP ARAComAPI §2 “Recoverable Errors”. Deze wordt in retourtypes zoals ara::core::Result of ara::core::Future door synchrone en asynchrone API's van Communication Management getransporteerd om functionele foutoorzaken in de client- of servercontext nauwkeurig te signaleren.

De enumerators dekken specifieke foutgevallen af langs de levenscyclus van diensten en de gegevensoverdracht:

• Levenscyclus van diensten en binding: kServiceNotOffered geeft aan dat een dienst nog niet via OfferService() beschikbaar is gesteld ([SWS_CM_00101]), terwijl kServiceNotAvailable het tussentijdse verlies signaleert. kInstanceIDNotResolvable treedt op wanneer een InstanceSpecifier niet kan worden opgelost ([SWS_CM_00118]).
• Event- en sample-abonnementen: kMaxSamplesExceeded waarschuwt voor het overschrijden van toegezegde SamplePtr-quota, en kMaxSampleCountNotRealizable meldt niet-passende waarden bij het opnieuw aanmelden via [SWS_CM_00141].
• Velden en overdracht: kFieldValueNotInitialized wijst op een ontbrekende initialisatie vóór Update() ([SWS_CM_00119]), kFieldSetHandlerNotSet op een ontbrekende setter-handler. Lokale netwerkproblemen, bijvoorbeeld bij het verzenden van triggers via [SWS_CM_00721], leiden tot kCommunicationFailure ([SWS_CM_10517]). Bovendien bestraffen kMinimumSendIntervalViolationError schendingen van de kloksnelheid en kUnknownApplicationError onverwachte serverfouten ([SWS_CM_10432]).

Als puur opsommingstype heeft ComErrc geen eigen toestand; lees- en vergelijkingsbewerkingen op foutwaarden zijn daarom vermoedelijk thread-safe in de aanroepende thread. Vraag Q-013822ee5711df2b (open) De daadwerkelijke foutcontrole is de verantwoordelijkheid van de applicatie na evaluatie van het desbetreffende resultaatobject.

De enumeratie ara::com::MethodCallProcessingMode definieert de verwerkingsmodi voor inkomende methodeaanroepen op een service-instantie [SWS_CM_00301]. Deze wordt als parameter doorgegeven aan de constructoren van de skeleton-klassen, waarbij de standaardwaarde ara::com::MethodCallProcessingMode::kEvent is voorgeschreven [SWS_CM_00130], [SWS_CM_00152], [SWS_CM_00153].

De enumerators besturen de concurrency en de uitvoeringscontext van de service-methoden [SWS_CM_00301]:

• kPoll: Polling-modus. Inkomende aanroepen van service-consumenten worden niet automatisch uitgevoerd. De service-implementatie bestuurt de uitvoering ervan actief via de aanroep van ProcessNextMethodCall() [SWS_CM_00199]. De openstaande methode wordt synchroon in de context van deze aanroep afgehandeld. Dit waarborgt de volledige controle over thread- en contextwissels aan servicezijde ARAComAPI §6.3.3 “Event Buffering Approaches”.
• kEvent: Gebeurtenisgestuurde en concurrente modus voor de parallelle verwerking van inkomende aanroepen.
• kEventSingleThread: Gebeurtenisgestuurde, sequentiële modus voor de individuele uitvoering van methodeaanroepen.

Foutafhandeling en beperkingen:

• Wordt er een ontoelaatbare modus doorgegeven aan een skeleton-constructor, dan treedt de schending WrongMethodCallProcessingModeViolation op [SWS_CM_00130], [SWS_CM_00153].
• De aanroep van ProcessNextMethodCall() op een skeleton die met kEvent is geconstrueerd, leidt eveneens tot een WrongMethodCallProcessingModeViolation [SWS_CM_00199] (interpretatie: dit geldt vermoedelijk eveneens voor kEventSingleThread, aangezien de methode alleen voor kPoll is voorzien). Vraag Q-bcd9f07119db44fb (open)

De enumeratie SubscriptionState [SWS_CM_00310] vertegenwoordigt in de namespace ara::com op basis van het type std::uint8_t de actuele toestand van een abonnement. Deze definieert drie afzonderlijke toestanden:

• kNotSubscribed: Het abonnement is inactief.
• kSubscriptionPending: Het abonnement is nog in behandeling of de verbinding wordt hersteld na een uitval.
• kSubscribed: Het abonnement is actief.

Voor synchroon opvragen dient de methode GetSubscriptionState(), die beschikbaar wordt gesteld op proxy-events [SWS_CM_00316], proxy-fields [SWS_CM_11604] en triggers [SWS_CM_01105] alsook skeleton-triggers [SWS_CM_01109]. Al deze opvraagfuncties zijn gedeclareerd als noexcept en waarborgen volledige uitzonderingsveiligheid.

Voor asynchrone reacties op statuswijzigingen kunnen applicaties via SetSubscriptionStateChangeHandler() een callback van het type SubscriptionStateChangeHandler registreren [SWS_CM_00311] [SWS_CM_00333]. Indien een ongeldige of lege handler wordt doorgegeven, treedt de schending InvalidHandlerViolation op [SWS_CM_00333]. Het deregistreren vindt plaats via UnsetSubscriptionStateChangeHandler() [SWS_CM_00334]. Via een template-overload met ExecutorT kan bovendien de uitvoeringscontext voor de callback worden vastgelegd [SWS_CM_11354].

In de levenscyclus van een proxy-instantie is SubscriptionState nauw verweven met de automatische actualisering: valt een service-instantie uit, dan mislukken methodeaanroepen en levert GetSubscriptionState() voor eerder geabonneerde events kSubscriptionPending ARAComAPI §6.1 “Auto Updating of Proxy Instance”. Zodra de service-instantie via de Service Discovery weer bereikbaar is, actualiseert het communicatiebeheer de verbinding transparant; GetSubscriptionState() levert daarop automatisch weer kSubscribed AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2. Het handmatig opnieuw aanmaken van de proxy of opnieuw abonneren is daarbij niet vereist.

De type-alias SubscriptionStateChangeHandler in de namespace ara::com is gedeclareerd als std::function<void(SubscriptionState)> in het headerbestand ara/com/types.h ([SWS_CM_00311]). Deze specificeert de functiesignatuur voor applicatie-eigen callbacks die worden getriggerd zodra de ara::com::SubscriptionState van een geabonneerd proxy-event verandert ([SWS_CM_00311], EXP_ARAComAPI §5.3 “Proxy Class API’s”). Bij de aanroep wordt de nieuwe abonnementstoestand direct als parameter meegegeven; een retourwaarde is niet voorzien ([SWS_CM_00311]).

De registratie van de handler verloopt via de methode SetSubscriptionStateChangeHandler() van de desbetreffende proxy-klasse (EXP_ARAComAPI §5.3.1 “Proxy Class API’s”, EXP_ARAComAPI §5.3 “Proxy Class API’s”). Deze bewerking retourneert een ara::core::Result<void> (EXP_ARAComAPI §5.3 “Proxy Class API’s”), waarmee applicatieontwikkelaars mogelijke fouten bij de registratie synchroon kunnen controleren. Het gericht verwijderen van de geregistreerde callback gebeurt via de aanroep van UnsetSubscriptionStateChangeHandler() conform [SWS_CM_00334] (EXP_ARAComAPI §1 “Introduction”, EXP_ARAComAPI §5.3.1 “Proxy Class API’s”).

Wat betreft het verloop en de gelijktijdigheid vindt de statusnotificatie asynchroon plaats. De aanroep van de handler zal vermoedelijk in de thread-context van de communicatie-infrastructuur plaatsvinden (interpretatie). Vraag Q-8dda0cd4de0070bf (open) Daarom moet de implementatie van de callback snel terugkeren en re-entrant resp. thread-safe zijn opgebouwd. Het samenspel van de handler sluit nauw aan op de levenscyclus van het event-abonnement, met name in combinatie met Subscribe(), Unsubscribe() en GetSubscriptionState() (EXP_ARAComAPI §5.3.1 “Proxy Class API’s”).

Gebruik

De globale functie GetComErrorDomain in de namespace ara::com stelt een referentie naar het foutdomeinobject ara::com::ComErrorDomain beschikbaar [SWS_CM_11334]. De declaratie is via de header ara/com/com_error_domain.h ingebonden en vindt plaats als een synchrone, parameterloze aanroep SWS CommunicationManagement §8.12.3.1.1 “GetComErrorDomain”. Als retourwaarde levert de functie een constante referentie van het type const ara::core::ErrorDomain& op, die het communicatiefoutdomein in het systeem vertegenwoordigt.

Foutafhandeling en exception-veiligheid

De interface is expliciet gedeclareerd als noexcept en geldt als uitzonderingsveilig (exception safe) [SWS_CM_11334]. Aangezien de functieaanroep altijd slaagt, treden er geen runtime-fouten op. Aanroepers hoeven daarom geen foutafhandeling voor de functieaanroep zelf te voorzien. Specifieke foutcodes, terugmeldingskanalen of meldingen aan DET of DEM zijn voor dit opvragen niet gedefinieerd in de specificatie.

Gelijktijdigheid en wisselwerking

Dankzij de declaratie met constexpr en noexcept is de functie vermoedelijk toestandloos, vrij van neveneffecten alsook onbeperkt re-entrant en thread-safe; vermoedelijk kan deze ook tijdens compile-time worden uitgevoerd. Vraag Q-21aafe1fdcb5997b (open) Het beschikbaar gestelde foutdomein dient in het totale systeem als referentie-instantie om foutcodes uit operaties van het Communication Management aan de hand van hun domeinlidmaatschap te verifiëren en af te bakenen van andere foutbronnen [SWS_CM_11334].

De hulpfunctie ara::com::MakeErrorCode dient voor het creëren van een instantie van ara::core::ErrorCode ([SWS_CM_11335], SWS CommunicationManagement §8.12.3.1.2 “MakeErrorCode”). Deze wordt via het headerbestand #include "ara/com/com_error_domain.h" in de namespace ara::com gedeclareerd. Als invoerparameters accepteert deze het foutnummer code van het type ara::com::ComErrc evenals fabrikantspecifieke aanvullende gegevens data van het type ara::core::ErrorDomain::SupportDataType en retourneert het overeenkomstige foutobject synchroon.

Wat betreft de uitvoeringsveiligheid is de functie gespecificeerd als noexcept en uitdrukkelijk geclassificeerd als exceptieveilig („exception safe”) ([SWS_CM_11335]). Runtimemeldingen via DET of DEM zijn voor deze hulpfunctie niet voorzien, aangezien deze uitsluitend dient voor de constructie van foutobjecten. Op grond van de declaratie als constexpr en noexcept zal de functie vermoedelijk vrij van neveneffecten en re-entrant zijn, waardoor aanroepen ook tijdens compilatietijd en vanuit gelijktijdige contexten zijn toegestaan. Vraag Q-43f118920f402d86 (open)

Het architectuurpatroon volgt het platformbrede foutmodel van Adaptive AUTOSAR en wordt voor aangrenzende functionele domeinen analoog beschikbaar gesteld: voor de end-to-end-beveiliging bestaat de functie ara::com::e2e::MakeErrorCode ([SWS_CM_12511], SWS CommunicationManagement §8.15.2.1.2 “MakeErrorCode”), terwijl voor beveiligingsfuncties apext::com::secoc::MakeErrorCode ter beschikking staat ([SWS_CM_12522], SWS CommunicationManagement §C.2.2.1.2 “MakeErrorCode”).