class ara::core::Executor

Class ara::core::Executor provides an interface for asynchronous execution of callables in a guaranteed thread-safe context. Tasks are either initiated in a result-oriented manner via execute [SWS_CORE_00024] returning a ara::core::Future for values or error codes, or dispatched status-independently via oneway_execute [SWS_CORE_00025] in fire-and-forget mode. As a central constraint, it must be noted that execute itself is not thread-safe and parallel calls on the same instance must be synchronized externally, whereas execution of the callable in the background is performed thread-safely.

more ›

Context

Class ara::core::Executor provides an interface for an execution context that asynchronously executes callables in a guaranteed thread-safe environment. It serves as an abstraction layer between the calling thread and asynchronous background processing. Two mechanisms are available for submitting tasks: Method execute [SWS_CORE_00024] passes a task in a result-oriented manner and returns a ara::core::Future object, through which the subsequent return value or an error code can be synchronized and queried. For pure notifications or status-independent background operations, the class provides method oneway_execute [SWS_CORE_00025], which follows fire-and-forget semantics and does not return an asynchronous context to the caller. Presumably, the concrete implementation encapsulates a thread management or task queue in the background to coordinate concurrent processing. Question Q-068fe33f2900d6cf (open)

Lifecycle

The instantiation and lifetime of an ara::core::Executor are subject to differentiated rules regarding exception safety and thread safety:

• Copying: The copy constructor [SWS_CORE_00009] and the copy assignment operator [SWS_CORE_00017] are specified as thread-safe, but are classified as not exception safe. A copy operation may therefore fail if required resources cannot be allocated.
• Moving: The move constructor [SWS_CORE_00015] and the move assignment [SWS_CORE_00018] are declared as noexcept and are thus exception-safe. However, move operations are not thread-safe (not thread-safe); hence, concurrent accesses during moving must be synchronized by the caller.
• Destruction: Destructor [SWS_CORE_00019] is noexcept and implemented as thread-safe, allowing the lifecycle of an instance to be terminated safely.

Regarding concurrency during operation, a fundamental division becomes apparent: While oneway_execute [SWS_CORE_00025] is thread-safe, execute [SWS_CORE_00024] is classified as not thread-safe. The lack of thread safety in execute is likely attributable to the internal creation and management of the underlying state object for the resulting future, which is why concurrent invocations of execute on the same instance must be synchronized externally. Question Q-4425e6b07758230e (open)

Usage Path

Usage of ara::core::Executor is divided into two primary paths, depending on whether a return value is required:

1. Result-oriented path (execute): The caller passes a callable object f as well as optional arguments p... to execute [SWS_CORE_00024]. The method immediately returns a ara::core::Future whose result type is based on the deduced return type of the call. The callable is executed asynchronously in the guaranteed context. Once processing is complete, the caller can extract the result value or a potential error code from the future.
2. One-way path (oneway_execute): If the caller requires neither feedback nor synchronization, oneway_execute [SWS_CORE_00025] is invoked. The callable is likewise executed asynchronously, but no return value exists (void).

Sequence diagram: Asynchronous task processing via execute and result retrieval via future. Sources: [SWS_CORE_00024]

Error Scenarios

The invocation methods execute [SWS_CORE_00024] and oneway_execute [SWS_CORE_00025] do not throw C++ exceptions; both are explicitly specified as noexcept. Likewise, the specification for execute defines no standardized error codes for the dispatch invocation itself [SWS_CORE_00024].

If, however, an error occurs during the asynchronous execution of the callable, it is propagated via the ara::core::Future returned by execute: In the event of an error, the future encapsulates an error code, whereas in case of success, type ara::core::Result::value_type is provided with the function result [SWS_CORE_00024]. For oneway_execute [SWS_CORE_00025], by design there is no possibility of returning an error to the caller; errors remain within the asynchronous context.