class ara::core::FutureException

The class ara::core::FutureException serves as a specific exception type that is thrown on errors in connection with ara::core::Future and ara::core::Promise [SWS_CORE_00412]. It encapsulates an ara::core::ErrorCode and is created via an explicit constructor [SWS_CORE_00412]. For safe use in asynchronous and concurrent environments, instantiation is specified as noexcept, thread-safe, and exception-safe [SWS_CORE_00412].

more ›

Context

Within module core, the class ara::core::FutureException functions as a dedicated exception type for asynchronous communication and synchronization primitives. In accordance with its intended purpose, this exception type is triggered by ara::core::Future as well as ara::core::Promise to signal error states in the context of asynchronous operations to the caller. Structurally, ara::core::FutureException derives from base class Exception and encapsulates a domain-specific error code.

In collaborative scenarios, ara::core::FutureException forms the bridge between the producing asynchronous endpoint (such as ara::core::Promise), the consuming endpoint (ara::core::Future), and application-side error handling. The interaction of these three participants illustrates the structural framework in which the exception is passed for error handling.

Context diagram: Embedding of ara::core::FutureException between Promise, Future, and the application thread. Sources: [SWS_CORE_00412]

Lifecycle

The instantiation of ara::core::FutureException takes place explicitly via the constructor by passing an error code of type ara::core::ErrorCode [SWS_CORE_00412]. Declaration with explicit prevents implicit type conversion from an ara::core::ErrorCode. The constructor is designated as noexcept, ensuring that construction itself cannot throw further exceptions [SWS_CORE_00412].

Regarding execution safety, the class is specified as exception safe [SWS_CORE_00412]. For concurrent operation, the specification also explicitly identifies construction as thread-safe [SWS_CORE_00412]. This permits asynchronous operations to safely instantiate the exception across thread boundaries and pass it to waiting recipients.

Usage Path

The typical usage sequence encompasses the occurrence of an error during an asynchronous operation up to the catching of the exception by the consuming caller. Provision is typically made via header ara/core/future_error_domain.h [SWS_CORE_00412].

Sequence diagram: Flow from error occurrence via instantiation of ara::core::FutureException to catching. Sources: [SWS_CORE_00412]

The usage sequence is divided into the following steps:

• Detection of a failure or an impermissible state during asynchronous processing in connection with ara::core::Promise or ara::core::Future.
• Creation of ara::core::FutureException using the constructor specifying the specific ara::core::ErrorCode [SWS_CORE_00412].
• Transmission of the exception to the consuming thread, where it is caught within a try-catch block and the contained error is analyzed.

Error Scenarios

Since ara::core::FutureException itself represents the vehicle for error signaling, error scenarios are limited to the conditions of its own creation. Because the constructor is marked with noexcept, it is guaranteed that no execution error in the form of a secondary exception can occur during object creation [SWS_CORE_00412]. Passing a valid object of type ara::core::ErrorCode as a parameter is considered a precondition for construction err [SWS_CORE_00412]. If an error occurs when working with ara::core::Future or ara::core::Promise, the exception serves the purpose of transporting this error code unchanged to higher-level callers.