класс ara::core::Promise< void, E >

Специализация ara::core::Promise< void, E > служит асинхронной конечной точкой производителя для сигнализации о завершении операции без возвращаемого значения или для передачи ошибки ([SWS_CORE_06341]). После инстанцирования через get_future() ровно один раз запрашивается соответствующий Future для потребителя ([SWS_CORE_06344]). Предоставление выполняется потокобезопасно (thread-safe) с помощью set_value(), SetError() или SetResult(), благодаря чему разделяемое состояние помечается как готовое. Поскольку класс обладает исключительно семантикой перемещения, многократная установка или отсутствие разделяемого состояния приводят к специфицированным нарушениям.

больше ›

Контекст

Класс ara::core::Promise< void, E > представляет собой шаблонную специализацию для асинхронных процессов без полезного значения (тип возвращаемого значения void). Он образует сторону производителя (Producer) канала связи и синхронизирует асинхронные вычисления или операции со стороной потребителя (Consumer). Через общее внутреннее состояние (Shared State) он позволяет сигнализировать либо об успешном завершении операции, либо о возникновении ошибки типа E. Соответствующий объект-получатель предоставляется в форме ara::core::Future< void, E > ([SWS_CORE_06344]). Согласно требованиям AUTOSAR Adaptive Platform, реализация требует, чтобы тип ошибки E был совместим с ara::core::ErrorCode; любое отклонение приводит к ошибке компиляции.

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

Создание экземпляра выполняется через конструктор по умолчанию без параметров [SWS_CORE_06341], который создает новое общее состояние и ведет себя аналогично стандартной функции C++ std::promise. Класс моделирует эксклюзивное владение и реализует строгую семантику перемещения: как конструктор копирования ([SWS_CORE_06350]), так и оператор присваивания с копированием ([SWS_CORE_06351]) удалены (delete).

Существующее состояние может быть передано другим экземплярам через конструктор перемещения ([SWS_CORE_06342]) или оператор присваивания с перемещением ([SWS_CORE_06343]). При присваивании с перемещением удерживаемое до этого момента Shared State сбрасывается, и состояние передается так, как если бы использовался Promise(std::move(other)).swap(*this) ([SWS_CORE_06343]). Кроме того, функция swap ([SWS_CORE_06352]) позволяет напрямую обменивать два состояния.

Деструктор [SWS_CORE_06349] освобождает удерживаемое Shared State, если таковое имеется. Интерпретация: преждевременный сброс Shared State при уничтожении еще не удовлетворенного Promise, вероятно, приведет к переходу связанного Future в повисшее (осиротевшее) состояние. Вопрос Q-e89b32fa3e5994e2 (открытый) В отношении параллелизма создание по умолчанию ([SWS_CORE_06341]) и установка результата ([SWS_CORE_06345], [SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]) являются потокобезопасными (thread-safe). Напротив, операции перемещения, swap, получение Future ([SWS_CORE_06344]) и уничтожение не являются thread-safe и требуют внешней координации при совместном доступе.

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

Типичное использование ara::core::Promise< void, E > включает подготовку асинхронного выполнения, передачу канала приема и последующее оповещение о результате:

1. Инициализация: производитель инстанцирует объект Promise ([SWS_CORE_06341]).
2. Получение Future: с помощью get_future() ровно один раз создается связанный ara::core::Future< void, E > ([SWS_CORE_06344]) и передается на сторону потребителя.
3. Установка результата: после завершения асинхронной операции производитель переводит разделяемое состояние в состояние готовности (ready):
   • в случае успеха — путем вызова set_value() без аргументов ([SWS_CORE_06345]);
   • в случае ошибки — путем сохранения ошибки через SetError, либо с перемещением ([SWS_CORE_06353]), либо с копированием ([SWS_CORE_06354]);
   • в качестве альтернативы — путем передачи полного Result< void, E > с помощью SetResult с копированием ([SWS_CORE_06355]) или с перемещением ([SWS_CORE_06356]).
4. Разрешение: как только состояние становится готовым, потребитель может получить результат через Future; объект Promise освобождается в конце своей области видимости ([SWS_CORE_06349]).

Диаграмма последовательности: типичный процесс асинхронной синхронизации от создания до предоставления результата. Источники: [SWS_CORE_06341], [SWS_CORE_06344], [SWS_CORE_06345], [SWS_CORE_06349]

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

Нарушения предусловий приводят к определенным ошибочным ситуациям (Violations):

• IsoStdFutureErrcFutureAlreadyRetrievedViolation: генерируется, если get_future() вызывается несколько раз для одного и того же разделяемого состояния ([SWS_CORE_06344]).
• IsoStdFutureErrcNoStateViolation: возникает, когда get_future() вызывается без наличия у Promise разделяемого состояния ([SWS_CORE_06344]), например после операции перемещения ([SWS_CORE_06342]).
• IsoStdFutureErrcPromiseAlreadySatisfiedViolation: возникает, если set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) или SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) вызывается, когда в Shared State уже сохранены значение или ошибка.
• PromiseNoSharedStateToSetViolation: сигнализирует о том, что set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) или SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) были вызваны при отсутствии существующего разделяемого состояния.

С точки зрения безопасности исключений методы SetError и SetResult являются условно безопасными к исключениям (conditionally exception safe): они гарантируют noexcept только в том случае, если тип E классифицирован как nothrow-move-конструируемый или nothrow-copy-конструируемый ([SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]).