класс <SI-Namespace>::skeleton:: events::<Event>

Метод Allocate вызывается на уровне скелетона для события ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 «Skeleton Class API’s») с целью выделения памяти для передачи данных события, если Communication Management (ara::com) отвечает за управление данными ([SWS_CM_90438]). Он возвращает экземпляр типа 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 направлена прежде всего на поддержку механизмов zero-copy, в частности при IPC-транспорте на основе разделяемой памяти (shared memory), при этом предполагается строгая синхронизация между читателями и писателями (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»). Разработчики реализации должны учитывать, что требования к сериализации могут свести на нет zero-copy, если типы данных в развертывании не настроены как бинарно совместимые или если логика обнаружения исключает это (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 передается объект данных, после чего реализация биндинга создает внутреннюю копию во время вызова (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).

В отличие от zero-copy-альтернативы [SWS_CM_90437], которая требует полученных через Allocate() указателей типа ara::com::SampleAllocateePtr, данный вызов не требует привязки памяти к фреймворку. Такое же поведение передачи и те же условия ошибок действуют согласно [SWS_CM_00119] и для метода обновления Update полей.

Использование и контекст вызова

Метод Send вызывается на экземпляре события в скелетоне сервиса (<SI-Namespace>::skeleton::events::<Event>) ([SWS_CM_90437]). Он передает данные события, за управление памятью которых отвечает Communication Management. Параметр data типа ara::com::SampleAllocateePtr<SampleType> должен быть предварительно получен через 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]). Поэтому перед вызовом сервис обязательно должен быть предложен, а последовательные вызовы отправки должны соблюдать сконфигурированный минимальный интервал.

Взаимодействие и оптимизация

По сравнению с сигнатурой [SWS_CM_00162], при которой передаются данные под управлением приложения и копируются Communication Management, данный вариант нацелен на zero-copy-коммуникацию через разделяемую память (ARAComAPI §6.18 «Event Allocate/Send sample»). При этом предполагается строгая синхронизация между писателями и читателями, причем необходимо учитывать возможные требования к сериализации между участниками коммуникации (ARAComAPI §6.18 «Event Allocate/Send sample»).

Использование

Функция SetSubscriptionStateChangeHandler регистрирует в области видимости скелетона (skeleton::events) обработчик обратного вызова для отслеживания статуса подписки события [SWS_CM_12008]. Параметр handler должен быть вызываемым объектом типа SubscriptionStateChangeHandler согласно [SWS_CM_00311]. Метод не возвращает значения и специфицирован как 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]. Если переданный вызываемый объект недействителен или равен null, имеет место InvalidHandlerViolation [SWS_CM_12008]. Интерпретация: поскольку функция не генерирует исключений и не возвращает код ошибки, это нарушение спецификации, вероятно, перехватывается платформенными механизмами времени выполнения. Вопрос Q-a7b7b54f0d538b40 (открытый)

Обработчик разрешается перезаписывать во время выполнения [SWS_CM_12012]. Для выполнения в выделенном контексте потока или задачи существует перегрузка с шаблонным параметром executor [SWS_CM_12009]. Аналогичную регистрацию для триггерных элементов скелетона определяет [SWS_CM_01110].

Шаблонная функция SetSubscriptionStateChangeHandler служит на уровне скелетона ([SWS_CM_12009]) в пространстве имен события для регистрации callback на изменения состояния входящих подписок. По сравнению с базовой функцией без исполнителя ([SWS_CM_12008]) она дополнительно принимает контекст выполнения (executor), в котором выполняется зарегистрированный обработчик ([SWS_CM_12009]). Функция не имеет возвращаемого значения, объявлена как noexcept и считается безопасной относительно исключений ([SWS_CM_12009]).

Что касается поведения при ошибках, передача недействительного или нулевого вызываемого объекта приводит к 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]).

Интерпретация: передача executor, предположительно, позволяет целенаправленно привязать выполнение обработчика к собственным контекстам потоков или диспетчеризации приложения ([SWS_CM_12009]), чтобы четко отделить параллельное уведомление кода скелетона от внутренних коммуникационных потоков. Вопрос Q-b11f3bc97069f2ec (открытый)

Функция UnsetSubscriptionStateChangeHandler служит на уровне скелетона в пространстве имен ::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::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler предоставляет соответствующую отмену регистрации для триггеров [SWS_CM_01112].
• На уровне прокси существуют эквивалентные методы отмены регистрации обработчиков изменений состояния для событий [SWS_CM_00334], полей [SWS_CM_11609] и триггеров [SWS_CM_01108] в пространстве имен proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s».