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

Функция-член get специализации ara::core::Future<void, E> служит для ожидания результата асинхронной операции без возвращаемого значения ([SWS_CORE_06226]). Она ведет себя как соответствующая функция std::future и блокирует вызывающую сторону до тех пор, пока не будет готов результат или ошибка ([SWS_CORE_06226], [SWS_CORE_00336]). После вызова экземпляр Future теряет валидность, так что выполняется valid() == false ([SWS_CORE_06226]).

Функция объявлена небезопасной относительно исключений (not exception safe) ([SWS_CORE_06226]). Если в связанном Promise была сохранена ошибка, инициируется соответствующее исключение ([SWS_CORE_06226]). Если общее состояние было преждевременно прекращено, возникает код ошибки kBrokenPromise согласно [SWS_CORE_00400] ([SWS_CORE_06226]). Если get выполняется на уже невалидном экземпляре, функция генерирует FutureException с кодом ошибки kNoState ([SWS_CORE_06226]).

Что касается параллелизма, метод не является потокобезопасным (not thread-safe) ([SWS_CORE_06226]). Поэтому параллельные обращения к одному и тому же объекту требуют внешней синхронизации. Кроме того, функция не участвует в разрешении перегрузки, если исключения C++ отключены в инструментарии компилятора ([SWS_CORE_06226]).

Во взаимодействии с родственными функциями [SWS_CORE_00332] (is_ready) гарантирует, что get заведомо не заблокирует выполнение, если операция уже завершена. Для контекстов без исключений AUTOSAR предлагает в качестве альтернативы [SWS_CORE_00336] (GetResult), который возвращает ошибки через тип результата вместо генерации исключений.

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

Метод then регистрирует операцию продолжения (continuation func) для экземпляра ara::core::Future<void, E> [SWS_CORE_06231]. Вызываемый объект принимает результат операции в виде rvalue-выражения типа Result<void, E>, которое внутренне предоставляется через GetResult [SWS_CORE_06231]. Вызов func может происходить синхронно в контексте then или асинхронно в контексте Promise::set_value(), Promise::SetError() либо в другом месте [SWS_CORE_06231].

Непосредственно после возврата из then исходный Future становится невалидным (valid() == false) [SWS_CORE_06231]. Тип возвращаемого значения адаптируется к типу возвращаемого значения U функции продолжения:

• Если func возвращает Future<T2, E2>, выполняется неявная распаковка и then возвращает Future<T2, E2> [SWS_CORE_06231].
• Если func возвращает Result<T2, E2>, оно также неявно распаковывается в Future<T2, E2> [SWS_CORE_06231].
• Во всех остальных случаях возвращаемым типом является Future<U, E> [SWS_CORE_06231].

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

Стандартизированные коды ошибок для этой функции не специфицированы [SWS_CORE_06231]. Метод объявлен как noexcept, однако определяет два нарушения (violations):

• FutureInvalidViolation: возникает при вызове метода на невалидном Future (если valid() возвращает false) [SWS_CORE_06231].
• FutureContinuationHasThrownViolation: возникает, если продолжение генерирует исключение, не реализующее Violation [SWS_CORE_06231]. Ошибки в продолжении должны вместо этого возвращаться упакованными в Result или Future [SWS_CORE_06231].

Параллелизм и взаимодействие

Метод не является потокобезопасным (not thread-safe) [SWS_CORE_06231]. После возврата из деструктора возвращенного Future ни одно зарегистрированное продолжение больше не выполняется; однако уже запущенное выполнение доводится до конца, поэтому деструктор может блокировать выполнение [SWS_CORE_06231]. В то время как [SWS_CORE_06231] относится к Future<void, E>, [SWS_CORE_00331] описывает вариант для типизированных Future Future<T, E>, а [SWS_CORE_06237] — перегрузку с явным исполнителем (Executor).

Функция then регистрирует вызываемый объект продолжения (continuation) func на экземпляре ara::core::Future<void, E> для выполнения в указанном контексте выполнения executor [SWS_CORE_06237]. Непосредственно после возврата из then вызывающий экземпляр Future теряет свою валидность, так что выполняется valid() == false [SWS_CORE_06237]. Продолжение получает результат исходного экземпляра Future в виде Result<void, E> в форме rvalue-выражения [SWS_CORE_06237]. В качестве возвращаемого значения вызов возвращает новый экземпляр Future, причем типы возвращаемого значения продолжения типа Future<T2, E2> или Result<T2, E2> неявно распаковываются в Future<T2, E2>; в противном случае возвращается Future<U, E> [SWS_CORE_06237].

В отношении параллелизма и жизненного цикла функция специфицирована как непотокобезопасная (not thread-safe) [SWS_CORE_06237]. Продолжение регистрируется во вновь возвращенном объекте Future. После возврата деструктора этого нового Future ни одно продолжение больше не должно выполняться; однако уже выполняющееся продолжение завершается полностью, из-за чего деструктор Future может блокироваться [SWS_CORE_06237].

Функция не объявляет стандартизированных кодов ошибок и определена как noexcept [SWS_CORE_06237]. Если она вызывается на недействительном экземпляре Future, возникает нарушение FutureInvalidViolation [SWS_CORE_06237]. Если продолжение генерирует исключение, это приводит к нарушению FutureContinuationHasThrownViolation [SWS_CORE_06237]. Исключения не должны покидать продолжение, а должны при необходимости преобразовываться в значения ошибок и возвращаться внутри Result или Future [SWS_CORE_06237]. Функция дополняет вариант без исполнителя [SWS_CORE_06231] и является аналогом перегрузок со значениями [SWS_CORE_00331], а также [SWS_CORE_00337].

Функция valid() синхронно проверяет, имеет ли экземпляр ara::core::Future<void, E> общее состояние (Shared State) и пригоден ли он тем самым к использованию [SWS_CORE_06227]. Согласно спецификации она ведёт себя аналогично соответствующей функции из std::future [SWS_CORE_06227]. В качестве возвращаемого значения она возвращает true, если Future пригоден для использования, и false, если он непригоден [SWS_CORE_06227].

Что касается параллелизма и обработки ошибок, метод объявлен как noexcept, является исключебно-безопасным (exception safe) и явно специфицирован как потокобезопасный (thread-safe) [SWS_CORE_06227]. Таким образом, его можно безопасно вызывать из параллельных контекстов.

Во взаимодействии с другими операциями valid() служит для контроля жизненного цикла:

• Если для недействительного объекта Future (valid() == false) вызывается такая операция, как wait() [SWS_CORE_06228] или is_ready() [SWS_CORE_00332], это приводит к нарушению FutureInvalidViolation.
• Потребляющие операции инвалидируют объект: после вызова get() Future больше не является действительным, так что последующие проверки с помощью valid() возвращают значение false [SWS_CORE_06226].
• Аналогично, перемещение через then() [SWS_CORE_00331] или вызовы GetResult() [SWS_CORE_00336] приводят к немедленной инвалидации исходного объекта Future.

Функция-член wait специализации ara::core::Future<void, E> синхронно блокирует вызывающий поток до тех пор, пока результат асинхронной операции не станет доступен в виде значения или ошибки [SWS_CORE_06228]. Функция не принимает параметров, не возвращает значения (void) и в соответствии со спецификацией ведет себя как соответствующая функция std::future [SWS_CORE_06228].

В отношении обработки ошибок и граничных условий действуют следующие требования:

• Безопасность исключений и обработка ошибок: операция объявлена с noexcept и специфицирована как безопасная относительно исключений (exception safe) [SWS_CORE_06228]. Если valid() возвращает false для экземпляра Future, имеет место нарушение FutureInvalidViolation [SWS_CORE_06228]. Конкретное следствие этого нарушения, вероятно, реализовано как платформозависимая обработка ошибок среды выполнения AUTOSAR. Вопрос Q-469e9abc947b9869 (открытый)
• Параллелизм: функция классифицирована как непотокобезопасная (not thread-safe) [SWS_CORE_06228]. Поэтому параллельный доступ к одному и тому же объекту Future без внешней синхронизации недопустим.

Во взаимодействии с другими функциями модуля core существуют следующие возможности:

• С помощью потокобезопасного метода is_ready можно заранее запросить, завершена ли операция; при возврате true метод wait гарантированно больше не блокирует выполнение [SWS_CORE_06232].
• Для предотвращения бесконечной блокировки доступны функции с ограничением по времени wait_for с относительной длительностью [SWS_CORE_06229], а также wait_until с абсолютной временной меткой [SWS_CORE_06230].
• Для первичного шаблонного класса ara::core::Future действуют те же правила синхронного ожидания и ограничения [SWS_CORE_00328].

Метод wait_for специализации ara::core::Future<void, E> синхронно блокирует вызывающий поток на максимальный промежуток времени timeoutDuration или до тех пор, пока результат не станет готов [SWS_CORE_06229]. Семантически он ведет себя аналогично соответствующей стандартной функции std::future::wait_for [SWS_CORE_06229].

В качестве возвращаемого значения функция возвращает статус FutureStatus [SWS_CORE_06229]. Он сигнализирует с помощью FutureStatus::kReady, что значение или ошибка доступны, либо с помощью FutureStatus::kTimeout, что срок истек без получения результата [SWS_CORE_00361]. Состояние, эквивалентное std::future_status::deferred, не предусмотрено [SWS_CORE_00361]. Поведение соответствует общему интерфейсу Future [SWS_CORE_00329].

Для вызова действуют следующие условия относительно параллелизма и обработки ошибок:

• Параллелизм: функция специфицирована как непотокобезопасная (not thread-safe) [SWS_CORE_06229]. Одновременные вызовы на одном и том же экземпляре должны быть защищены на стороне вызывающего кода.
• Случаи ошибок и безопасность исключений: операция объявлена как безопасная относительно исключений (exception safe), а также noexcept [SWS_CORE_06229]. Если объект Future недействителен (valid() возвращает false), имеет место FutureInvalidViolation [SWS_CORE_06229]. Из-за объявления noexcept это нарушение, вероятно, приведет к немедленному аварийному завершению программы. Вопрос Q-4f01aa6e7fbfb12d (открытый)

Функция-член wait_until специализации ara::core::Future<void, E> блокирует вызывающий поток до тех пор, пока не будет достигнут указанный абсолютный момент времени deadline или пока не станет доступно значение либо ошибка [SWS_CORE_06230]. Функция демонстрирует такое же поведение, как и соответствующая стандартная функция C++ std::future::wait_until [SWS_CORE_06230], и обладает той же семантикой, что и универсальная перегрузка для ara::core::Future [SWS_CORE_00330].

Возвращаемое значение типа FutureStatus сигнализирует, истек ли предельный срок или стало доступно значение [SWS_CORE_06230]. При этом состояние kReady указывает на то, что разделяемое состояние готово, тогда как kTimeout означает, что разделяемое состояние не стало готовым до истечения предельного срока [SWS_CORE_00361]. Состояние, аналогичное std::future_status::deferred, в FutureStatus отсутствует [SWS_CORE_00361].

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

• Контекст вызова и поведение при исключениях: функция доступна через заголовочный файл #include "ara/core/future.h", объявлена как noexcept и специфицирована как безопасная относительно исключений (exception safe) [SWS_CORE_06230].
• Состояния ошибок: если Future недействителен, то есть когда valid() возвращает значение false, имеет место нарушение FutureInvalidViolation [SWS_CORE_06230].
• Параллелизм: операция классифицируется как непотокобезопасная (not thread-safe) [SWS_CORE_06230].