class ara::diag::DiagException

The class ara::diag::DiagException functions as a specialized exception type for signaling errors from diagnostic classes of the AUTOSAR Adaptive Platform ([SWS_DM_00515]). It encapsulates a ara::core::ErrorCode and is thrown on internal errors to propagate error states in a structured manner to calling applications ([SWS_DM_00516]). Its constructor is declared thread-safe and exception-safe by noexcept ([SWS_DM_00516]).

more ›

Context

The class ara::diag::DiagException forms the central exception type for the functional cluster of the AUTOSAR Adaptive Platform Diagnostics (SWS Diagnostics §8.11.4 “Class: DiagException”, [SWS_DM_00515]). It derives directly from the base class ara::core::Exception and is responsible for reporting error conditions occurring within the diagnostic classes to the caller in exceptional cases. Primary interaction partners are the providing diagnostic classes within ara::diag, which signal exceptional situations, as well as the consuming application software that requests diagnostic operations and catches potential exceptions. Through its declaration in the header file ara/diag/diag_error_domain.h, the exception class is directly linked to the diagnostic-specific error domains ([SWS_DM_00516]).

Lifecycle

Instantiation of ara::diag::DiagException is performed by passing an error code of type ara::core::ErrorCode to the constructor ([SWS_DM_00516]). This constructor is defined as explicit, which prevents implicit type conversions from error codes. Furthermore, the creation is declared as noexcept, which guarantees exception safety (\"exception safe\") during object creation and prevents another exception from being thrown while raising an exception state ([SWS_DM_00516]). Thread safety (\"thread-safe\") is guaranteed for invoking the constructor ([SWS_DM_00516]). Regarding the further life cycle, the exception object exists for the duration of the stack unwinding process until the completion of the associated catch block (Interpretation: Ownership and destruction of the exception object follow the standardized mechanisms of the C++ runtime environment). Question Q-ae485b4ea411b187 (open)

Usage Path

The regular usage path of ara::diag::DiagException spans from the detection of an error situation in the diagnostic subsystem to evaluation by the application layer. The following sequence illustrates the interaction of the involved components:

Sequence diagram: Typical sequence during the occurrence, throwing, and handling of a DiagException. Sources: [SWS_DM_00515], [SWS_DM_00516].

The application initially initiates an operation on a functional class of the module ara::diag. If a condition occurs during processing that precludes a regular return path, the diagnostic class creates an instance of ara::diag::DiagException, specifying the particular ara::core::ErrorCode ([SWS_DM_00516]). This exception is thrown via the normal C++ exception mechanism. The calling application instance catches the object in a typed exception handler to initiate appropriate recovery or logging actions.

Error Scenarios

As an error-signaling class, ara::diag::DiagException primarily serves the propagation of diagnostic error conditions. The precondition for successful construction is the provisioning of an initialized parameter err of type ara::core::ErrorCode ([SWS_DM_00516]). The exception safety of the constructor ensures that no secondary exceptions are raised in the construction path, even in resource-critical situations ([SWS_DM_00516]). After successful instantiation, the object fully encapsulates the passed error code (Interpretation: The concrete diagnostic error code is likely inspected by the catching application logic via the inherited base mechanisms of ara::core::Exception). Question Q-d20a61b72951321b (open)