namespace ara::log

La enumeración ara::log::ClientState representa el estado de conexión actual de un cliente externo con el backend de DLT [SWS_LOG_00098]. Se basa en el tipo de datos std::int8_t y se incluye a través del archivo de cabecera #include "ara/log/common.h" o del archivo de cabecera de reenvío #include "ara/log/log_fwd.h" [SWS_LOG_00098].

Estados y semántica

La enumeración define tres estados de conexión discretos [SWS_LOG_00098]:

• kUnknown (-1): El backend de DLT aún no está listo para operar; el estado de conexión real no se puede determinar en este momento [SWS_LOG_00098].
• kNotConnected: No se detectó ningún cliente externo [SWS_LOG_00098].
• kConnected: Un cliente remoto está conectado correctamente [SWS_LOG_00098].

Interacción y concurrencia

La enumeración sirve principalmente como parámetro de transferencia para la retrollamada de función ConnectionStateHandler (definida como std::function<void(ClientState)>), que se registra a través de ara::log::RegisterConnectionStateHandler [SWS_LOG_00265]. Este manejador está declarado como seguro para subprocesos [SWS_LOG_00265]. Interpretación: Los manejadores registrados probablemente se llamen de manera asíncrona tan pronto como el backend de DLT detecte cambios de estado del cliente externo. Pregunta Q-b78ef73772a658a2 (abierta)

El alias de tipo ConnectionStateHandler especifica la signatura para funciones de callback destinadas a la monitorización del estado de conexión en el módulo log [SWS_LOG_00265]. Está declarado en el espacio de nombres ara::log y requiere la inclusión del archivo de cabecera ara/log/logger.h [SWS_LOG_00265]. Como envoltorio de función std::function<void(ClientState)>, la rutina de callback recibe el estado de conexión producido a través del parámetro de tipo ClientState y no proporciona ningún valor de retorno [SWS_LOG_00265].

El uso se realiza a través de la función de registro RegisterConnectionStateHandler [SWS_LOG_00205]. Para la interacción y el ciclo de vida del manejador se aplican las siguientes prescripciones:

• Momento de llamada: la función de callback registrada se invoca cada vez que cambia el estado de conexión del cliente [SWS_LOG_00205].
• Exclusividad: solo puede haber un único manejador registrado activamente en cualquier momento [SWS_LOG_00205]. Si ya se había registrado un callback previamente, la nueva función pasada lo reemplaza por completo, de modo que en adelante se invocará exclusivamente el nuevo manejador [SWS_LOG_00205].
• Seguridad frente a excepciones: la función de registro RegisterConnectionStateHandler está especificada con noexcept, de manera que la transferencia del callback de función se realiza con seguridad frente a excepciones [SWS_LOG_00205].

En cuanto a la concurrencia, el elemento de especificación está marcado como seguro para hilos [SWS_LOG_00265]. Interpretación: dado que los cambios de estado se señalan de manera potencialmente asíncrona a través de la infraestructura de logging, es de suponer que la lógica de aplicación implementada en el manejador deba diseñarse como reentrante y no ejecutar operaciones bloqueantes, con el fin de no obstaculizar el contexto de comunicación. Pregunta Q-ca507d992cc31284 (abierta)

usar

La función CreateLogger en el espacio de nombres ara::log sirve para crear y registrar un objeto Logger que administra el contexto respectivo dentro del marco de registro (logging framework) [SWS_LOG_00021]. Al realizar la llamada, se pasan el identificador de contexto ctxId, la descripción textual ctxDescription y el nivel de registro predeterminado ctxDefLogLevel [SWS_LOG_00021]. Si no hay ningún modelo disponible, el framework redirige las salidas por defecto a la consola como destino (sink) [SWS_LOG_00021].

La función devuelve una referencia Logger & a la instancia administrada internamente. La propiedad (ownership) permanece en este caso completamente en el framework de registro [SWS_LOG_00021].

Concurrencia y seguridad de ejecución

La interfaz está declarada como noexcept y especificada tanto como segura frente a excepciones (exception safe) como segura para subprocesos (thread-safe) [SWS_LOG_00021]. Por lo tanto, se puede llamar de forma segura desde múltiples subprocesos concurrentes.

Interacción y alternativas

Para diferentes enfoques de configuración, están disponibles interfaces relacionadas:

• Una sobrecarga alternativa permite la instanciación únicamente a través de ctxId y ctxDescription [SWS_LOG_00263], donde se utiliza implícitamente Warning como nivel de registro predeterminado [SWS_LOG_00021].
• Además, se puede derivar un Logger basado en modelos a partir del manifiesto mediante un ara::core::InstanceSpecifier [SWS_LOG_00256]. En este proceso, la plataforma comprueba errores como InstanceSpecifierMappingIntegrityViolation o PortInterfaceMappingViolation [SWS_LOG_00256].

La función síncrona CreateLogger crea o devuelve una referencia a un objeto Logger administrado internamente basándose en los datos del modelo del manifiesto [SWS_LOG_00256]. Como parámetro de llamada se utiliza una referencia a un ara::core::InstanceSpecifier, el cual identifica el elemento de modelo deseado en el contexto del proceso en ejecución [SWS_LOG_00256].

La función está declarada como noexcept, se considera segura frente a excepciones (exception safe) y está especificada como segura para subprocesos, de modo que las llamadas pueden realizarse de forma reentrante y concurrente [SWS_LOG_00256]. Para configuraciones erróneas o contextos de modelo no válidos, la especificación define varias violaciones (Violations) [SWS_LOG_00256]:

• InstanceSpecifierMappingIntegrityViolation: Se produce cuando el InstanceSpecifier no se puede resolver en el contexto del ejecutable o hace referencia a un elemento distinto de un PortPrototype [SWS_LOG_00256].
• PortInterfaceMappingViolation: Se activa en caso de que el tipo de asignación (mapping) no coincida con el tipo esperado de la interfaz de puerto [SWS_LOG_00256].
• ProcessMappingViolation: Se aplica cuando, aunque existe un InstanceRef adecuado, ningún proceso modelado coincide con el proceso en tiempo de ejecución [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation: Señaliza que se llamó a un constructor en el framework con un identificador que ya se está utilizando en este proceso [SWS_LOG_00256].

En comparación con las sobrecargas [SWS_LOG_00021] y [SWS_LOG_00263], que inicializan registradores mediante programación a través de ID de contexto y cadenas de descripción y, a falta de modelo, utilizan por defecto la consola como destino (sink), la configuración aquí es totalmente impulsada por el manifiesto. En todas las variantes, la propiedad de la instancia permanece dentro del framework de registro [SWS_LOG_00263].

La función CreateLogger en el espacio de nombres ara::log ([SWS_LOG_00263]) sirve para crear y registrar un objeto Logger vinculado al contexto dentro del framework de registro de AUTOSAR Adaptive.

usar

A través del archivo de cabecera ara/log/logger.h, la función acepta el identificador de contexto ctxId y la descripción detallada ctxDescription, cada uno como tipo ara::core::StringView [SWS_LOG_00263]. Como valor de retorno, la llamada devuelve una referencia Logger & a la instancia administrada internamente del objeto Logger creado [SWS_LOG_00263]. La propiedad (Ownership) de esta instancia permanece permanentemente en el framework de registro y no se transfiere al llamador [SWS_LOG_00263]. Si no hay ningún modelo disponible en el sistema, la consola actúa de forma predeterminada como destino (Sink) para todas las salidas de registro [SWS_LOG_00263].

Tratamiento de errores y concurrencia

Para la llamada no se definen códigos de error específicos y no se lanzan excepciones de C++, ya que la función está especificada con noexcept e identificada como segura frente a excepciones (exception safe) [SWS_LOG_00263]. En relación con la concurrencia, CreateLogger es segura para subprocesos (thread-safe), de modo que la función puede llamarse de forma concurrente desde múltiples hilos sin sincronización externa [SWS_LOG_00263].

Interacción

El framework de logging ofrece sobrecargas estrechamente relacionadas: además de esta signatura de dos parámetros, una sobrecarga permite la configuración adicional de un nivel de log predeterminado mediante ctxDefLogLevel ([SWS_LOG_00021]). Otra signatura permite la creación de un objeto Logger a través de un ara::core::InstanceSpecifier directamente desde el manifiesto ([SWS_LOG_00256]).

usar

La función ara::log::EngFloatMax() del archivo de cabecera ara/log/logger.h crea de forma sincrónica una instancia del tipo Format [SWS_LOG_00220]. El objeto devuelto contiene la indicación de formato Fmt::kEngFloat para la salida de números en coma flotante en notación de ingeniería, así como una precisión suficiente para una conversión completa de ida y vuelta («full round-trip safety») [SWS_LOG_00220]. La función no espera parámetros.

Manejo de errores

La función cuenta con el especificador noexcept y está definida como segura frente a excepciones (exception safe) [SWS_LOG_00220]. No existen códigos de error específicos y no se lanzan excepciones ni se transmiten errores a instancias de diagnóstico o notificación de errores. La llamada no falla en funcionamiento regular.

Concurrencia y restricciones

La especificación clasifica la función como segura para hilos (thread-safe) [SWS_LOG_00220]. Gracias a la calificación como constexpr, la llamada puede evaluarse ya en tiempo de compilación. Interpretación: Dado que la especificación no define condiciones previas y la función carece de estado, es probable que no existan restricciones respecto al contexto de llamada ni dependencias de una inicialización previa de la infraestructura de registro (logging). Pregunta Q-90c67bfad5b19641 (abierta)

La función auxiliar HexFloat sirve para la creación de un objeto de formateo para números de coma flotante destinados a la salida en formato hexadecimal según [SWS_LOG_00221]. Instancia un objeto del tipo Format provisto de la indicación de formato Fmt::kHexFloat y de una precisión predefinida.

Uso y parámetros

La función está disponible en el espacio de nombres ara::log a través del encabezado #include "ara/log/logger.h" [SWS_LOG_00221]:

• Parámetros: como parámetro de entrada se pasa precision de tipo std::uint16_t, el cual define la precisión de salida deseada [SWS_LOG_00221].
• Valor de retorno: un objeto Format inicializado con el prefijo Fmt::kHexFloat establecido [SWS_LOG_00221].
• Ejecución: gracias a su designación como constexpr, la construcción de la indicación de formato puede llevarse a cabo de forma síncrona en tiempo de ejecución o bien ya en tiempo de compilación [SWS_LOG_00221].

Tratamiento de errores y concurrencia

La firma está declarada con noexcept y se considera totalmente segura contra excepciones (exception safe) [SWS_LOG_00221]. No se generan códigos de error ni mensajes de error específicos. La función está especificada como segura para hilos (thread-safe) y puede invocarse en paralelo desde cualquier contexto sin sobrecarga de sincronización [SWS_LOG_00221].

La función HexFloatMax en el espacio de nombres ara::log sirve para crear una instancia de Format para la salida formateada de valores en coma flotante [SWS_LOG_00222]. Se proporciona a través del archivo de cabecera #include "ara/log/logger.h" y no acepta parámetros de llamada [SWS_LOG_00222]. Como valor de retorno sincrónico se entrega una instancia de Format, la cual está provista de la indicación de formato Fmt::kHexFloat y presenta una precisión que garantiza una seguridad total frente a conversiones de ida y vuelta (round-trip) [SWS_LOG_00222].

La firma está declarada como constexpr y noexcept [SWS_LOG_00222]. Esto permite la evaluación ya en tiempo de compilación y garantiza que no se puedan producir excepciones durante la ejecución. Para esta llamada no se especifican estados de error particulares, códigos de error ni mecanismos de tratamiento de errores, ya que la creación del objeto de formato se realiza siempre sin errores.

En cuanto al contexto de llamada y a la concurrencia, la función está especificada como segura frente a excepciones (exception safe) y segura para hilos (thread-safe) [SWS_LOG_00222]. No está sujeta a restricciones de llamada secuenciales y puede invocarse de forma segura y concurrente desde cualquier hilo sin sincronización adicional.

usar

La función ara::log::Oct() sirve como función auxiliar para crear un objeto de formateo para salidas de registro en el sistema octal [SWS_LOG_00213]. No acepta parámetros y devuelve de forma síncrona un objeto de tipo Format configurado con la indicación de formateo Fmt::kOct y una precisión estándar [SWS_LOG_00213]. Dado que la función está declarada como constexpr, la instanciación ya puede tener lugar en tiempo de compilación. Interpretación: El objeto Format devuelto estaría previsto principalmente para controlar el formateo de enteros en flujos de registro. Pregunta Q-3f4fe5ac42de16cb (abierta)

Manejo de errores

La función garantiza seguridad frente a excepciones (exception safe) y está declarada explícitamente como noexcept [SWS_LOG_00213]. Queda excluida la aparición de errores en tiempo de ejecución o el lanzamiento de excepciones. No existen códigos de error específicos y no se emiten notificaciones a DET ni a DEM.

Concurrencia y restricciones

La llamada a Oct() es plenamente segura para subprocesos (thread-safe) [SWS_LOG_00213]. Dado que no se modifican estados compartidos, la función no está sujeta a restricciones relativas a la reentrancia o al contexto de llamada y puede llamarse en paralelo desde varios subprocesos.

Interacción

La función está definida en el espacio de nombres ara::log y se proporciona mediante el archivo de encabezado #include "ara/log/logger.h" [SWS_LOG_00213]. Además de esta variante sin parámetros, existe la sobrecarga Oct(std::uint16_t precision), mediante la cual se puede definir una precisión numérica distinta [SWS_LOG_00214].

usar

La función auxiliar ara::log::Oct se proporciona a través del archivo de cabecera #include "ara/log/logger.h" en el espacio de nombres ara::log [SWS_LOG_00214]. Sirve para crear una instancia del tipo Format con la indicación de formato Fmt::kOct, así como una precisión predefinida [SWS_LOG_00214]. Como parámetro de entrada, la función recibe el valor entero sin signo de 16 bits precision, el cual define la precisión que se aplicará [SWS_LOG_00214]. La función opera de forma síncrona y devuelve inmediatamente la instancia de Format creada [SWS_LOG_00214].

Tratamiento de errores y concurrencia

La función está declarada como noexcept y especificada expresamente como segura contra excepciones (exception safe) [SWS_LOG_00214]. No existen códigos de error específicos ni notificaciones mediante DET o DEM en caso de error. En cuanto al contexto de llamada y la concurrencia, la función está clasificada como segura para hilos (thread-safe) [SWS_LOG_00214]. Puesto que además está definida como constexpr, la creación de la instrucción de formateo puede realizarse ya en tiempo de compilación [SWS_LOG_00214].

Interacción

Dentro del módulo log, la función complementa la sobrecarga afín Oct() [SWS_LOG_00213]. Mientras que la variante sin parámetros construye una instancia de Format con precisión predeterminada (default precision) [SWS_LOG_00213], la presente función permite la configuración explícita de una precisión personalizada por el usuario para el formateo octal [SWS_LOG_00214].

La función RegisterConnectionStateHandler en el espacio de nombres ara::log sirve para registrar una función de retrollamada por parte de la aplicación que se invoca con cada cambio en el estado de conexión [SWS_LOG_00205]. Está declarada en la cabecera ara/log/logger.h [SWS_LOG_00205]. Como parámetro se pasa un objeto de función callback de tipo ConnectionStateHandler [SWS_LOG_00205], el cual está especificado como alias de tipo para std::function<void(ClientState)> [SWS_LOG_00265]. No existe ningún valor de retorno (void) [SWS_LOG_00205].

En cuanto al ciclo de vida y al orden, se estipula que en cualquier momento solo puede haber instalado un único manejador de estado [SWS_LOG_00205]. Si ya se había registrado previamente una función de retrollamada, cada nueva llamada sobrescribe completamente la instancia existente, de modo que a partir de ese instante se ejecutará exclusivamente el último manejador transferido [SWS_LOG_00205].

La función está declarada con noexcept y especificada como segura frente a excepciones («exception safe») [SWS_LOG_00205]. En la especificación no se definen códigos de error, valores de error ni notificaciones a monitores de diagnóstico o de errores específicos [SWS_LOG_00205].

En relación con la concurrencia, RegisterConnectionStateHandler está catalogada expresamente como no segura para hilos («not thread-safe») [SWS_LOG_00205]. Por lo tanto, el registro no debe invocarse de forma concurrente sin protección desde varios hilos y debería realizarse idealmente durante la fase de inicialización. Por contra, el alias de tipo ConnectionStateHandler está especificado como seguro para hilos [SWS_LOG_00265]. Interpretación: De ello cabe deducir que la retrollamada registrada podría ser invocada por el entorno de ejecución interno de logging potencialmente desde contextos concurrentes al producirse transiciones de estado. Pregunta Q-59eae7980ba48666 (abierta)