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

当 Communication Management (ara::com) 负责数据管理时 ([SWS_CM_90438])，在 Skeleton 级别为事件调用方法 Allocate ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 “Skeleton Class API’s”)，以分配用于传输事件数据的内存。它返回一个类型为 ara::com::SampleAllocateePtr<SampleType> 的实例 ([SWS_CM_90438])。该指针类型在概念上表现得像一个 std::unique_ptr<T>，因此在任何时间点都只有一个参与方拥有该指针的所有权 (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”)。

关于错误处理和异常安全性，Allocate 被指定为 not exception safe ([SWS_CM_90438])。规范定义了两种可能的违例（Violations）：

• SampleAllocationViolation：没有足够的内存资源来分配数据 ([SWS_CM_90438])。
• AllocateUsageViolation：通过用户自定义分配器进行了不允许的分配 ([SWS_CM_90438])。

Allocate 背后的概念主要旨在支持零拷贝机制，特别是在基于共享内存的 IPC 传输中，此时假定读取器和写入器之间存在严格同步 (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”)。实现者必须注意，如果部署中的数据类型未配置为二进制兼容，或者识别逻辑排除了这一点，则序列化要求可能会破坏零拷贝 (ARAComAPI §6 “Event Allocate/Send sample Binding implementer hint”)。

在与发送事件的交互中，通过 Allocate 获取的内存指针被传递给 Send(ara::com::SampleAllocateePtr<SampleType> data) ([SWS_CM_90437])。在调用 Send 之后，一旦 Communication Management 将数据发送给所有订阅应用程序，服务应用程序便不得再访问该数据 ([SWS_CM_90437])。

函数 [SWS_CM_00162] 用于在服务提供者端 <SI-Namespace>::skeleton::events::<Event> 内向所有订阅的应用程序发送事件数据。在此变体中，数据分配的责任完全保留在发起调用的应用程序端。数据对象通过参数 data 传入，随后 Binding 实现在调用期间生成一个内部副本（ARAComAPI, Figure 6.17 “BrakeEvent Class”）。在同步方法调用返回后，应用程序可以立即修改或释放原始内存区域。

该方法使用 noexcept 声明并指定为异常安全。它返回一个 ara::core::Result<void>，在成功情况下包含 void，在错误情况下报告来自 [SWS_CM_10432] 的错误代码（[SWS_CM_00162]）：

• ComErrc::kServiceNotOffered：当服务实例尚未通过 OfferService() 提供时发生。
• ComErrc::kMinimumSendIntervalViolationError：当发送请求的发出速度快于配置的最小发送间隔（ServiceInterfaceDeploymentElement.minimumSendInterval）时发生。

与需要通过 Allocate() 获取类型为 ara::com::SampleAllocateePtr 的指针的零拷贝替代方案 [SWS_CM_90437] 相比，此调用不需要将内存绑定到框架。根据 [SWS_CM_00119]，相同的传输行为和相同的错误条件也适用于字段的更新方法 Update。

用法与调用上下文

方法 Send 在服务骨架（<SI-Namespace>::skeleton::events::<Event>）中的事件实例上调用（[SWS_CM_90437]）。它传输由 Communication Management 负责内存管理的事件数据。类型为 ara::com::SampleAllocateePtr<SampleType> 的参数 data 必须事先通过 Allocate() 获取（[SWS_CM_90437]）。该指针类型在语义上表现为 std::unique_ptr，从而在调用时将数据的所有权转移给通信层（ARAComAPI §6.17 “BrakeEvent Class”）。移交后，禁止发送方应用程序对数据进行任何进一步访问（[SWS_CM_90437]）。

错误处理与边界条件

该函数声明为 noexcept 并返回一个 ara::core::Result<void>（[SWS_CM_90437]）。如果发送失败，结果将包含来自 ara::com::ComErrc 的错误代码（[SWS_CM_10432]）：

• ComErrc::kServiceNotOffered：关联的服务事先尚未通过 OfferService() 提供（[SWS_CM_90437]）。
• ComErrc::kMinimumSendIntervalViolationError：自上次传输以来，为该服务元素配置的最小发送间隔（minimumSendInterval）尚未过去（[SWS_CM_90437]）。

这两种错误情况都具有回滚语义（[SWS_CM_90437]）。因此在调用前必须先提供该服务，且连续的发送调用必须遵守配置的最小间隔。

协作与优化

相较于传入应用程序管理的数据并由 Communication Management 复制的签名 [SWS_CM_00162]，此变体旨在通过共享内存实现零拷贝通信（ARAComAPI §6.18 “Event Allocate/Send sample”）。在此前提下，写入者与读取者之间需要严格同步，同时必须注意通信伙伴之间可能存在的序列化要求（ARAComAPI §6.18 “Event Allocate/Send sample”）。

使用

函数SetSubscriptionStateChangeHandler在骨架作用域（skeleton::events）中注册一个回调处理程序，以监视事件的订阅状态[SWS_CM_12008]。参数handler必须是符合[SWS_CM_00311]且类型为SubscriptionStateChangeHandler的可调用对象。该方法不返回任何返回值，并被指定为noexcept[SWS_CM_12008]。

一旦事件的订阅状态发生更改，Communication Management 就会调用已注册的处理程序[SWS_CM_12012]。在骨架端，一旦活动订阅数量大于零，就会以状态kSubscribed进行此操作[SWS_CM_12013]；当不再存在活动订阅时，则以kNotSubscribed进行此操作[SWS_CM_12014]SWS CommunicationManagement §7.5.4 “Query Service Event Subscription State on Skeleton side”。

错误处理与并发

该操作被归类为exception safe[SWS_CM_12008]。如果传入的 Callable 无效或为 null，则存在InvalidHandlerViolation[SWS_CM_12008]。解释：由于该函数既不抛出异常也不返回错误代码，因此推测该规范违规将通过平台特定的运行时机制被拦截。 问题 Q-a7b7b54f0d538b40 (未决)

允许在运行时覆盖处理程序[SWS_CM_12012]。为了在专用线程或任务上下文中执行，存在带有模板参数executor的重载[SWS_CM_12009]。骨架的触发器元素定义了类似注册[SWS_CM_01110]。

模板函数 SetSubscriptionStateChangeHandler 用于在事件命名空间的 Skeleton 级别（[SWS_CM_12009]）注册用于接收传入订阅状态变更的回调。与不带 Executor 的基础函数（[SWS_CM_12008]）相比，它还额外接收一个执行上下文（executor），已注册的处理程序将在该上下文中执行（[SWS_CM_12009]）。该函数没有返回值，声明为 noexcept 并被视为异常安全（[SWS_CM_12009]）。

关于错误行为，传入无效或空值 Callable 会导致 InvalidHandlerViolation（[SWS_CM_12009]）。已注册的处理程序可以在应用程序运行时随时通过再次调用进行覆盖（[SWS_CM_12012]）。

一旦相应事件的订阅状态发生改变，Communication Management 就会调用该处理程序（SWS CommunicationManagement §7.5.4 “Query Service Event Subscription State on Skeleton side”，[SWS_CM_12012]）：

• 当活跃订阅数从零增加到大于零时，以状态 kSubscribed 进行调用（[SWS_CM_12013]）。
• 当活跃订阅者数量再次降至零时，使用 kNotSubscribed 通知处理程序（[SWS_CM_12014]）。

Interpretation：通过传入 executor，处理程序的执行很可能会被专门绑定到应用程序自身的线程或分发上下文中（[SWS_CM_12009]），以便将 Skeleton 代码的并发通知与内部通信线程清晰地分离开来。 问题 Q-b11f3bc97069f2ec (未决)

函数 UnsetSubscriptionStateChangeHandler 在 Skeleton 级别的命名空间 ::skeleton::events::{<event-name>} 中用于注销先前针对事件的 ara::com::SubscriptionState 注册的状态变更处理程序 [SWS_CM_12010]。该函数不接收传入参数且不返回任何值（void）[SWS_CM_12010]。通过头文件 #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010] 引入。

关于异常行为，该方法使用 noexcept 声明并指定为异常安全（exception safe）[SWS_CM_12010]。不返回特定错误代码或抛出 C++ 异常 [SWS_CM_12010]。解读：由于签名未提供错误反馈，注销时的任何内部错误状态大概率由通信管理在内部拦截。 问题 Q-7e986a15e552ca19 (未决)

在与相关接口的协作中，存在用于处理程序注销的类似函数：

• 在 Skeleton 级别，::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler 为触发器提供相应的注销 [SWS_CM_01112]。
• 在 Proxy 级别，存在等效的方法用于在命名空间 proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s” 内注销针对事件 [SWS_CM_00334]、字段 [SWS_CM_11609] 以及触发器 [SWS_CM_01108] 的状态变更处理程序。