namespace ara::log

The enumeration ara::log::ClientState represents the current connection status of an external client to the DLT backend [SWS_LOG_00098]. It is based on data type std::int8_t and is included via header file #include "ara/log/common.h" or forwarding header #include "ara/log/log_fwd.h" [SWS_LOG_00098].

States and semantics

The enumeration defines three discrete connection states [SWS_LOG_00098]:

• kUnknown (-1): The DLT backend is not yet operational; the actual connection status cannot be determined at this point in time [SWS_LOG_00098].
• kNotConnected: No external client has been detected [SWS_LOG_00098].
• kConnected: A remote client is successfully connected [SWS_LOG_00098].

Interaction and Concurrency

The enumeration serves primarily as a parameter for function callback ConnectionStateHandler (defined as std::function<void(ClientState)>), which is registered via ara::log::RegisterConnectionStateHandler [SWS_LOG_00265]. This handler is declared as thread-safe [SWS_LOG_00265]. Interpretation: Registered handlers are likely called asynchronously as soon as the DLT backend detects state changes of the external client. Question Q-b78ef73772a658a2 (open)

The type alias ConnectionStateHandler specifies the signature for callback functions for monitoring the connection status in module log [SWS_LOG_00265]. It is declared in namespace ara::log and requires including the header file ara/log/logger.h [SWS_LOG_00265]. As a function wrapper std::function<void(ClientState)>, the callback routine accepts the resulting connection state via the parameter of type ClientState and provides no return value [SWS_LOG_00265].

Usage takes place via the registration function RegisterConnectionStateHandler [SWS_LOG_00205]. The following requirements apply to the interaction and lifecycle of the handler:

• Invocation timing: The registered callback function is called every time the client's connection state changes [SWS_LOG_00205].
• Exclusivity: Only a single handler can be actively registered at any given time [SWS_LOG_00205]. If a callback was already registered previously, the newly passed function replaces it completely, so that going forward only the new handler is called [SWS_LOG_00205].
• Exception safety: The registration function RegisterConnectionStateHandler is specified with noexcept, ensuring that passing the function callback is exception safe [SWS_LOG_00205].

Regarding concurrency, the specification element is marked as thread-safe [SWS_LOG_00265]. Interpretation: Since state changes are potentially signaled asynchronously by the logging infrastructure, the application logic provided in the handler is likely required to be designed reentrantly and perform no blocking operations in order not to obstruct the communication context. Question Q-ca507d992cc31284 (open)

use

The function CreateLogger in namespace ara::log serves to create and register a Logger object, which manages the respective context within the logging framework [SWS_LOG_00021]. Upon invocation, context identifier ctxId, textual description ctxDescription, and default log level ctxDefLogLevel are passed [SWS_LOG_00021]. If no model is available, the framework redirects output to the console as a sink by default [SWS_LOG_00021].

The function returns a reference Logger & to the internally managed instance. Ownership remains entirely with the logging framework [SWS_LOG_00021].

Concurrency and Execution Safety

The interface is declared as noexcept and specified as both exception safe and thread-safe [SWS_LOG_00021]. It can thus be safely called from multiple concurrent threads.

Interaction and Alternatives

Related interfaces are available for different configuration approaches:

• An alternative overload allows instantiation using only ctxId and ctxDescription [SWS_LOG_00263], implicitly using Warning as the default log level [SWS_LOG_00021].
• In addition, a Logger can be derived model-based via an ara::core::InstanceSpecifier from the manifest [SWS_LOG_00256]. In doing so, the platform checks for errors such as InstanceSpecifierMappingIntegrityViolation or PortInterfaceMappingViolation [SWS_LOG_00256].

The synchronous function CreateLogger creates or returns a reference to an internally managed Logger object based on the model data of the manifest [SWS_LOG_00256]. A reference to an ara::core::InstanceSpecifier, which identifies the desired model element in the context of the running process, serves as invocation parameter [SWS_LOG_00256].

The function is declared as noexcept, is considered exception safe (exception safe), and is specified as thread-safe so that calls can occur reentrantly and concurrently [SWS_LOG_00256]. For erroneous configurations or invalid model contexts, the specification defines several violations (Violations) [SWS_LOG_00256]:

• InstanceSpecifierMappingIntegrityViolation: Occurs when the InstanceSpecifier cannot be resolved in the context of the executable or refers to an element other than an PortPrototype [SWS_LOG_00256].
• PortInterfaceMappingViolation: Triggered if the mapping type does not correspond to the expected type of the port interface [SWS_LOG_00256].
• ProcessMappingViolation: Takes effect when a matching InstanceRef exists, but no modeled process matches the runtime process [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation: Signals that a constructor in the framework was called with an identifier that is already in use in this process [SWS_LOG_00256].

Compared to overloads [SWS_LOG_00021] and [SWS_LOG_00263], which initialize loggers programmatically via context IDs and description strings and, in the absence of a model, use the console as a sink by default, configuration here is completely manifest-driven. In all variants, ownership of the instance remains within the logging framework [SWS_LOG_00263].

Function CreateLogger in namespace ara::log ([SWS_LOG_00263]) serves to create and register a context-bound Logger object within the logging framework of AUTOSAR Adaptive.

use

Via header file ara/log/logger.h, the function accepts the context identifier ctxId as well as the detailed description ctxDescription, each as type ara::core::StringView [SWS_LOG_00263]. As a return value, the call returns a reference Logger & to the internally managed instance of the created Logger object [SWS_LOG_00263]. Ownership of this instance remains permanently with the logging framework and is not transferred to the caller [SWS_LOG_00263]. If no model is available in the system, the console functions by default as a sink for all logging output [SWS_LOG_00263].

Error Handling and Concurrency

No specific error codes are defined for the invocation and no C++ exceptions are thrown, as the function is specified with noexcept and designated as exception safe [SWS_LOG_00263]. In terms of concurrency, CreateLogger is thread-safe, so the function can be called concurrently from multiple threads without external synchronization [SWS_LOG_00263].

Interaction

The logging framework offers closely related overloads: In addition to this two-parameter signature, an overload allows the additional configuration of a default log level via ctxDefLogLevel ([SWS_LOG_00021]). A further signature enables the creation of a Logger object via an ara::core::InstanceSpecifier directly from the manifest ([SWS_LOG_00256]).

use

The function ara::log::EngFloatMax() from the header file ara/log/logger.h synchronously creates an instance of type Format [SWS_LOG_00220]. The returned object contains the formatting hint Fmt::kEngFloat for outputting floating-point numbers in engineering notation as well as a precision sufficient for full round-trip safety [SWS_LOG_00220]. The function expects no parameters.

Error handling

The function is provided with the specifier noexcept and defined as exception safe (exception safe) [SWS_LOG_00220]. No specific error codes exist, and neither exceptions are thrown nor errors transmitted to diagnostic or error reporting entities. The call does not fail in regular operation.

Concurrency and Limitations

The specification designates the function as thread-safe (thread-safe) [SWS_LOG_00220]. Thanks to the designation as constexpr, the call can already be evaluated at compile time. Interpretation: Since the specification defines no preconditions and the function is stateless, there are likely to be neither restrictions regarding the call context nor dependencies on a prior initialization of the logging infrastructure. Question Q-90c67bfad5b19641 (open)

The helper function HexFloat serves to create a formatting object for floating-point numbers for output in hexadecimal format according to [SWS_LOG_00221]. It instantiates an object of type Format that is provided with the formatting hint Fmt::kHexFloat as well as a specified precision.

Usage and Parameters

The function is available in namespace ara::log via header #include "ara/log/logger.h" [SWS_LOG_00221]:

• Parameters: As input parameter, precision of type std::uint16_t is passed, which specifies the desired output precision [SWS_LOG_00221].
• Return value: An initialized Format object with set Fmt::kHexFloat prefix [SWS_LOG_00221].
• Execution: By being marked as constexpr, construction of the formatting hint can occur synchronously at runtime or already at compile time [SWS_LOG_00221].

Error Handling and Concurrency

The signature is declared with noexcept and is considered completely exception-safe (exception safe) [SWS_LOG_00221]. Neither error codes nor specific error messages are generated. The function is specified as thread-safe (thread-safe) and can be invoked concurrently from arbitrary contexts without synchronization overhead [SWS_LOG_00221].

The function HexFloatMax in namespace ara::log serves to create a Format instance for the formatted output of floating-point values [SWS_LOG_00222]. It is provided via the header file #include "ara/log/logger.h" and takes no call parameters [SWS_LOG_00222]. As a synchronous return value, a Format instance is returned, which is provided with the formatting hint Fmt::kHexFloat and has a precision that ensures full round-trip safety [SWS_LOG_00222].

The signature is declared as constexpr as well as noexcept [SWS_LOG_00222]. This permits evaluation already at compile time and guarantees that no exceptions can occur during execution. Special error states, error codes, or mechanisms for error handling are not specified for this call, as creation of the format object always takes place without error.

Regarding the call context and concurrency, the function is specified as exception safe (exception safe) and thread-safe (thread-safe) [SWS_LOG_00222]. It is subject to no sequential call restrictions and can be called safely and concurrently from arbitrary threads without additional synchronization.

use

The function ara::log::Oct() serves as a helper function for creating a formatting object for logging output in the octal system [SWS_LOG_00213]. It takes no parameters and synchronously returns an object of type Format configured with the formatting hint Fmt::kOct and a default precision [SWS_LOG_00213]. Since the function is declared as constexpr, the instantiation can already take place at compile time. Interpretation: The returned Format object is likely primarily intended for controlling the formatting of integers in log streams. Question Q-3f4fe5ac42de16cb (open)

Error handling

The function guarantees exception safety (exception safe) and is explicitly declared as noexcept [SWS_LOG_00213]. The occurrence of runtime errors or the throwing of exceptions is excluded. Specific error codes do not exist, and no notifications are sent to DET or DEM.

Concurrency and Limitations

Calling Oct() is unconditionally thread-safe (thread-safe) [SWS_LOG_00213]. Because no shared states are modified, the function is not subject to any constraints regarding reentrancy or call context and can be called concurrently from multiple threads.

Interaction

The function is defined in namespace ara::log and provided via header file #include "ara/log/logger.h" [SWS_LOG_00213]. In addition to this parameterless variant, the overload Oct(std::uint16_t precision) exists, via which a different precision can be specified [SWS_LOG_00214].

use

The helper function ara::log::Oct is provided via the header file #include "ara/log/logger.h" in namespace ara::log [SWS_LOG_00214]. It serves to create an instance of type Format with the formatting hint Fmt::kOct as well as a specified precision [SWS_LOG_00214]. As an input parameter, the function accepts the unsigned 16-bit integer value precision, which specifies the precision to be applied [SWS_LOG_00214]. The function operates synchronously and returns the created Format instance immediately [SWS_LOG_00214].

Error Handling and Concurrency

The function is declared as noexcept and explicitly specified as exception-safe (exception safe) [SWS_LOG_00214]. Neither specific error codes nor notifications via DET or DEM exist in case of an error. Regarding call context and concurrency, the function is classified as thread-safe (thread-safe) [SWS_LOG_00214]. Because it is also defined as constexpr, the creation of the formatting instruction can already occur at compile time [SWS_LOG_00214].

Interaction

Within module log, the function complements the related overload Oct() [SWS_LOG_00213]. While the parameterless variant constructs a Format instance with default precision (default precision) [SWS_LOG_00213], the present function allows the explicit configuration of a user-specific precision for octal formatting [SWS_LOG_00214].

The function RegisterConnectionStateHandler in namespace ara::log serves to register an application-side callback function that is called upon every change of the connection state [SWS_LOG_00205]. It is declared in header ara/log/logger.h [SWS_LOG_00205]. A function object callback of type ConnectionStateHandler is passed as a parameter [SWS_LOG_00205], which is specified as a type alias for std::function<void(ClientState)> [SWS_LOG_00265]. A return value is not present (void) [SWS_LOG_00205].

Regarding lifecycle and sequencing, it is specified that only a single state handler can be installed at any point in time [SWS_LOG_00205]. If a callback function was already registered previously, every renewed call completely overwrites the existing instance, so that from this point on exclusively the handler passed last is executed [SWS_LOG_00205].

The function is declared with noexcept and specified as exception-safe [SWS_LOG_00205]. Specific error codes, error values, or notifications to error or diagnostic monitors are not defined in the specification [SWS_LOG_00205].

Regarding concurrency, RegisterConnectionStateHandler is explicitly classified as not thread-safe [SWS_LOG_00205]. The registration must therefore not be called unprotected concurrently from multiple threads and should ideally take place during the initialization phase. In contrast, the type alias ConnectionStateHandler is specified as thread-safe [SWS_LOG_00265]. Interpretation: From this, it is likely to follow that the registered callback can potentially be called from concurrent contexts by the internal logging runtime environment upon state changes. Question Q-59eae7980ba48666 (open)