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

The method Allocate is called at the skeleton level for an event ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 “Skeleton Class API’s”) in order to allocate memory for the transmission of event data when Communication Management (ara::com) is responsible for managing the data ([SWS_CM_90438]). It returns an instance of type ara::com::SampleAllocateePtr<SampleType> ([SWS_CM_90438]). This pointer type conceptually behaves like a std::unique_ptr<T>, so that only one party owns the pointer at any given time (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”).

Regarding error handling and exception safety, Allocate is specified as not exception safe ([SWS_CM_90438]). The specification defines two possible violations:

• SampleAllocationViolation: Insufficient memory resources are available to allocate the data ([SWS_CM_90438]).
• AllocateUsageViolation: The allocation was impermissibly performed via a custom allocator ([SWS_CM_90438]).

The concept behind Allocate primarily aims at supporting zero-copy mechanisms, particularly with shared-memory-based IPC transport, where strict synchronization between readers and writers is assumed (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”). Implementers must note that serialization requirements can negate zero-copy if data types in deployment are not configured to be binary compatible or detection logic precludes this (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”).

In interaction with sending events, the memory pointer obtained via Allocate is passed to Send(ara::com::SampleAllocateePtr<SampleType> data) ([SWS_CM_90437]). After calling Send, the service application may no longer access the data once Communication Management transmits the data to all subscribing applications ([SWS_CM_90437]).

The function [SWS_CM_00162] serves on the service provider side within <SI-Namespace>::skeleton::events::<Event> to send event data to all subscribing applications. In this variant, responsibility for data allocation remains entirely with the applying application. The data object is passed via parameter data, whereupon the binding implementation creates an internal copy during the call (ARAComAPI, Figure 6.17 “BrakeEvent Class”). After the synchronous method call returns, the application can immediately modify or free the original memory area.

The method is declared with noexcept and specified as exception-safe. It returns a ara::core::Result<void>, which contains void in case of success and reports error codes from [SWS_CM_10432] in case of error ([SWS_CM_00162]):

• ComErrc::kServiceNotOffered: Occurs if the service instance has not yet been offered via OfferService().
• ComErrc::kMinimumSendIntervalViolationError: Occurs if the send request was issued faster than the configured minimum send interval (ServiceInterfaceDeploymentElement.minimumSendInterval).

In contrast to the zero-copy alternative [SWS_CM_90437], which requires pointers of type ara::com::SampleAllocateePtr obtained via Allocate(), this call does not require any memory binding to the framework. The same transmission behavior and error conditions also apply according to [SWS_CM_00119] to the update method Update of fields.

Usage and Call Context

The method Send is called on an event instance in the service skeleton (<SI-Namespace>::skeleton::events::<Event>) ([SWS_CM_90437]). It transmits event data for whose memory management Communication Management is responsible. The parameter data of type ara::com::SampleAllocateePtr<SampleType> must have been obtained beforehand via Allocate() ([SWS_CM_90437]). This pointer type behaves semantically like a std::unique_ptr, whereby ownership of the data passes to the communication layer upon the call (ARAComAPI §6.17 “BrakeEvent Class”). After the transfer, the sending application is prohibited from any further access to the data ([SWS_CM_90437]).

Error Handling and Boundary Conditions

The function is declared as noexcept and returns a ara::core::Result<void> ([SWS_CM_90437]). If sending fails, the result contains an error code from ara::com::ComErrc ([SWS_CM_10432]):

• ComErrc::kServiceNotOffered: The associated service has not yet been offered beforehand with OfferService() ([SWS_CM_90437]).
• ComErrc::kMinimumSendIntervalViolationError: The minimum sending interval (minimumSendInterval) configured for the service element has not yet elapsed since the last transmission ([SWS_CM_90437]).

Both error cases have rollback semantics ([SWS_CM_90437]). Before the call, the service must therefore mandatorily have been offered, and consecutive send calls must adhere to the configured minimum interval.

Interaction and optimization

Compared to the signature [SWS_CM_00162], in which application-managed data is passed and copied by Communication Management, this variant aims at zero-copy communication via shared memory (ARAComAPI §6.18 “Event Allocate/Send sample”). In doing so, strict synchronization between writers and readers is assumed, whereby possible serialization requirements between communication partners must be observed (ARAComAPI §6.18 “Event Allocate/Send sample”).

use

The function SetSubscriptionStateChangeHandler registers a callback handler in the skeleton scope (skeleton::events) for monitoring the subscription state of an event [SWS_CM_12008]. Parameter handler must be a callable object of type SubscriptionStateChangeHandler according to [SWS_CM_00311]. The method returns no value and is specified as noexcept [SWS_CM_12008].

Communication Management calls the registered handler as soon as the subscription state of the event changes [SWS_CM_12012]. On the skeleton side, this happens with the state kSubscribed as soon as the number of active subscriptions becomes greater than zero [SWS_CM_12013], or with kNotSubscribed when there are no longer any active subscriptions [SWS_CM_12014] SWS CommunicationManagement §7.5.4 “Query Service Event Subscription State on Skeleton side”.

Error Handling and Concurrency

The operation is classified as exception safe [SWS_CM_12008]. If the passed callable is invalid or null, a InvalidHandlerViolation occurs [SWS_CM_12008]. Interpretation: Since the function neither throws exceptions nor returns an error code, this specification violation is likely caught via platform-specific runtime mechanisms. Question Q-a7b7b54f0d538b40 (open)

The handler may be overwritten at runtime [SWS_CM_12012]. For execution in a dedicated thread or task context, the overload with the template parameter executor exists [SWS_CM_12009]. An analogous registration for trigger elements of the skeleton is defined by [SWS_CM_01110].

The template function SetSubscriptionStateChangeHandler serves at the skeleton level ([SWS_CM_12009]) in the namespace of an event to register a callback for state changes of incoming subscriptions. Compared to the basic function without executor ([SWS_CM_12008]), it additionally accepts an execution context (executor) in which the registered handler is executed ([SWS_CM_12009]). The function has no return value, is declared as noexcept, and is considered exception-safe ([SWS_CM_12009]).

Regarding error behavior, passing an invalid or null callable results in a InvalidHandlerViolation ([SWS_CM_12009]). The registered handler can be overwritten at any time during application runtime by calling the function again ([SWS_CM_12012]).

Communication Management calls the handler as soon as the state of the subscriptions for the respective event changes (SWS CommunicationManagement §7.5.4 “Query Service Event Subscription State on Skeleton side”, [SWS_CM_12012]):

• The call is made with status kSubscribed if the number of active subscriptions increases from zero to more than zero ([SWS_CM_12013]).
• If the number of active subscribers drops back to zero, the handler is notified with kNotSubscribed ([SWS_CM_12014]).

Interpretation: By passing executor, the execution of the handler is likely specifically bound to application-owned thread or dispatching contexts ([SWS_CM_12009]) in order to cleanly separate concurrent notification of skeleton code from internal communication threads. Question Q-b11f3bc97069f2ec (open)

The function UnsetSubscriptionStateChangeHandler is used on the skeleton level in namespace ::skeleton::events::{<event-name>} to deregister a previously registered state change handler for the ara::com::SubscriptionState of an event [SWS_CM_12010]. The function takes no parameters and returns no value (void) [SWS_CM_12010]. Inclusion is done via header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010].

Regarding exception behavior, the method is declared with noexcept and specified as exception safe (exception safe) [SWS_CM_12010]. No specific error codes are returned or C++ exceptions thrown [SWS_CM_12010]. Interpretation: Any internal error states during deregistration should be caught internally by Communication Management, since the signature does not provide for error feedback. Question Q-7e986a15e552ca19 (open)

In interaction with related interfaces, analogous functions for handler deregistration exist:

• On the skeleton level, ::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler provides the corresponding deregistration for triggers [SWS_CM_01112].
• On the proxy level, equivalent methods for deregistering state change handlers exist for events [SWS_CM_00334], fields [SWS_CM_11609], and triggers [SWS_CM_01108] within namespace proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”.