класс <SI-Namespace>::proxy::<SI>Proxy

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

Статический фабричный метод Create служит согласно [SWS_CM_10438] для создания экземпляра прокси (<SI>Proxy) без генерации исключений в соответствии с идиомой именованного конструктора. В качестве параметра handle он требует предварительно определенный дескриптор сервиса согласно [SWS_CM_00131]. Вызов выполняется синхронно и объявлен как noexcept. Результат возвращается в ara::core::Result, который в случае успеха содержит готовый к работе экземпляр прокси.

Обработка ошибок

Если во время инстанцирования возникает ошибка, Create через ara::core::Result возвращает код ошибки типа ara::com::ComErrc [SWS_CM_10438]:

• ComErrc::kServiceNotAvailable: сервис больше не доступен после предварительного предложения через OfferService().
• ComErrc::kCommunicationFailure: сетевая привязка сообщает об устранимой ошибке коммуникации или сбое защищенного соединения.

Обе ошибки обладают семантикой отката (rollback) [SWS_CM_10438]. При структурных ошибках или ошибках, связанных с безопасностью, действуют специфицированные нарушения (violations): если переданный дескриптор равен null или поврежден, имеет место ErroneousServiceHandleViolation. Если у вызывающего процесса в рамках grant enforcement отсутствуют необходимые полномочия для экземпляра, запрос отклоняется и обрабатывается как InsufficientPermissionsViolation (SWS CommunicationManagement §8 «Security», [SWS_CM_10438]).

Параллелизм и граничные условия

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

Статический метод FindService класса Proxy служит для синхронного поиска доступных экземпляров сервисов по ara::com::InstanceIdentifier ([SWS_CM_00122]). Вызов непосредственно возвращает результат в виде ara::core::Result, который при успешном выполнении содержит ara::com::ServiceHandleContainer ([SWS_CM_00122]). Этот контейнер — обычно реализуемый как ara::core::Vector ([SWS_CM_00304]) — в зависимости от текущего состояния предоставления может быть пустым, содержать один дескриптор экземпляра или несколько дескрипторов (ARAComAPI §6.5 «Service Discovery»).

В случае сбоя ara::core::Result возвращает код ошибки из ara::com::ComErrc, а именно ComErrc::kCommunicationFailure, если сетевой биндинг сообщает об устранимой ошибке передачи или проблеме с защищенным обменом данными ([SWS_CM_00122]). Кроме того, доступ подлежит проверке прав; недостаточные полномочия приводят к InsufficientPermissionsViolation ([SWS_CM_00122]).

В отношении хода выполнения и параллелизма действуют следующие условия:

• Контекст вызова и синхронность: поскольку поиск выполняется непосредственно, обнаруживаются только те экземпляры, для которых ранее на стороне сервера был вызван OfferService() (ARAComAPI §6.5 «Service Discovery»).
• Безопасность исключений и реентерабельность: функция специфицирована как noexcept и является exception-safe ([SWS_CM_00122]). Поскольку метод является статическим и не требует изменяемого состояния объекта, он, вероятно, реентерабелен и потокобезопасен для вызова. Вопрос Q-3228cc998c4a737e (открытый)
• Дальнейшая обработка: найденные дескрипторы служат для инстанцирования объектов Proxy через конструктор Proxy(const HandleType &handle) ([SWS_CM_00131]). Для поиска на основе модели в качестве альтернативы доступна перегрузка с ara::core::InstanceSpecifier ([SWS_CM_00622]).

Статическая функция FindService класса прокси служит согласно [SWS_CM_00622] для синхронного поиска доступных экземпляров сервиса на основе ara::core::InstanceSpecifier с немедленным возвратом («immediately returned request»). Необходимым условием для поиска является предварительное предоставление соответствующего экземпляра скелетона сервиса с помощью OfferService() (ARAComAPI с. 103 «Figure 6.5: Service Discovery»).

Возвращаемые значения и взаимодействие

В качестве результата вызов возвращает ara::core::Result с ara::com::ServiceHandleContainer согласно [SWS_CM_00622], который по умолчанию базируется на ara::core::Vector [SWS_CM_00304]. Этот контейнер может быть пустым, содержать один дескриптор или несколько найденных экземпляров (ARAComAPI с. 103 «Figure 6.5: Service Discovery»). Полученные дескрипторы сервиса затем передаются в конструктор для инстанцирования объекта прокси [SWS_CM_00131]. В качестве альтернативы для асинхронного поиска по событиям с уведомлением доступен StartFindService [SWS_CM_00623], тогда как для идентификаторов экземпляров используется перегрузка из [SWS_CM_00122].

Обработка ошибок и граничные условия

Функция объявлена как noexcept и считается безопасной относительно исключений («exception safe») согласно [SWS_CM_00622]. В случае ошибки объект Result содержит код ошибки ComErrc::kCommunicationFailure, например, при сбоях связи сетевой привязки [SWS_CM_00622]. Кроме того, [SWS_CM_00622] определяет нарушения модели и прав доступа, такие как InstanceSpecifierMappingIntegrityViolation, PortInterfaceMappingViolation, ProcessMappingViolation, InstanceSpecifierAlreadyInUseViolation, а также InsufficientPermissionsViolation.

Интерпретация: из-за синхронного и немедленного возврата метод, по-видимому, преимущественно подходит для начальных этапов инициализации или целевого опроса, если не требуется непрерывное наблюдение через колбэк. Вопрос Q-ea5b242a6fe41d20 (открытый)

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

Явный конструктор <SI>Proxy инстанцирует типоспецифичный класс прокси сервиса в пространстве имен <SI-Namespace>::proxy [SWS_CM_00131]. В рамках паттерна «прокси-скелетон» этот сгенерированный объект на стороне потребителя сервиса служит локальным фасадом, который перенаправляет вызовы методов к фактической реализации сервиса ARAComAPI Figure 5.1 «Proxy Skeleton Pattern».

Для конструирования в качестве параметра передается ссылка на действительный HandleType [SWS_CM_00131]. Этот идентификатор должен быть предварительно получен через механизмы Service Discovery — либо синхронно через FindService() [SWS_CM_00122], либо асинхронно через зарегистрированный обратный вызов StartFindService() [SWS_CM_00123].

Обработка ошибок

Конструирование не является безопасным с точки зрения исключений (not exception safe) [SWS_CM_00131]. Если на целевой сервис невозможно сослаться, возбуждается ara::com::ComException согласно ara::com::ComErrc::kServiceNotAvailable [SWS_CM_00131]. Кроме того, определены следующие нарушения:

• ErroneousServiceHandleViolation: возникает, если переданный объект HandleType равен null или поврежден [SWS_CM_00131].
• InsufficientPermissionsViolation: возникает, если создание отклонено проверкой прав (Grant Enforcement) [SWS_CM_00131].

Ограничения и жизненный цикл

Для прокси-класса конструктор копирования явно удален (=delete) [SWS_CM_00136]. Передача экземпляра допускается исключительно через конструктор перемещения (Move Constructor), который также специфицирован как небезопасный с точки зрения исключений [SWS_CM_00137]. Во время выполнения после успешного создания при временном сбое и повторной доступности целевого сервиса система управления коммуникацией автоматически обновляет адресацию транспортного уровня существующего экземпляра прокси в фоновом режиме ARAComAPI Figure 6.1 «Auto Updating of Proxy Instance».

Деструктор ~<SI>Proxy () завершает жизненный цикл экземпляра сервисного прокси и освобождает соответствующие локальные ресурсы [SWS_CM_99444]. Сервисный прокси на стороне потребителя служит локальным фасадом для взаимодействия с потенциально удаленной реализацией сервиса и перенаправляет вызовы ARAComAPI §5.1 «Proxy Skeleton Pattern». Объект прокси предварительно инстанцируется через полученный дескриптор сервиса [SWS_CM_00131], который был предоставлен через функции Service Discovery, такие как FindService [SWS_CM_00122].

Для уничтожения и поведения во время выполнения действуют следующие требования и граничные условия:

• Жизненный цикл и семантика: уничтожение происходит синхронно при выходе из области видимости или при явном удалении экземпляра. В то время как конструктор копирования прокси-класса удален [SWS_CM_00136], объект перед своей деструкцией может быть перемещен с использованием семантики перемещения [SWS_CM_00137].
• Безопасность исключений: деструктор специфицирован как not exception safe [SWS_CM_99444].
• Предусловия и поведение при ошибках: нарушение предусловия [SWS_CM_00087] приводит к DanglingSamplesViolation [SWS_CM_99444]. (Интерпретация: перед вызовом деструктора, вероятно, должны быть освобождены все удерживаемые потребителем ссылки на семплы или указатели на данные во избежание недействительных ссылок.) Вопрос Q-5488797b732d9be6 (открытый)
• Взаимодействие: если используется асинхронный поиск сервисов, при необходимости его следует завершить перед освобождением контекста использования через StopFindService [SWS_CM_00125]. Кроме того, обработчики ошибок, зарегистрированные для событий, триггеров и полей, могут быть предварительно сброшены [SWS_CM_00105] [SWS_CM_00108] [SWS_CM_00126].

Статический метод StartFindService [SWS_CM_00123] класса прокси запускает асинхронный поиск экземпляров сервиса по ara::com::InstanceIdentifier с регистрацией callback-обработчика (ARAComAPI §6.5 «Service Discovery»). В вызов передаются ara::com::FindServiceHandler, а также искомый ara::com::InstanceIdentifier [SWS_CM_00123].

В случае успеха функция возвращает ara::core::Result с ara::com::FindServiceHandle [SWS_CM_00123]. Этот идентификатор представляет активный поисковый запрос и строго необходим для того, чтобы позже снова завершить мониторинг доступности сервиса и последующие вызовы обработчика с помощью StopFindService [SWS_CM_00125].

Если при установлении соединения возникает проблема связи, метод возвращает в ara::core::Result код ошибки ComErrc::kCommunicationFailure [SWS_CM_00123]. Если переданный экземпляр Callable недействителен или равен null, это расценивается как InvalidHandlerViolation; отсутствие прав доступа приводит к InsufficientPermissionsViolation [SWS_CM_00123].

Как только подходящий экземпляр сервиса становится доступным в системе, управление коммуникациями вызывает зарегистрированный обработчик с соответствующими хэндлами сервиса [SWS_CM_00123]. На основе сообщенного HandleType приложение может создать конкретный экземпляр прокси через метод именованного конструктора Create [SWS_CM_10438]. Интерпретация: обработчик, по-видимому, выполняется асинхронно в потоке управления коммуникациями, поэтому доступ к общим ресурсам в обработчике должен осуществляться потокобезопасно. Вопрос Q-9dc570d7e65fc808 (открытый) Для поиска по модельному идентификатору альтернативно доступен StartFindService с InstanceSpecifier [SWS_CM_00623].

Статический метод StartFindService класса прокси запускает непрерывный поиск экземпляров сервиса на основе смоделированного ara::core::InstanceSpecifier [SWS_CM_00623]. При вызове передаются InstanceSpecifier, а также функция обратного вызова типа ara::com::FindServiceHandler [SWS_CM_00623]. В качестве возвращаемого значения функция предоставляет ara::core::Result<ara::com::FindServiceHandle> [SWS_CM_00623], который при успешной регистрации предоставляет дескриптор поиска для управления поиском.

Обработка ошибок осуществляется через возвращаемый ara::core::Result. Если в сетевом биндинге возникает устранимая ошибка связи или ошибка защищенной связи, результат содержит код ошибки ComErrc::kCommunicationFailure [SWS_CM_00623]. Кроме того, специфицированы конкретные нарушения (violations): InvalidHandlerViolation, если переданный обработчик недействителен или равен null, InsufficientPermissionsViolation при отсутствии прав из-за grant enforcement, а также такие нарушения моделирования, как InstanceSpecifierMappingIntegrityViolation или PortInterfaceMappingViolation [SWS_CM_00623].

В отношении параллелизма и граничных условий функция объявлена как noexcept и специфицирована как безопасная относительно исключений [SWS_CM_00623]. Выполнение зарегистрированного обработчика, по-видимому, происходит асинхронно с помощью управления связью, как только в системе обнаруживаются подходящие экземпляры сервиса. Вопрос Q-79fb3ff78d517714 (открытый)

При взаимодействии со связанными интерфейсами действуют следующие положения:

• Возвращенный ara::com::FindServiceHandle необходимо сохранять, чтобы завершить текущий поиск через StopFindService [SWS_CM_00125] и остановить получение дальнейших уведомлений.
• Дескрипторы (HandleType), предоставляемые через обратный вызов, обычно служат для инстанцирования объекта прокси через фабричный метод Create [SWS_CM_10438].
• В качестве альтернативы поиску через InstanceSpecifier поиск также может быть инициирован с помощью ara::com::InstanceIdentifier [SWS_CM_00123].

Метод SetServiceStateChangeHandler служит на экземпляре прокси для регистрации функции обратного вызова с целью мониторинга изменений доступности соответствующего сервиса ([SWS_CM_01074], SWS CommunicationManagement §8.3.8.2.4.6 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler)»). Управление коммуникациями вызывает этот обработчик, как только изменяется состояние доступности сервиса (ServiceState) ([SWS_CM_01074]).

В качестве параметра передается функциональный объект типа ara::com::ServiceStateHandler, который специфицирован как std::function<void(ServiceState)> ([SWS_CM_01072]). Функция не имеет возвращаемого значения. Уже зарегистрированный обработчик может быть перезаписан во время выполнения путем повторного вызова ([SWS_CM_01074]).

Что касается обработки ошибок, функция объявлена как безопасная относительно исключений (noexcept) ([SWS_CM_01074]). Если переданный вызываемый объект не существует или равен null, возникает нарушение InvalidHandlerViolation ([SWS_CM_01074]).

Что касается среды выполнения, [SWS_CM_01074] представляет собой базовый интерфейс. Поскольку здесь нельзя передать исполнитель (executor), колбэк, вероятно, будет выполняться во внутреннем контексте потока управления коммуникациями. Вопрос Q-7833435e7aa1da9f (открытый) Если требуется выполнение в специфическом контексте приложения, в качестве альтернативы доступен перегруженный шаблонный вариант с executor согласно [SWS_CM_01076] (SWS CommunicationManagement §8.3.8.2.4.5 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)»).

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

Шаблонный метод SetServiceStateChangeHandler служит в сгенерированном прокси-классе <SI-Namespace>::proxy::<SI>Proxy для регистрации обратного вызова с целью мониторинга доступности сервиса [SWS_CM_01076]. Функция принимает два параметра AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.5 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)»:

• handler: функтор типа ara::com::ServiceStateHandler (определённый как std::function<void(ServiceState)>), который вызывается при каждом изменении статуса доступности [SWS_CM_01072], [SWS_CM_01074].
• executor: контекст выполнения шаблонного типа ExecutorT согласно [SWS_CM_11360], в котором выполняется зарегистрированный обработчик [SWS_CM_01076].

Функция не имеет возвращаемого значения (void) [SWS_CM_01076].

Обработка ошибок и безопасность исключений

Функция объявлена как noexcept и специфицирована как exception safe (безопасная относительно исключений) [SWS_CM_01076]. Если переданный вызываемый обработчик отсутствует или равен null, генерируется InvalidHandlerViolation [SWS_CM_01076].

Параллелизм и ограничения

Зарегистрированный обработчик может быть перезаписан во время выполнения [SWS_CM_01074]. Поскольку выполнение происходит через переданный объект executor [SWS_CM_01076], уведомление, вероятно, обрабатывается асинхронно в предоставленном пользователем контексте потока или диспетчеризации. Вопрос Q-349c5224c3b9cc20 (открытый)

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

Метод расширяет базовый вариант [SWS_CM_01074] явным заданием контекста выполнения [SWS_CM_01076]. Для интеграции требуется заголовочный файл <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h, тогда как тип обработчика взят из ara/com/types.h [SWS_CM_01072].

Статический шаблонный метод StartFindService запускает асинхронный фоновый мониторинг для обнаружения экземпляров сервиса с помощью ara::com::InstanceIdentifier ([SWS_CM_11352], EXP_ARAComAPI §5.3.3 «Proxy Class API’s»). Наряду с целевым экземпляром (instance согласно [SWS_CM_00122]) регистрируются функция обратного вызова (handler согласно [SWS_CM_00123]), а также контекст выполнения (executor шаблонного типа ExecutorT согласно [SWS_CM_11360]) ([SWS_CM_11352]). Уведомления обратного вызова при этом, вероятно, обрабатываются в контексте потока или задачи переданного executor ([SWS_CM_11352]). Вопрос Q-1db520123c1e49a4 (открытый)

В качестве возвращаемого значения вызов возвращает ara::com::FindServiceHandle ([SWS_CM_11352]). Этот дескриптор идентифицирует текущую активность поиска и требуется для того, чтобы позже явно завершить фоновую активность через [SWS_CM_00125] (StopFindService) (EXP_ARAComAPI §5.3.3 «Proxy Class API’s»). Дескрипторы сервисов (HandleType), полученные через зарегистрированный обратный вызов, служат затем для конструирования соответствующих экземпляров прокси ([SWS_CM_00131]).

Функция объявлена как noexcept и специфицирована как исключение-безопасная (exception safe) ([SWS_CM_11352]). Определены следующие нарушения времени выполнения (Violations):

• InvalidHandlerViolation: возникает, если переданная функция-обработчик недействительна или соответствует null ([SWS_CM_11352]).
• InsufficientPermissionsViolation: возникает, если доступ отклонен системой контроля полномочий (Grant Enforcement) ([SWS_CM_11352]).

Если сервис вместо этого требуется искать через модельный ara::core::InstanceSpecifier, альтернативно доступен вариант функции [SWS_CM_11365].

Статическая шаблонная функция StartFindService запускает непрерывный асинхронный поиск экземпляров сервиса на основе ara::core::InstanceSpecifier с регистрацией обработчика оповещений в переданном контексте выполнения [SWS_CM_11365]. В отличие от синхронных однократных поисков, она инициирует фоновую активность по мониторингу доступности сервиса и возвращает ara::com::FindServiceHandle EXP_ARAComAPI §5.3 «Proxy Class APIs».

Параметры и выполнение

Функция принимает три параметра [SWS_CM_11365]:

• handler: функция обратного вызова типа ara::com::FindServiceHandler согласно [SWS_CM_00123], которая вызывается при изменениях доступности экземпляра.
• instance: искомый ara::core::InstanceSpecifier согласно [SWS_CM_00123].
• executor: контекст выполнения шаблонного типа ExecutorT согласно [SWS_CM_11360]. Интерпретация: аргумент шаблона ExecutorT, вероятно, определяет, в каком контексте потока или задачи выполняется зарегистрированный обратный вызов. Вопрос Q-6d46f67d536a391e (открытый)

Обработка ошибок и граничные условия

Сигнатура объявлена как noexcept и специфицирована как exception safe [SWS_CM_11365]. По спецификации определены функциональные нарушения (Violations): InstanceSpecifierMappingIntegrityViolation (разрешение в контексте Executable завершилось неудачей или не является PortPrototype), PortInterfaceMappingViolation и ProcessMappingViolation (несовпадающие сопоставления PortInterface), InstanceSpecifierAlreadyInUseViolation, InvalidHandlerViolation (недействительный или отсутствующий обработчик), а также InsufficientPermissionsViolation при отсутствии прав доступа [SWS_CM_11365].

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

Полученный FindServiceHandle служит для того, чтобы контролируемо завершить текущий фоновый мониторинг путем передачи в StopFindService [SWS_CM_00125]. Дескрипторы, переданные обработчику, используются для создания экземпляров конкретных прокси сервиса с помощью Proxy(handle) [SWS_CM_00131]. Для поиска посредством ara::com::InstanceIdentifier существует альтернативная перегрузка [SWS_CM_11352].

Статическая функция StopFindService класса прокси завершает асинхронный поиск сервисов, ранее запущенный с помощью StartFindService, и останавливает получение дальнейших уведомлений для переданного дескриптора [SWS_CM_00125]. Тем самым технический биндинг прекращает текущую фоновую активность по мониторингу доступности сервисов AP EXP ARAComAPI §5.3 «Proxy Class API’s».

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

• Параметры: в качестве входного параметра функция ожидает ara::com::FindServiceHandle, полученный ранее с помощью одного из методов StartFindService ([SWS_CM_00123], [SWS_CM_00623], [SWS_CM_11352], [SWS_CM_11365], [SWS_CM_00125]).
• Возвращаемое значение и безопасность относительно исключений: функция не возвращает значения (void), объявлена с noexcept и специфицирована как безопасная относительно исключений [SWS_CM_00125].
• Параллелизм и контекст вызова: вызов StopFindService явно разрешен также непосредственно внутри пользовательской функции обратного вызова FindServiceHandler [SWS_CM_00383] AP EXP ARAComAPI §5.3 «Proxy Class API’s». Для этой цели обработчику в качестве параметра передается соответствующий FindServiceHandle [SWS_CM_00383]. Поскольку сам колбэк не обязан быть реентерабельным, сериализация последовательных вызовов должна обеспечиваться разработчиком биндинга AP EXP ARAComAPI §5.3 «Proxy Class API’s».

Функция-член UnsetServiceStateChangeHandler входит в состав сгенерированного прокси-класса в пространстве имен <SI-Namespace>::proxy::<SI>Proxy согласно [SWS_CM_01075] (AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.12 «UnsetServiceStateChangeHandler»). Она подключается через заголовочный файл #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h".

В отношении применения, поведения и конкурентности действуют следующие положения:

• Применение: метод имеет сигнатуру void UnsetServiceStateChangeHandler() noexcept;. Он не принимает параметров и не возвращает значения. Интерпретация: судя по идентификатору и ссылке на [SWS_CM_01074], вызов служит для сброса или отмены регистрации ранее зарегистрированного обработчика обратного вызова для изменений состояния сервиса на экземпляре прокси. Вопрос Q-6eb71298a6f37ad9 (открытый)
• Обработка ошибок и безопасность исключений: операция объявлена как noexcept и специфицирована как exception safe ([SWS_CM_01075]). Она не генерирует исключений и не возвращает вызывающей стороне кодов ошибок.
• Взаимодействие и граничные условия: функциональная семантика отсылает к определению в [SWS_CM_01074]. Интерпретация: дерегистрация, по-видимому, вступает в силу синхронно, так что после возврата из вызова функции дальнейшие изменения состояния через прежний обратный вызов не доставляются. Вопрос Q-31348a50d9be537d (открытый)