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

De methode Allocate wordt op skeletonniveau voor een event aangeroepen ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 “Skeleton Class API’s”) om geheugen voor de overdracht van eventgegevens te alloceren wanneer het Communication Management (ara::com) verantwoordelijk is voor het beheer van de gegevens ([SWS_CM_90438]). Ze levert een instantie van het type ara::com::SampleAllocateePtr<SampleType> op ([SWS_CM_90438]). Dit pointertype gedraagt zich conceptueel als een std::unique_ptr<T>, zodat op elk moment slechts één partij eigenaar van de pointer is (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”).

Wat betreft foutafhandeling en uitzonderingsveiligheid is Allocate gespecificeerd als not exception safe ([SWS_CM_90438]). De specificatie definieert twee mogelijke overtredingen (violations):

• SampleAllocationViolation: Er zijn onvoldoende geheugenbronnen beschikbaar om de gegevens te alloceren ([SWS_CM_90438]).
• AllocateUsageViolation: De allocatie vond ontoelaatbaarderwijs plaats via een door de gebruiker gedefinieerde allocator ([SWS_CM_90438]).

Het concept achter Allocate is primair gericht op de ondersteuning van zero-copy-mechanismen, met name bij op shared memory gebaseerd IPC-transport, waarbij een strikte synchronisatie tussen lezers en schrijvers wordt verondersteld (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”). Implementeerders moeten er rekening mee houden dat serialisatievereisten zero-copy teniet kunnen doen indien gegevenstypen bij de deployment niet binair compatibel geconfigureerd zijn of detectielogica dit uitsluit (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”).

In interactie met het verzenden van events wordt de via Allocate verkregen geheugenpointer doorgegeven aan Send(ara::com::SampleAllocateePtr<SampleType> data) ([SWS_CM_90437]). Na de aanroep van Send mag de servicetoepassing geen toegang meer hebben tot de gegevens zodra het Communication Management de gegevens naar alle abonnerende applicaties verzendt ([SWS_CM_90437]).

De functie [SWS_CM_00162] dient aan service-provider-zijde binnen <SI-Namespace>::skeleton::events::<Event> voor het verzenden van event-gegevens naar alle abonnende applicaties. Bij deze variant blijft de verantwoordelijkheid voor de data-allocatie volledig bij de toepassende applicatie. Via de parameter data wordt het data-object meegegeven, waarna de binding-implementatie tijdens de aanroep een interne kopie maakt (ARAComAPI, Figure 6.17 “BrakeEvent Class”). Na terugkeer van de synchrone methode-aanroep kan de applicatie het oorspronkelijke geheugengebied direct wijzigen of vrijgeven.

De methode is gedeclareerd met noexcept en gespecificeerd als uitzonderingsveilig. Deze geeft een ara::core::Result<void> terug, die in geval van succes void bevat en in geval van een fout foutcodes uit [SWS_CM_10432] meldt ([SWS_CM_00162]):

• ComErrc::kServiceNotOffered: Treedt op wanneer de service-instantie nog niet via OfferService() beschikbaar is gesteld.
• ComErrc::kMinimumSendIntervalViolationError: Treedt op wanneer het verzendverzoek sneller dan het geconfigureerde minimale verzendinterval (ServiceInterfaceDeploymentElement.minimumSendInterval) is verstuurd.

In tegenstelling tot het zero-copy-alternatief [SWS_CM_90437], dat via Allocate() verkregen pointers van het type ara::com::SampleAllocateePtr vereist, vereist deze aanroep geen geheugenbinding aan het framework. Ditzelfde overdrachtsgedrag en dezelfde foutvoorwaarden gelden conform [SWS_CM_00119] ook voor de updatemethode Update van fields.

Gebruik en aanroepcontext

De methode Send wordt aangeroepen op een event-instantie in het service-skeleton (<SI-Namespace>::skeleton::events::<Event>) ([SWS_CM_90437]). Deze draagt event-data over voor het geheugenbeheer waarvan Communication Management verantwoordelijk is. De parameter data van het type ara::com::SampleAllocateePtr<SampleType> moet vooraf verkregen zijn via Allocate() ([SWS_CM_90437]). Dit pointertype gedraagt zich semantisch als een std::unique_ptr, waardoor het eigendom van de data bij de aanroep overgaat naar de communicatielaag (ARAComAPI §6.17 “BrakeEvent Class”). Na de overdracht is elke verdere toegang tot de data door de zendende applicatie verboden ([SWS_CM_90437]).

Foutafhandeling en randvoorwaarden

De functie is gedeclareerd als noexcept en retourneert een ara::core::Result<void> ([SWS_CM_90437]). Mislukt het verzenden, dan bevat het resultaat een foutcode uit ara::com::ComErrc ([SWS_CM_10432]):

• ComErrc::kServiceNotOffered: De bijbehorende service is vooraf nog niet beschikbaar gesteld met OfferService() ([SWS_CM_90437]).
• ComErrc::kMinimumSendIntervalViolationError: Het voor het service-element geconfigureerde minimale zendinterval (minimumSendInterval) is sinds de laatste overdracht nog niet verstreken ([SWS_CM_90437]).

Beide foutgevallen hebben rollback-semantiek ([SWS_CM_90437]). Voorafgaand aan de aanroep moet de service daarom dwingend zijn aangeboden, en opeenvolgende zendaanroepen moeten de geconfigureerde minimumafstand aanhouden.

Interactie en optimalisatie

In vergelijking met de signatuur [SWS_CM_00162], waarbij applicatiebeheerde data worden overgedragen en door Communication Management worden gekopieerd, richt deze variant zich op zero-copy-communicatie via shared memory (ARAComAPI §6.18 “Event Allocate/Send sample”). Daarbij wordt een strikte synchronisatie tussen schrijvers en lezers verondersteld, waarbij rekening moet worden gehouden met mogelijke serialisatievereisten tussen de communicatiepartners (ARAComAPI §6.18 “Event Allocate/Send sample”).

Gebruik

De functie SetSubscriptionStateChangeHandler registreert in de skeleton-scope (skeleton::events) een callback-handler voor het bewaken van de subscriptiestatus van een event [SWS_CM_12008]. De parameter handler moet een aanroepbaar object zijn volgens type SubscriptionStateChangeHandler conform [SWS_CM_00311]. De methode levert geen retourwaarde op en is gespecificeerd als noexcept [SWS_CM_12008].

Communication Management roept de geregistreerde handler aan zodra de subscriptiestatus van het event verandert [SWS_CM_12012]. Aan de skeleton-zijde gebeurt dit met de toestand kSubscribed zodra het aantal actieve abonnementen groter dan nul wordt [SWS_CM_12013], resp. met kNotSubscribed wanneer er geen actieve subscripties meer aanwezig zijn [SWS_CM_12014] SWS CommunicationManagement §7.5.4 “Query Service Event Subscription State on Skeleton side”.

Foutafhandeling en gelijktijdigheid

De bewerking is geclassificeerd als exception safe [SWS_CM_12008]. Als het overgedragen callable ongeldig of null is, is er sprake van een InvalidHandlerViolation [SWS_CM_12008]. Interpretatie: Aangezien de functie noch excepties werpt noch een foutcode retourneert, zal deze specificatieovertreding vermoedelijk via platformspecifieke runtimemechanismen worden opgevangen. Vraag Q-a7b7b54f0d538b40 (open)

De handler mag tijdens runtime worden overschreven [SWS_CM_12012]. Voor uitvoering in een dedicated thread- resp. taakcontext bestaat de overload met de template-parameter executor [SWS_CM_12009]. Een analoge registratie voor trigger-elementen van het skeleton wordt gedefinieerd door [SWS_CM_01110].

De template-functie SetSubscriptionStateChangeHandler dient op skeleton-niveau ([SWS_CM_12009]) in de namespace van een event voor de registratie van een callback voor statuswijzigingen van inkomende abonnementen. Ten opzichte van de basisfunctie zonder executor ([SWS_CM_12008]) accepteert deze tevens een uitvoeringscontext (executor) waarin de geregistreerde handler wordt uitgevoerd ([SWS_CM_12009]). De functie heeft geen retourwaarde, is gedeclareerd als noexcept en geldt als uitzonderingsveilig ([SWS_CM_12009]).

Wat betreft het foutgedrag leidt het meegeven van een ongeldige of null-waardige callable tot een InvalidHandlerViolation ([SWS_CM_12009]). De geregistreerde handler kan tijdens runtime van de applicatie op elk moment worden overschreven door een hernieuwde aanroep ([SWS_CM_12012]).

Communication Management roept de handler aan zodra de status van de abonnementen voor het desbetreffende event verandert (SWS CommunicationManagement §7.5.4 “Query Service Event Subscription State on Skeleton side”, [SWS_CM_12012]):

• De aanroep vindt plaats met de status kSubscribed wanneer het aantal actieve abonnementen stijgt van nul naar meer dan nul ([SWS_CM_12013]).
• Daalt het aantal actieve abonnees weer naar nul, dan wordt de handler met kNotSubscribed geïnformeerd ([SWS_CM_12014]).

Interpretatie: door de overdracht van executor wordt de uitvoering van de handler vermoedelijk gericht gebonden aan applicatie-eigen thread- of dispatching-contexten ([SWS_CM_12009]), om de gelijktijdige notificatie van de skeleton-code netjes te scheiden van interne communicatie-threads. Vraag Q-b11f3bc97069f2ec (open)

De functie UnsetSubscriptionStateChangeHandler dient op skeleton-niveau in de namespace ::skeleton::events::{<event-name>} om een eerder geregistreerde statuswijzigingshandler voor de ara::com::SubscriptionState van een event te deregistreren [SWS_CM_12010]. De functie accepteert geen overdrachtsparameters en levert geen retourwaarde op (void) [SWS_CM_12010]. Het invoegen geschiedt via de header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010].

Wat betreft het uitzonderingsgedrag is de methode gedeclareerd met noexcept en gespecificeerd als uitzonderingsveilig (exception safe) [SWS_CM_12010]. Er worden geen specifieke foutcodes geretourneerd of C++-excepties geworpen [SWS_CM_12010]. Interpretatie: Eventuele interne fouttoestanden bij de deregistratie worden vermoedelijk intern door het communicatiebeheer afgevangen, aangezien de signatuur niet voorziet in een foutterugmelding. Vraag Q-7e986a15e552ca19 (open)

In interactie met gerelateerde interfaces bestaan er analoge functies voor handler-deregistratie:

• Op skeleton-niveau biedt ::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler de overeenkomstige deregistratie voor triggers [SWS_CM_01112].
• Op proxy-niveau bestaan equivalente methoden voor de deregistratie van statuswijzigingshandlers voor events [SWS_CM_00334], fields [SWS_CM_11609] en triggers [SWS_CM_01108] binnen de namespace proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”.