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

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

Функция-член Bind специализации ara::core::Result<void, E> из ara/core/result.h выполняет последующее вычисление на успешном экземпляре без значения результата [SWS_CORE_00870]. Если значение присутствует, переданный callable f вызывается синхронно и без параметров. Callable должен удовлетворять либо интерфейсу Result<XXX, E> f(), либо XXX f(), где XXX должен быть допустимым типом для Result [SWS_CORE_00870]. Если callable возвращает Result, тип возвращаемого значения соответствует decltype(f()); если он возвращает напрямую XXX, результат упаковывается как Result<decltype(f()), E> [SWS_CORE_00870].

Обработка ошибок и параллелизм

Если экземпляр не содержит значения, возвращается новый Result<XXX, E>, в который копируется исходная ошибка [SWS_CORE_00870]. Интерпретация: в этом случае выполнение callable f, вероятно, не происходит. Вопрос Q-6288a7106d2730c3 (открытый) В плане безопасности выполнения функция считается not exception safe [SWS_CORE_00870]. Потокобезопасность является условной (conditional) и полностью зависит от потокобезопасности переданного callable f [SWS_CORE_00870].

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

В отличие от первичных функций Result<T, E> из [SWS_CORE_00768] и [SWS_CORE_00941], в которых callable принимает значение экземпляра через f(const T&), данная перегрузка [SWS_CORE_00870] привязывает операции к результатам void и поэтому ожидает callable без параметров.

Функция-член EmplaceError специализации ara::core::Result<void, E> синхронно конструирует новое значение ошибки непосредственно in-place внутри существующего экземпляра из переданных аргументов args [SWS_CORE_00844]. Предоставляемая через заголовочный файл ara/core/result.h шаблонная функция не имеет возвращаемого значения и инициализирует объект ошибки типа E непосредственно на месте [SWS_CORE_00844].

Что касается обработки ошибок и безопасности относительно исключений, операция классифицирована как условно безопасная относительно исключений (conditionally exception safe) [SWS_CORE_00844]. С помощью спецификатора noexcept(std::is_nothrow_constructible<E, Args...>::value) отсутствие исключений гарантируется при условии, что тип E может быть сконструирован с типами Args... без исключений [SWS_CORE_00844].

В отношении многопоточности и граничных условий функция-член определена как непотокобезопасная (not thread-safe) [SWS_CORE_00844]. Если несколько потоков параллельно обращаются к одному и тому же экземпляру Result, для предотвращения нескоординированных изменений состояния, вероятно, требуется внешний механизм синхронизации. Вопрос Q-ffcb8ced860f6080 (открытый)

В общем контексте модуля core [SWS_CORE_00844] напрямую соответствует другим вариантам этой же функции: для первичного шаблона ara::core::Result идентичное поведение специфицировано под [SWS_CORE_00744], тогда как для ссылочных типов ara::core::Result<T&, E> требование [SWS_CORE_00916] задает ту же сигнатуру и семантику.

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

Шаблонная функция-член EmplaceValue принадлежит модулю core и определяется через заголовочный файл #include "ara/core/result.h" для специализации ara::core::Result<void, E> [SWS_CORE_00843]. Ее назначением является прямое создание или установка нового значения в существующем экземпляре на основе переданных аргументов args [SWS_CORE_00843]. Выполнение происходит синхронно и не возвращает значения (void) [SWS_CORE_00843]. Поскольку типом значения специализации является void, вызов переводит экземпляр в состояние успеха; в качестве интерпретации прием args, вероятно, служит главным образом для совместимости сигнатуры на обобщенном уровне с первичным классом шаблона. Вопрос Q-b53ca5908f2517fb (открытый)

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

Функция объявлена как noexcept и имеет спецификацию exception safe [SWS_CORE_00843]. Она не возвращает кодов ошибок и не генерирует исключений. Если объект Result ранее находился в состоянии ошибки, оно перезаписывается установкой значения.

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

Операция обозначена как непотокобезопасная (not thread-safe) [SWS_CORE_00843]. При потенциально параллельных обращениях на чтение или запись к одному и тому же экземпляру ara::core::Result внешняя синхронизация со стороны вызывающего кода является строго обязательной.

Взаимодействие со смежными спецификациями

По сравнению с общей реализацией EmplaceValue для ara::core::Result<T, E> в [SWS_CORE_00743], которая безопасна относительно исключений лишь условно и чье свойство noexcept зависит от std::is_nothrow_constructible<T, Args...>::value, специализация void согласно [SWS_CORE_00843] предоставляет безоговорочную гарантию noexcept и безопасности относительно исключений.

Функция-член Err() const & специализации класса ara::core::Result<void, E> позволяет синхронно запросить возможно содержащееся состояние ошибки ([SWS_CORE_00868]). Она объявляется через заголовочный файл ara/core/result.h и не требует входных параметров при вызове ([SWS_CORE_00868]). В качестве возвращаемого значения функция возвращает ara::core::Optional<E>, содержащее конкретное значение ошибки, если объект представляет ошибку ([SWS_CORE_00868]).

В отношении параллелизма и граничных условий операция явно специфицирована как thread-safe ([SWS_CORE_00868]). В части безопасности относительно исключений метод считается условно безопасным относительно исключений (conditionally exception safe) ([SWS_CORE_00868]). При этом гарантия noexcept действует тогда и только тогда, когда выполнено std::is_nothrow_constructible<Optional<E>, const E&>::value ([SWS_CORE_00868]).

В совокупности интерфейсов перегрузка для rvalue Err() && ([SWS_CORE_00869]) дополняет данную функцию внутри ara::core::Result<void, E>. Сопоставимые пары перегрузок для lvalue и rvalue доступны также для первичного шаблона ara::core::Result<T, E> ([SWS_CORE_00772], [SWS_CORE_00773]) и для специализации по ссылкам ara::core::Result<T&, E> ([SWS_CORE_00931], [SWS_CORE_00932]).

Функция-член Err() && специализации ara::core::Result< void, E > извлекает возможную ошибку и возвращает её как ara::core::Optional< E > [SWS_CORE_00869]. Она подключена через заголовочный файл ara/core/result.h [SWS_CORE_00869].

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

• Контекст вызова и параметры: функция не принимает параметров и в качестве rvalue-квалифицированного метода связывается исключительно с rvalue-экземплярами ara::core::Result< void, E > [SWS_CORE_00869]. Интерпретация: благодаря семантике rvalue (&&) объект ошибки при вызове, вероятно, перемещается в возвращаемый Optional. Вопрос Q-b5a0098f77686ca6 (открытый)
• Возвращаемое значение: результирующий ara::core::Optional< E > содержит значение ошибки, если таковое присутствует в объекте [SWS_CORE_00869].
• Безопасность относительно исключений и многопоточность: операция классифицирована как условно безопасная относительно исключений (conditionally exception safe) и не выбрасывает исключений, если выполнено std::is_nothrow_constructible< Optional< E >, E && >::value [SWS_CORE_00869]. Кроме того, функция специфицирована как потокобезопасная (thread-safe) [SWS_CORE_00869].

Во взаимодействии интерфейсов этот rvalue-вариант дополняет соответствующую lvalue-перегрузку Err() const & той же специализации [SWS_CORE_00868]. Аналогичные пары методов для lvalue и rvalue существуют для первичного шаблона ara::core::Result [SWS_CORE_00772], [SWS_CORE_00773], а также для специализации по ссылкам ara::core::Result< T &, E > [SWS_CORE_00931], [SWS_CORE_00932].

Шаблонная функция-член ErrorOr специализации ara::core::Result<void, E> служит для синхронного получения содержащейся ошибки или альтернативной стандартной ошибки согласно [SWS_CORE_00863]. Если экземпляр уже содержит значение ошибки типа E, оно возвращается без изменений; в противном случае переданный параметр defaultError с помощью static_cast преобразуется в тип ошибки E и возвращается [SWS_CORE_00863].

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

• Безопасность относительно исключений: вызов является условно безопасным относительно исключений (conditionally exception safe) и объявлен как noexcept при условии, что как конструктор копирования E, так и конструирование E из типа универсальной ссылки G&& не генерируют исключений (std::is_nothrow_copy_constructible<E>::value && std::is_nothrow_constructible<E, G&&>::value) [SWS_CORE_00863].
• Потокобезопасность: операция специфицирована как потокобезопасная (thread-safe) [SWS_CORE_00863]. Поскольку речь идёт о перегрузке для константной lvalue-ссылки (const &), одновременный доступ для чтения к одному и тому же экземпляру, по-видимому, безопасен. Вопрос Q-f95402c2e79ef590 (открытый)
• Заголовочный файл: функция предоставляется через заголовочный файл #include "ara/core/result.h" [SWS_CORE_00863].

Во взаимодействии внутри ara::core::Result сущность [SWS_CORE_00863] образует lvalue-константный аналог для rvalue-перегрузки [SWS_CORE_00864] для результатов типа void, в которой ошибка передаётся через std::move. Эквивалентные перегрузки существуют для первичного шаблона класса Result<T, E> через [SWS_CORE_00763] и [SWS_CORE_00764], а также для ссылочных типов Result<T &, E> через [SWS_CORE_00935] и [SWS_CORE_00936].

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

Функция-член ErrorOr специализации ara::core::Result<void, E> служит для синхронного считывания ошибки из rvalue-экземпляра ([SWS_CORE_00864]). Если метод вызывается и объект Result содержит ошибку, она перемещается с помощью std::move в возвращаемое значение типа E. Если же имеется успешный результат, переданный аргумент defaultError преобразуется с помощью static_cast в E и возвращается ([SWS_CORE_00864]).

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

Функция сама по себе не инициирует классических сообщений об ошибках AUTOSAR, таких как DET или DEM. В отношении обработки исключений ErrorOr является условно безопасной относительно исключений (conditionally exception safe). Она защищена выражением noexcept, если тип ошибки E перемещаем без исключений (std::is_nothrow_move_constructible<E>::value) и E может быть сконструирован без исключений из универсального ссылочного типа G&& стандартной ошибки ([SWS_CORE_00864]).

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

Метод специфицирован как thread-safe ([SWS_CORE_00864]). Из-за rvalue-ref-квалификатора && вызов предполагает, что объект Result передаётся как rvalue.

В модуле core этот rvalue-вариант входит в состав группы с другими реализациями:

• Для ara::core::Result<void, E> в качестве lvalue-аналога существует перегрузка const & [SWS_CORE_00863], которая копирует ошибку вместо перемещения.
• Для результатов-значений и ссылочных результатов специализации ara::core::Result<T, E> ([SWS_CORE_00763], [SWS_CORE_00764]) и ara::core::Result<T&, E> ([SWS_CORE_00935], [SWS_CORE_00936]) предоставляют ту же дуальную структуру сигнатур для семантики копирования и перемещения.

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

Статическая функция FromError входит в состав специализации шаблона ara::core::Result<void, E> и подключается через заголовочный файл ara/core/result.h [SWS_CORE_00834]. Она служит синхронным фабричным методом для конструирования нового Result из уже существующего объекта ошибки [SWS_CORE_00834].

• Параметр: входной параметр e принимает ошибку в виде константной lvalue-ссылки (const E &) [SWS_CORE_00834].
• Возвращаемое значение: возвращает экземпляр Result, содержащий переданную ошибку e [SWS_CORE_00834].

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

Спецификация не определяет конкретных кодов ошибок и не предусматривает сообщений в DET или DEM [SWS_CORE_00834]. Функция является условно исключение-безопасной (conditionally exception safe): она гарантированно является noexcept тогда и только тогда, когда тип ошибки E допускает невыбрасывающее копирование (std::is_nothrow_copy_constructible<E>::value) [SWS_CORE_00834].

Параллелизм

Вызов классифицирован как thread-safe [SWS_CORE_00834]. Интерпретация: потокобезопасность, вероятно, касается внутреннего процесса создания объекта, однако предполагает, что исходный объект e, на который указывает ссылка, не изменяется другими потоками во время процесса копирования. Вопрос Q-639cbb5cf8a64a0c (открытый)

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

Внутри специализации ara::core::Result<void, E> эту функцию дополняют перегрузки для rvalue-ссылок (E&&) [SWS_CORE_00835], а также для конструирования на месте (in-place) через пакет параметров [SWS_CORE_00836]; обе они, в отличие от неё, объявлены как not thread-safe. Соответствующие перегрузки существуют также для не полностью специализированного типа ara::core::Result ([SWS_CORE_00734], [SWS_CORE_00735], [SWS_CORE_00736]) и специализаций для ссылок ([SWS_CORE_00905], [SWS_CORE_00906], [SWS_CORE_00907]).

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

Статическая функция FromError синхронно создаёт новый экземпляр ara::core::Result<void, E> из переданного как rvalue объекта ошибки e [SWS_CORE_00835]. Функция определена в заголовке ara/core/result.h и возвращает ara::core::Result, содержащий значение ошибки [SWS_CORE_00835].

Обработка ошибок и параллелизм

Операция обеспечивает условную безопасность исключений (conditionally exception safe): она гарантирует отсутствие исключений через noexcept, если тип ошибки E имеет невыбрасывающий конструктор перемещения (std::is_nothrow_move_constructible<E>::value) [SWS_CORE_00835]. Функция классифицирована как непотокобезопасная (not thread-safe) [SWS_CORE_00835]. Интерпретация: вероятно, это означает, что перемещаемый rvalue-объект должен быть защищён от параллельного доступа из других потоков. Вопрос Q-be29e8c3a7412b7a (открытый)

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

Внутри специализации ara::core::Result<void, E> эта перегрузка представляет собой move-аналог функции копирования lvalue [SWS_CORE_00834] и конструирования на месте через пакеты параметров [SWS_CORE_00836]. Сопоставимые rvalue-перегрузки существуют в модуле core также для типов значений [SWS_CORE_00735] и ссылок [SWS_CORE_00906], дополненные соответствующими lvalue- ([SWS_CORE_00734], [SWS_CORE_00905]) и in-place-вариантами ([SWS_CORE_00736], [SWS_CORE_00907]).

Статическая шаблонная функция FromError согласно [SWS_CORE_00836] служит для того, чтобы внутри специализации ara::core::Result<void, E> создавать содержащий ошибку объект Result, экземпляр ошибки которого типа E конструируется непосредственно на месте («in-place») из переданных аргументов args. Функция принимает участие в разрешении перегрузки только в том случае, если std::is_constructible<E, Args&&...>::value истинно, первый тип распакованного пакета параметров не соответствует E и не является специализацией Result [SWS_CORE_00836].

В отношении безопасности исключений функция специфицирована как условно исключение-безопасная («conditionally exception safe»): она объявлена с noexcept(std::is_nothrow_constructible<E, Args...>::value) [SWS_CORE_00836]. Что касается параллелизма, вызов считается непотокобезопасным («not thread-safe») [SWS_CORE_00836].

Во взаимодействии с другими функциями класса этот метод дополняет перегрузки для создания из уже существующих lvalue- ([SWS_CORE_00834]) или rvalue-объектов ошибки ([SWS_CORE_00835]). Интерпретация: ограничения SFINAE в отношении E и Result, вероятно, обеспечивают, чтобы при передаче уже созданных ошибок или экземпляров Result преимущественно выбирались соответствующие операторы копирования или перемещения и исключалась неоднозначность. Вопрос Q-2796f954bcaececa (открытый) Аналогичные in-place-фабричные функции существуют для обобщённого типа Result ([SWS_CORE_00736]), а также для ссылочных типов в Result<T&, E> ([SWS_CORE_00907]).

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

Статическая функция-член FromValue() служит для создания успешного объекта ara::core::Result для специализации шаблона ara::core::Result<void, E> [SWS_CORE_00831]. Поскольку тип результата void не передает полезных данных, функция не принимает входных параметров. Вызов выполняется синхронно и возвращает Result, представляющий значение void [SWS_CORE_00831]. Объявление находится в заголовочном файле ara/core/result.h [SWS_CORE_00831].

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

Функция снабжена спецификацией noexcept и классифицирована как полностью безопасная относительно исключений (exception safe) [SWS_CORE_00831]. Поскольку FromValue() по определению представляет успешную операцию, она не создает ошибочных состояний и не возвращает кодов ошибок. Специфические сообщения об ошибках через DET или DEM для этого вызова не определены.

Параллелизм

Согласно спецификации функция классифицирована как потокобезопасная (thread-safe) [SWS_CORE_00831]. Ее можно вызывать параллельно из нескольких потоков без дополнительных мер синхронизации.

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

Сигнатура без параметров предусмотрена исключительно для Result<void, E> [SWS_CORE_00831]. Она отличается от перегрузок, создающих значения:

• Для типов значений Result<T, E> существуют варианты для lvalue [SWS_CORE_00731], rvalue [SWS_CORE_00732], а также конструирования на месте (in-place) [SWS_CORE_00733].
• Для ссылочных типов Result<T&, E> FromValue привязывается к lvalue-ссылке [SWS_CORE_00904].

Функция-член Resolve класса шаблона ara::core::Result<void, E> служит для обработки ошибок в рамках обобщенного программирования [SWS_CORE_00867]. Если экземпляр Result содержит обычное значение, вызов не выполняет никаких операций [SWS_CORE_00867]. Если же экземпляр содержит ошибку, вызывается переданный в качестве параметра callable f [SWS_CORE_00867].

Переданный callable f должен быть совместим с сигнатурой функции void f(const E&), где E представляет собой тип ошибки [SWS_CORE_00867]. Сама функция Resolve не имеет возвращаемого значения (void) [SWS_CORE_00867]. Что касается безопасности выполнения, функция специфицирована как небезопасная относительно исключений («not exception safe») [SWS_CORE_00867]. Ее потокобезопасность является условной и напрямую зависит от потокобезопасности переданного callable f [SWS_CORE_00867].

В общей системе эта специализация отличается от обычных функций Resolve для типов значений в ara::core::Result<T, E> [SWS_CORE_00767] и ссылочных типов в ara::core::Result<T&, E> [SWS_CORE_00939], [SWS_CORE_00940]: в то время как те варианты возвращают содержащееся значение или результат вызова callable, перегрузка void без возвращаемого значения существует исключительно как обобщенный строительный блок для унификации вызовов интерфейса [SWS_CORE_00867].

Функция-член Swap синхронно обменивает содержимое текущего экземпляра с переданной ссылкой other [SWS_CORE_00845]. Она относится к области действия специализации ara::core::Result<void, E> из заголовочного файла ara/core/result.h и не имеет возвращаемого значения [SWS_CORE_00845].

В отношении обработки ошибок операция классифицирована как условно безопасная относительно исключений (conditionally exception safe) [SWS_CORE_00845]. Гарантия noexcept действует тогда и только тогда, когда тип ошибки E является как noexcept-move-конструируемым (std::is_nothrow_move_constructible<E>::value), так и noexcept-move-присваиваемым (std::is_nothrow_move_assignable<E>::value) [SWS_CORE_00845]. Специфические коды ошибок или уведомления в DET либо DEM для этого вызова не предусмотрены [SWS_CORE_00845].

Касательно многопоточности Swap явно специфицирована как непотокобезопасная (not thread-safe) [SWS_CORE_00845]. Поэтому параллельный доступ к одним и тем же экземплярам без внешней синхронизации, вероятно, приведет к гонкам данных. Вопрос Q-a8d4f130648765df (открытый)

При взаимодействии внутри ara::core метод формирует основу для свободной шаблонной функции ara::core::swap, условие noexcept которой напрямую привязано к функции-члену [SWS_CORE_00796]. Сопоставимые операции обмена существуют для обобщенного типа ara::core::Result<T, E> [SWS_CORE_00745], ссылочной специализации ara::core::Result<T&, E> [SWS_CORE_00917], а также для объектов Promise [SWS_CORE_00352] [SWS_CORE_06352].

Функция-член ValueOr специализации ara::core::Result<void, E> служит главным образом для упрощения шаблонов обобщенного программирования и при выполнении не производит никаких действий ([SWS_CORE_00861]). Предоставляемый через заголовок ara/core/result.h метод синхронно принимает параметр defaultValue типа пересылки U&& и не возвращает значения (void) ([SWS_CORE_00861]).

В отношении многопоточности и поведения при исключениях функция-член специфицирована как потокобезопасная (thread-safe) и объявлена с синтаксисом спецификатора noexcept, что гарантирует полную безопасность относительно исключений ([SWS_CORE_00861]). Поскольку проверка состояния ошибки и какие-либо действия отсутствуют, нет ни кодов ошибок, ни сообщений в DET или DEM.

Во взаимодействии с остальными разновидностями Result эта функция дополняет основанные на значениях ([SWS_CORE_00761], [SWS_CORE_00762]) и ссылочные ([SWS_CORE_00933], [SWS_CORE_00934]) перегрузки ValueOr. В то время как те функции возвращают установленное значение или в противном случае выдают переданное замещающее значение после преобразования, данный вариант представляет собой нейтральный аналог для операций без возврата значения ([SWS_CORE_00861]). Интерпретация: переданное значение defaultValue в реализации, вероятно, отбрасывается без использования. Вопрос Q-6097af779219e859 (открытый) Это позволяет разработчикам писать обобщенные алгоритмы шаблонов без специальных ветвлений для Result<void, E>.

Функция-член ValueOrThrow специализации шаблона ara::core::Result<void, E> служит для синхронной проверки результата операции [SWS_CORE_00866]. Поскольку тип значения — void, функция не имеет параметров и не возвращает значения [SWS_CORE_00866]. Объявление предоставляется через заголовочный файл ara/core/result.h [SWS_CORE_00866].

В случае успеха метод завершается штатно; если же присутствует состояние ошибки, он генерирует исключение типа, связанного с содержащейся ошибкой (noexcept(false)) [SWS_CORE_00866]. С точки зрения безопасности исключений операция специфицирована как not exception safe [SWS_CORE_00866].

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

• Функция классифицирована как thread-safe [SWS_CORE_00866].
• Если исключения C++ отключены в инструментарии компилятора, эта функция не участвует в разрешении перегрузки [SWS_CORE_00866].

Во взаимодействии с модулем core эта void-специализация дополняет обобщенные перегрузки ara::core::Result<T, E>, возвращающие ссылки на содержащиеся значения ([SWS_CORE_00766], [SWS_CORE_00769], [SWS_CORE_00778]), а также специализации для ссылочных типов ara::core::Result<T&, E> ([SWS_CORE_00938], [SWS_CORE_00949]).

Шаблонная функция-член CheckError специализации ara::core::Result<void, E> синхронно проверяет, содержит ли текущий экземпляр определенную ошибку [SWS_CORE_00865]. Для этого переданный аргумент error преобразуется с помощью static_cast в тип ошибки E и сравнивается с возвращаемым значением внутреннего состояния ошибки Error() [SWS_CORE_00865]. Вызов осуществляется через заголовок #include "ara/core/result.h" [SWS_CORE_00865].

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

• Параметры и возвращаемое значение: универсальный ссылочный параметр error типа G&& принимает проверяемую ошибку [SWS_CORE_00865]. Функция возвращает true, если экземпляр содержит ошибку, эквивалентную error, и false в противном случае [SWS_CORE_00865].
• Многопоточность и безопасность относительно исключений: операция объявлена как const noexcept, считается безопасной относительно исключений (exception safe) и может безоговорочно вызываться потокобезопасно (thread-safe) [SWS_CORE_00865].

Во взаимодействии с модулем core существуют аналогичные перегрузки CheckError: первичный класс шаблона ara::core::Result предоставляет ту же сигнатуру также потокобезопасно и с безопасностью относительно исключений с noexcept [SWS_CORE_00765]. В отличие от этого специализация для ссылок ara::core::Result<T&, E> хоть и обладает тем же механизмом сравнения и является потокобезопасной, однако явно специфицирована без noexcept как небезопасная относительно исключений (not exception safe) [SWS_CORE_00937].