класс ara::exec::ExecutionClient

Класс ara::exec::ExecutionClient служит процессам приложений для обязательного сообщения своего внутреннего состояния выполнения в Execution Management ([SWS_EM_02003]). При инициализации он также берёт на себя перехват сигнала SIGTERM и пересылает его пользовательскому обработчику завершения в фоновом потоке ([SWS_EM_02562]). Являясь объектом, допускающим только перемещение (move-only), экземпляр строго привязывает обработку сигналов к своему жизненному циклу и восстанавливает прежнее состояние сигнала при уничтожении. Вызывающие стороны должны гарантировать, что зарегистрированный callback остаётся доступным для вызова на протяжении всего времени жизни экземпляра.

больше ›

Контекст

Класс ara::exec::ExecutionClient служит процессам на Adaptive Platform для сообщения своего внутреннего состояния выполнения в Execution Management ([SWS_EM_02003]). Он действует как стандартизированный интерфейс между работающим приложением и центральным управлением процессами. Помимо пересылки переходов состояний, экземпляр берёт на себя ответственность за обработку сигнала операционной системы SIGTERM ([SWS_EM_02562], [SWS_EM_02002]). При поступлении сигнала он выполняет пользовательский callback в отдельном фоновом потоке, чтобы обеспечить приложению упорядоченное завершение ([SWS_EM_02562]). Интерпретация: операционная система или Execution Management, вероятно, передаёт сигнал SIGTERM процессу, когда запрашивается завершение исполнимой единицы. Вопрос Q-51eee947d01ae8b4 (открытый)

Контекстная диаграмма: взаимодействие между процессом приложения, ExecutionClient, Execution Management и сигнальным механизмом. Источники: [SWS_EM_02003], [SWS_EM_02562], [SWS_EM_02002].

Жизненный цикл

Инстанцирование ara::exec::ExecutionClient выполняется на выбор через статический фабричный метод Create ([SWS_EM_02562]) или через обычный конструктор ([SWS_EM_02560]). В то время как Create является безопасным относительно исключений (noexcept) и возвращает результат, инкапсулированный в ara::core::Result ([SWS_EM_02562]), обычный конструктор объявлен как noexcept(false) ([SWS_EM_02560]). Оба пути создания ожидают в качестве параметра вызываемый callback std::function<void()> (terminationHandler). Этот callback должен оставаться валидным и доступным для вызова на протяжении всего времени жизни экземпляра ExecutionClient ([SWS_EM_02562], [SWS_EM_02560]).

С точки зрения владения класс спроектирован как move-only: конструктор копирования ([SWS_EM_02563]), а также оператор присваивания с копированием ([SWS_EM_02564]) явно удалены (delete). Перемещение экземпляров возможно исключительно через конструктор перемещения ([SWS_EM_02580]) и оператор присваивания с перемещением ([SWS_EM_02581]), которые оба являются безопасными относительно исключений (noexcept), однако не являются потокобезопасными. Фабричный метод Create и сам конструктор считаются потокобезопасными ([SWS_EM_02562], [SWS_EM_02560]).

Деструктор ~ExecutionClient() определён как noexcept ([SWS_EM_02002]) и не является потокобезопасным. При уничтожении экземпляра ответственность за сигнал SIGTERM снимается: деструктор возвращает обработчик сигналов для SIGTERM в исходное состояние, активное до инстанцирования ([SWS_EM_02002]).

Путь использования

Штатная работа делится на инициализацию, передачу состояния и упорядоченное завершение:

• Создание: в начале времени работы процесса экземпляр инициализируется через Create, при этом передаётся обработчик завершения ([SWS_EM_02562]). Как правило, этот обработчик устанавливает флаг или сигнализирует примитивам синхронизации для разблокировки работающих потоков.
• Сообщение о состоянии: как только процесс готов, он сообщает свой статус выполнения в Execution Management через ReportExecutionState ([SWS_EM_02003]). Вызов является потокобезопасным и может выполняться из различных рабочих потоков.
• Получение сигнала и завершение: если во время работы поступает сигнал SIGTERM, ExecutionClient асинхронно активирует сохранённый terminationHandler в фоновом потоке ([SWS_EM_02562]). Процесс упорядоченно завершает открытые задачи.
• Уничтожение: при выходе из области видимости деструктор восстанавливает исходную конфигурацию сигналов ([SWS_EM_02002]).

Диаграмма последовательности: ход выполнения от создания через сообщение о состоянии до управляемого сигналами завершения. Источники: [SWS_EM_02562], [SWS_EM_02003], [SWS_EM_02002].

Сценарии ошибок

При использовании ExecutionClient различные ошибочные ситуации охватываются кодами ошибок из ara::exec::ExecErrc:

• ara::exec::ExecErrc::kInvalidArgument: возникает при инстанцировании через Create ([SWS_EM_02562]) или обычный конструктор ([SWS_EM_02560]), если переданный объект terminationHandler не содержит вызываемой функции. Система применяет семантику отката (rollback); для устранения необходимо передать валидный callable-объект.
• ara::exec::ExecErrc::kNoCommunication: может возникать как при создании ([SWS_EM_02562], [SWS_EM_02560]), так и при ReportExecutionState ([SWS_EM_02003]), если имеет место ошибка связи между процессом приложения и Execution Management (например, отсутствие подтверждения приема сообщения). При этом семантика отката (rollback) не действует; в качестве меры восстановления предусмотрена повторная попытка вызова.
• ara::exec::ExecErrc::kInvalidTransition: возвращается из ReportExecutionState ([SWS_EM_02003]) в случае запроса недопустимой смены состояния, например при повторном сообщении об уже активном состоянии, таком как kRunning. Поскольку о состоянии уже было сообщено, повторная передача не требуется (семантика отката).