пространство имён ara::log

Перечисление ara::log::ClientState отражает текущее состояние подключения внешнего клиента к бэкенду DLT [SWS_LOG_00098]. Оно базируется на типе данных std::int8_t и подключается через заголовочный файл #include "ara/log/common.h" или заголовочный файл предварительного объявления #include "ara/log/log_fwd.h" [SWS_LOG_00098].

Состояния и семантика

Перечисление определяет три дискретных состояния подключения [SWS_LOG_00098]:

• kUnknown (-1): бэкенд DLT еще не готов к работе; фактическое состояние подключения на данный момент не может быть определено [SWS_LOG_00098].
• kNotConnected: внешний клиент не обнаружен [SWS_LOG_00098].
• kConnected: удаленный клиент успешно подключен [SWS_LOG_00098].

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

Перечисление служит в первую очередь параметром передачи для функции обратного вызова ConnectionStateHandler (определенной как std::function<void(ClientState)>), которая регистрируется через ara::log::RegisterConnectionStateHandler [SWS_LOG_00265]. Этот обработчик объявлен как потокобезопасный [SWS_LOG_00265]. Интерпретация: зарегистрированные обработчики, вероятно, вызываются асинхронно, как только бэкенд DLT обнаруживает смену состояния внешнего клиента. Вопрос Q-b78ef73772a658a2 (открытый)

Псевдоним типа ConnectionStateHandler специфицирует сигнатуру для функций обратного вызова для отслеживания состояния соединения в модуле log [SWS_LOG_00265]. Он объявлен в пространстве имен ara::log и требует подключения заголовочного файла ara/log/logger.h [SWS_LOG_00265]. В качестве функциональной оболочки std::function<void(ClientState)> процедура обратного вызова принимает наступившее состояние соединения через параметр типа ClientState и не возвращает значения [SWS_LOG_00265].

Использование осуществляется через функцию регистрации RegisterConnectionStateHandler [SWS_LOG_00205]. Для взаимодействия и жизненного цикла обработчика действуют следующие предписания:

• Момент вызова: зарегистрированная функция обратного вызова вызывается каждый раз при изменении состояния соединения клиента [SWS_LOG_00205].
• Исключительность: в любой момент времени может быть активно зарегистрирован только один обработчик [SWS_LOG_00205]. Если ранее уже был зарегистрирован callback, вновь переданная функция полностью заменяет его, так что в дальнейшем вызывается исключительно новый обработчик [SWS_LOG_00205].
• Безопасность исключений: функция регистрации RegisterConnectionStateHandler специфицирована с noexcept, поэтому передача функционального callback выполняется безопасно относительно исключений [SWS_LOG_00205].

С точки зрения параллелизма элемент спецификации помечен как потокобезопасный [SWS_LOG_00265]. Интерпретация: поскольку изменения состояния потенциально сигнализируются инфраструктурой логирования асинхронно, предоставляемая в обработчике логика приложения, вероятно, должна быть спроектирована реентерабельной и не должна выполнять блокирующих операций, чтобы не препятствовать контексту связи. Вопрос Q-ca507d992cc31284 (открытый)

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

Функция CreateLogger в пространстве имен ara::log служит для создания и регистрации объекта Logger, который управляет соответствующим контекстом внутри фреймворка логирования [SWS_LOG_00021]. При вызове передаются идентификатор контекста ctxId, текстовое описание ctxDescription, а также стандартный уровень логирования ctxDefLogLevel [SWS_LOG_00021]. Если модель недоступна, фреймворк по умолчанию перенаправляет вывод на консоль в качестве приемника [SWS_LOG_00021].

Функция возвращает ссылку Logger & на внутренне управляемый экземпляр. При этом владение (ownership) полностью сохраняется за фреймворком логирования [SWS_LOG_00021].

Параллелизм и надёжность выполнения

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

Взаимодействие и альтернативы

Для различных подходов к конфигурации доступны родственные интерфейсы:

• Альтернативная перегрузка позволяет выполнять инстанцирование только через ctxId и ctxDescription [SWS_LOG_00263], причем в качестве стандартного уровня логирования неявно используется Warning [SWS_LOG_00021].
• Кроме того, Logger может быть получен на основе модели через ara::core::InstanceSpecifier из манифеста [SWS_LOG_00256]. При этом платформа проверяет такие ошибки, как InstanceSpecifierMappingIntegrityViolation или PortInterfaceMappingViolation [SWS_LOG_00256].

Синхронная функция CreateLogger создает или возвращает ссылку на внутренне управляемый объект Logger на основе данных модели манифеста [SWS_LOG_00256]. В качестве параметра вызова служит ссылка на ara::core::InstanceSpecifier, который идентифицирует требуемый элемент модели в контексте запущенного процесса [SWS_LOG_00256].

Функция объявлена как noexcept, считается безопасной к исключениям (exception safe) и специфицирована как потокобезопасная, благодаря чему вызовы могут выполняться реентерабельно и параллельно [SWS_LOG_00256]. Для ошибочных конфигураций или недопустимых контекстов модели спецификация определяет несколько нарушений (violations) [SWS_LOG_00256]:

• InstanceSpecifierMappingIntegrityViolation: возникает, когда InstanceSpecifier в контексте исполняемого файла не может быть разрешен или указывает на элемент, отличный от PortPrototype [SWS_LOG_00256].
• PortInterfaceMappingViolation: инициируется, если тип сопоставления не соответствует ожидаемому типу интерфейса порта [SWS_LOG_00256].
• ProcessMappingViolation: срабатывает, когда подходящий InstanceRef существует, но ни один смоделированный процесс не соответствует процессу времени выполнения [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation: сигнализирует о том, что конструктор во фреймворке был вызван с идентификатором, который уже используется в этом процессе [SWS_LOG_00256].

По сравнению с перегрузками [SWS_LOG_00021] и [SWS_LOG_00263], которые инициализируют логгеры программно через идентификаторы контекста и строки описания и при отсутствии модели по умолчанию используют консоль в качестве приемника, конфигурация здесь осуществляется полностью на основе манифеста. Во всех вариантах владение экземпляром сохраняется за фреймворком логирования [SWS_LOG_00263].

Функция CreateLogger в пространстве имен ara::log ([SWS_LOG_00263]) служит для создания и регистрации привязанного к контексту объекта Logger внутри фреймворка логирования AUTOSAR Adaptive.

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

Через заголовочный файл ara/log/logger.h функция принимает идентификатор контекста ctxId, а также подробное описание ctxDescription, каждое типа ara::core::StringView [SWS_LOG_00263]. В качестве возвращаемого значения вызов возвращает ссылку Logger & на внутренне управляемый экземпляр созданного объекта Logger [SWS_LOG_00263]. Право владения (ownership) этим экземпляром постоянно сохраняется за фреймворком логирования и не передается вызывающей стороне [SWS_LOG_00263]. Если в системе модель недоступна, консоль по умолчанию действует как приемник (sink) для всего вывода логирования [SWS_LOG_00263].

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

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

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

Фреймворк логирования предлагает тесно связанные перегрузки: наряду с этой сигнатурой с двумя параметрами перегрузка позволяет дополнительно настраивать уровень логирования по умолчанию через ctxDefLogLevel ([SWS_LOG_00021]). Еще одна сигнатура обеспечивает создание объекта Logger через ara::core::InstanceSpecifier непосредственно из манифеста ([SWS_LOG_00256]).

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

Функция ara::log::EngFloatMax() из заголовочного файла ara/log/logger.h синхронно создает экземпляр типа Format [SWS_LOG_00220]. Возвращаемый объект содержит указание по форматированию Fmt::kEngFloat для вывода чисел с плавающей запятой в инженерной нотации, а также точность, достаточную для полного прямого и обратного преобразования («full round-trip safety») [SWS_LOG_00220]. Функция не ожидает параметров.

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

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

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

Спецификация обозначает функцию как потокобезопасную (thread-safe) [SWS_LOG_00220]. Благодаря обозначению как constexpr вызов может вычисляться уже во время компиляции. Интерпретация: поскольку спецификация не определяет предусловий, а функция не имеет состояния, по-видимому, отсутствуют как ограничения относительно контекста вызова, так и зависимости от предварительной инициализации инфраструктуры логирования. Вопрос Q-90c67bfad5b19641 (открытый)

Вспомогательная функция HexFloat служит для создания объекта форматирования для чисел с плавающей запятой для вывода в шестнадцатеричном формате согласно [SWS_LOG_00221]. Она инстанцирует объект типа Format, снабженный указанием форматирования Fmt::kHexFloat, а также заданной точностью.

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

Функция доступна в пространстве имен ara::log через заголовочный файл #include "ara/log/logger.h" [SWS_LOG_00221]:

• Параметры: в качестве входного параметра передается precision типа std::uint16_t, определяющий желаемую точность вывода [SWS_LOG_00221].
• Возвращаемое значение: инициализированный объект Format с установленным префиксом Fmt::kHexFloat [SWS_LOG_00221].
• Выполнение: благодаря обозначению как constexpr конструирование указания форматирования может происходить синхронно во время выполнения или уже во время компиляции [SWS_LOG_00221].

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

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

Функция HexFloatMax в пространстве имен ara::log служит для создания экземпляра Format для форматированного вывода значений с плавающей запятой [SWS_LOG_00222]. Она предоставляется через заголовочный файл #include "ara/log/logger.h" и не принимает параметров вызова [SWS_LOG_00222]. В качестве синхронного возвращаемого значения предоставляется экземпляр Format, снабженный указанием по форматированию Fmt::kHexFloat и обладающий точностью, обеспечивающей полную гарантию round-trip [SWS_LOG_00222].

Сигнатура объявлена как constexpr, а также noexcept [SWS_LOG_00222]. Это позволяет выполнять вычисление уже во время компиляции и гарантирует, что при выполнении не могут возникнуть исключения. Особые состояния ошибок, коды ошибок или механизмы обработки ошибок для этого вызова не специфицированы, поскольку создание объекта формата всегда выполняется безошибочно.

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

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

Функция ara::log::Oct() служит вспомогательной функцией для создания объекта форматирования для вывода журнала в восьмеричной системе [SWS_LOG_00213]. Она не принимает параметров и синхронно возвращает объект типа Format, сконфигурированный с указанием формата Fmt::kOct, а также стандартной точностью [SWS_LOG_00213]. Поскольку функция объявлена как constexpr, инстанцирование может происходить уже во время компиляции. Интерпретация: возвращаемый объект Format, вероятно, предназначен преимущественно для управления форматированием целых чисел в потоках журнала. Вопрос Q-3f4fe5ac42de16cb (открытый)

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

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

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

Вызов Oct() безоговорочно потокобезопасен (thread-safe) [SWS_LOG_00213]. Поскольку разделяемые состояния не модифицируются, функция не имеет ограничений относительно реентерабельности или контекста вызова и может вызываться параллельно из нескольких потоков.

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

Функция определена в пространстве имен ara::log и предоставляется через заголовочный файл #include "ara/log/logger.h" [SWS_LOG_00213]. Помимо этого варианта без параметров, существует перегрузка Oct(std::uint16_t precision), с помощью которой можно задать иную разрядную точность [SWS_LOG_00214].

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

Вспомогательная функция ara::log::Oct предоставляется через заголовочный файл #include "ara/log/logger.h" в пространстве имен ara::log [SWS_LOG_00214]. Она служит для создания экземпляра типа Format с указанием форматирования Fmt::kOct, а также заданной точностью [SWS_LOG_00214]. В качестве входного параметра функция принимает 16-битное беззнаковое целочисленное значение precision, определяющее применяемую точность [SWS_LOG_00214]. Функция работает синхронно и непосредственно возвращает созданный экземпляр Format [SWS_LOG_00214].

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

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

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

Внутри модуля log функция дополняет родственную перегрузку Oct() [SWS_LOG_00213]. В то время как вариант без параметров конструирует экземпляр Format с точностью по умолчанию (default precision) [SWS_LOG_00213], рассматриваемая функция позволяет явно настроить пользовательскую точность для восьмеричного форматирования [SWS_LOG_00214].

Функция RegisterConnectionStateHandler в пространстве имен ara::log служит для регистрации функции обратного вызова на стороне приложения, которая вызывается при каждом изменении состояния соединения [SWS_LOG_00205]. Она объявлена в заголовке ara/log/logger.h [SWS_LOG_00205]. В качестве параметра передается функциональный объект callback типа ConnectionStateHandler [SWS_LOG_00205], который специфицирован как псевдоним типа для std::function<void(ClientState)> [SWS_LOG_00265]. Возвращаемое значение отсутствует (void) [SWS_LOG_00205].

В отношении жизненного цикла и порядка определено, что в каждый момент времени может быть установлен только один обработчик состояния [SWS_LOG_00205]. Если функция обратного вызова уже была зарегистрирована ранее, каждый повторный вызов полностью перезаписывает существующий экземпляр, так что с этого момента выполняется исключительно последний переданный обработчик [SWS_LOG_00205].

Функция объявлена с noexcept и специфицирована как безопасная относительно исключений («exception safe») [SWS_LOG_00205]. Специфические коды ошибок, значения ошибок или уведомления для мониторов ошибок или диагностики в спецификации не определены [SWS_LOG_00205].

В отношении параллелизма RegisterConnectionStateHandler явно классифицирована как непотокобезопасная («not thread-safe») [SWS_LOG_00205]. Поэтому регистрацию нельзя вызывать незащищенным параллельным образом из нескольких потоков, и ее в идеале следует выполнять на этапе инициализации. В отличие от этого, псевдоним типа ConnectionStateHandler специфицирован как потокобезопасный [SWS_LOG_00265]. Интерпретация: из этого, вероятно, следует, что зарегистрированный обратный вызов может потенциально вызываться внутренней средой выполнения логирования из параллельных контекстов при изменениях состояния. Вопрос Q-59eae7980ba48666 (открытый)