класс ara::core::Future

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

Метод get() синхронно извлекает результат типа T из ara::core::Future [SWS_CORE_00326]. Функция ведет себя идентично аналогу в std::future; если асинхронное вычисление все еще продолжается, вызов блокируется до завершения или до возникновения ошибки [SWS_CORE_00336]. В результате вызова объект теряет свое состояние, так что future немедленно становится недействительным (valid() == false) [SWS_CORE_00326]. Неблокирующий вызов можно предварительно обезопасить с помощью is_ready() [SWS_CORE_00332].

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

Сбои сообщаются через исключения C++ [SWS_CORE_00326]:

• Если в связанном Promise через SetError() или SetResult() была сохранена ошибка, генерируется исключение соответствующего типа ошибки [SWS_CORE_00326].
• Если общее состояние (shared state) преждевременно покидается асинхронной операцией, это приводит к ошибке kBrokenPromise согласно FutureErrc [SWS_CORE_00326], [SWS_CORE_00400].
• Если вызов выполняется на недействительном экземпляре, выбрасывается FutureException с кодом ошибки kNoState [SWS_CORE_00326].

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

Операция не является ни потокобезопасной, ни безопасной относительно исключений (not exception safe) [SWS_CORE_00326]. Одновременный доступ к одному и тому же future из нескольких потоков требует внешней синхронизации. Если исключения отключены в тулчейне компилятора, get() не участвует в разрешении перегрузки [SWS_CORE_00326]; для этого случая существует безысключительная альтернатива GetResult() [SWS_CORE_00336]. Для экземпляров без возвращаемого значения доступна специализация Future<void, E>::get() [SWS_CORE_06226].

Функция-член then служит для связывания в цепочку асинхронных вычислений и регистрирует вызываемый объект func как continuation на экземпляре ara::core::Future [SWS_CORE_00331]. После возврата из вызова исходный Future недействителен (valid() == false). Цель вызова получает полученный через GetResult() результат экземпляра в качестве rvalue типа Result<T, E> [SWS_CORE_00331].

Возвращаемый тип then зависит от возвращаемого типа U продолжения (continuation) [SWS_CORE_00331]:

• Если func возвращает Future<T2, E2>, происходит неявное развертывание future (unwrapping) в Future<T2, E2> [SWS_CORE_00331].
• Если func возвращает Result<T2, E2>, происходит неявное развертывание Result (unwrapping) в Future<T2, E2> [SWS_CORE_00331].
• Во всех остальных случаях возвращаемым типом является Future<U, E> [SWS_CORE_00331].

Выполнение func может происходить синхронно в контексте вызова then, в контексте Promise::set_result или Promise::SetError либо в другом контексте [SWS_CORE_00331]. Вызов специфицирован как непотокобезопасный. Continuation регистрируется в возвращенном Future; после возврата из его деструктора ни одно continuation больше не должно выполняться, тогда как уже запущенное выполнение дорабатывает до конца [SWS_CORE_00331].

Стандартизированные коды ошибок отсутствуют [SWS_CORE_00331]. Ошибки должны перехватываться пользователями и передаваться дальше в виде кода ошибки в возвращаемом Result или Future, поскольку исключения не должны покидать continuation. Вызов на недействительном Future вызывает FutureInvalidViolation; если continuation выбрасывает исключение, это приводит к FutureContinuationHasThrownViolation [SWS_CORE_00331].

Для выполнения в явном контексте выполнения доступна перегрузка с экзекутором [SWS_CORE_00337], тогда как для операций без возвращаемого значения задействуется void-специализация [SWS_CORE_06231].

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

Метод then регистрирует continuation (func), который асинхронно выполняется в контексте переданного executor, как только готов результат текущего экземпляра Future [SWS_CORE_00337]. Вызываемая сущность принимает результат экземпляра как rvalue-выражение типа Result<T,E> [SWS_CORE_00337]. Возвращаемый тип определяется типом возвращаемого значения U continuation:

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

Параллелизм и жизненный цикл

Сразу после возврата из вызова метода исходный экземпляр Future становится недействительным (valid() == false) [SWS_CORE_00337]. Функция объявлена как потоконебезопасная [SWS_CORE_00337]. Зарегистрированные continuations управляются во вновь возвращенном Future. По истечении работы его деструктора ни один continuation больше не может быть запущен; уже выполняющееся исполнение доводится до конца, вследствие чего деструктор может блокироваться [SWS_CORE_00337].

Обработка ошибок и взаимодействие

Стандартизированные коды ошибок не определены [SWS_CORE_00337]. Вызов на недействительном экземпляре приводит к нарушению (violation) FutureInvalidViolation [SWS_CORE_00337]. Если continuation выбрасывает исключение, это приводит к FutureContinuationHasThrownViolation; поэтому исключения должны перехватываться и передаваться дальше в виде ошибки через ara::core::Result или ara::core::Future [SWS_CORE_00337]. В отличие от перегрузки без контекста выполнения [SWS_CORE_00331], этот вариант принудительно задает выполнение на переданном Executor; для типов результатов void существует аналогичная специализация [SWS_CORE_06237].

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

Функция объявлена как noexcept, считается безопасной относительно исключений (exception safe) и явно специфицирована как потокобезопасная (thread-safe) [SWS_CORE_00327]. Она сама не генерирует кодов ошибок или исключений и поэтому может безопасно применяться для проверки состояния [SWS_CORE_00327].

При взаимодействии с другими методами Future проверка валидности имеет решающее значение, поскольку вызывающие операции, такие как wait() [SWS_CORE_00328] или is_ready() [SWS_CORE_00332], при недействительном состоянии (valid() == false) вызывают FutureInvalidViolation. Ранее действительный Future автоматически становится недействительным, как только его результат потребляется через get() [SWS_CORE_00326] или GetResult() [SWS_CORE_00336], либо когда зарегистрирована дальнейшая обработка через then() [SWS_CORE_00331], [SWS_CORE_00337].

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

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

• Условие ошибки: если объект Future недействителен (valid == FALSE), имеет место FutureInvalidViolation [SWS_CORE_00328], [SWS_CORE_06228]. Тем не менее функция объявлена как noexcept и классифицирована как исключение-безопасная (exception safe) [SWS_CORE_00328].
• Потокобезопасность: вызов явно классифицирован как not thread-safe [SWS_CORE_00328]. Параллельный доступ к одному и тому же объекту Future без внешней синхронизации недопустим.

Во взаимодействии с родственными интерфейсами перед вызовом рекомендуется проверка с помощью is_ready [SWS_CORE_00332], [SWS_CORE_06232]: если она возвращает true, вызов wait гарантированно больше не блокирует. Если вместо неограниченного ожидания требуется ограниченная по времени операция блокировки, альтернативно доступны wait_for с относительной длительностью [SWS_CORE_00329], [SWS_CORE_06229], а также wait_until с абсолютной временной меткой [SWS_CORE_00330], [SWS_CORE_06230].

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

Функция-член wait_for класса ara::core::Future блокирует вызывающий поток максимум на переданный интервал времени timeoutDuration или до тех пор, пока значение результата или ошибка не станет доступным в разделяемом состоянии [SWS_CORE_00329]. Ее поведение соответствует корреспондирующей функции из std::future [SWS_CORE_00329]. В качестве возвращаемого значения она возвращает FutureStatus [SWS_CORE_00329], которое указывает, доступно ли разделяемое состояние (kReady) или истекло заданное время ожидания (kTimeout) [SWS_CORE_00361].

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

Функция объявлена как noexcept и специфицирована как безопасная относительно исключений (exception safe) [SWS_CORE_00329]. Если объект Future недействителен (valid == FALSE), имеет место нарушение в форме FutureInvalidViolation [SWS_CORE_00329]. Интерпретация: поскольку генерация исключений C++ запрещена, такое нарушение со стороны платформы, вероятно, должно обрабатываться как фатальная ошибка времени выполнения. Вопрос Q-2f22a07f6e143856 (открытый)

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

Операция классифицирована как not thread-safe [SWS_CORE_00329]; поэтому одновременный доступ к одному и тому же экземпляру требует внешней синхронизации. Семантика и сигнатура идентично действуют для специализации шаблона ara::core::Future<void, E> [SWS_CORE_06229]. В отличие от std::future_status, в типе перечисления FutureStatus отсутствует запись для deferred [SWS_CORE_00361].

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

В качестве возвращаемого значения функция возвращает FutureStatus [SWS_CORE_00330]. Этот тип enum сигнализирует через состояние kReady о том, что разделяемое состояние готово (значение или ошибка доступны), либо через kTimeout о том, что срок истек без получения результата [SWS_CORE_00361]. Состояние, аналогичное std::future_status::deferred, в FutureStatus отсутствует [SWS_CORE_00361].

В отношении обработки ошибок и безопасности исключений функция специфицирована как безопасная относительно исключений (exception safe) и noexcept [SWS_CORE_00330]. Однако если функция вызывается на недействительном экземпляре (valid == FALSE), возникает нарушение в виде FutureInvalidViolation [SWS_CORE_00330].

Что касается параллелизма, wait_until классифицируется как непотокобезопасная (not thread-safe) [SWS_CORE_00330]. Поэтому параллельные обращения к одному и тому же объекту ara::core::Future должны синхронизироваться извне. Та же семантика и сигнатура применимы к специализации ara::core::Future<void, E> [SWS_CORE_06230].