class ara::core::Promise

The class ara::core::Promise acts as an asynchronous write endpoint to transfer values, errors, or results across threads into a shared state [SWS_CORE_00341]. Read access is performed via a Future that can be retrieved exactly once and is released when the result is provided [SWS_CORE_00344]. Because the class is non-copyable, the state remains strictly in unique ownership via move semantics, where setting the result multiple times or retrieving the future multiple times leads to standardized violations.

more ›

Context

The class ara::core::Promise represents the Adaptive Platform-specific manifestation of the concept std::promise known from the C++ standard. It is defined in the header ara/core/future.h as a template Promise<T, E = ErrorCode> and serves as an asynchronous write endpoint of a shared state (shared state). Via this channel, a producer passes either a computed output value, an error, or an aggregated ara::core::Result across threads. The corresponding receiver side accesses the result via an associated ara::core::Future, which is retrieved via the instance method get_future [SWS_CORE_00344]. In contrast to the standard C++ mechanism, which is primarily based on exceptions, AUTOSAR Adaptive anchors the error-typed paradigm: If the error type E is chosen to be not equal to ara::core::ErrorCode, the specification enforces a compilation error.

Lifecycle

An instance is regularly created via the parameterless default constructor, which behaves like the corresponding constructor of std::promise, is thread-safe, and establishes a new shared state [SWS_CORE_00341]. To guarantee unique ownership of this state, copy operations are completely prohibited: Both the copy constructor [SWS_CORE_00350] and the copy assignment operator [SWS_CORE_00351] are declared as deleted (delete).

However, the class supports move semantics. The move constructor takes over the shared state of the source instance [SWS_CORE_00342]. Upon a move assignment, the target instance abandons its previous shared state and takes over the state of the passed object analogously to a swap operation [SWS_CORE_00343]. In addition, the method swap allows swapping the internal state with another instance [SWS_CORE_00352]. Upon destruction via the destructor, a still held shared state is released or abandoned [SWS_CORE_00349]. While the default constructor is designed to be thread-safe [SWS_CORE_00341], move operations, assignments, swap, and destruction are not thread-safe ([SWS_CORE_00342], [SWS_CORE_00343], [SWS_CORE_00352], [SWS_CORE_00349]).

State diagram: Lifecycle and state transitions of the shared state in a Promise instance. Sources: [SWS_CORE_00341], [SWS_CORE_00342], [SWS_CORE_00343], [SWS_CORE_00344], [SWS_CORE_00345], [SWS_CORE_00349], [SWS_CORE_00353], [SWS_CORE_00355]

Usage Path

A typical provisioning sequence comprises the following steps:

1. Creation: The producer instantiates a ara::core::Promise<T, E> [SWS_CORE_00341].
2. Retrieving the future: Prior to starting asynchronous processing, the producer calls get_future() [SWS_CORE_00344]. Because only a single associated Future is permitted per promise, this call may occur exactly once. The returned Future is passed to the consuming thread.
3. Setting the result: After completion of the asynchronous operation, the producer transfers the result into the shared state and transitions it to the ready state. For this purpose, thread-safe overloads for copy and move operations are available in each case:
   • Successful value: call to set_value ([SWS_CORE_00345], [SWS_CORE_00346]).
   • Error state: call to SetError ([SWS_CORE_00353], [SWS_CORE_00354]).
   • Combined result: call to SetResult ([SWS_CORE_00355], [SWS_CORE_00356]).

Sequence diagram: Call and synchronization sequence between producer, promise, shared state, and consumer. Sources: [SWS_CORE_00341], [SWS_CORE_00344], [SWS_CORE_00345], [SWS_CORE_00353], [SWS_CORE_00355]

Error Scenarios

The specification defines strict preconditions for all interactions with the shared state, non-compliance with which leads to standardized violations (Violations):

• Multiple retrieval of the future: If get_future() is called more than once for the same shared state, the violation IsoStdFutureErrcFutureAlreadyRetrievedViolation occurs [SWS_CORE_00344].
• Missing shared state: If the called instance has no shared state—for example after executing a move operation—, get_future() leads to IsoStdFutureErrcNoStateViolation [SWS_CORE_00344]. In this case, the methods set_value, SetError, and SetResult trigger the violation PromiseNoSharedStateToSetViolation ([SWS_CORE_00345], [SWS_CORE_00353], [SWS_CORE_00355]).
• Already satisfied state: If the shared state has already been populated with a value, error, or result, each renewed call to set_value ([SWS_CORE_00345], [SWS_CORE_00346]), SetError ([SWS_CORE_00353], [SWS_CORE_00354]), or SetResult ([SWS_CORE_00355], [SWS_CORE_00356]) leads to the violation IsoStdFutureErrcPromiseAlreadySatisfiedViolation.
• Exception safety: The methods set_value, SetError, and SetResult are conditionally exception safe (conditionally exception safe). They do not throw exceptions provided that the constructors of the types T and E are declared as nothrow ([SWS_CORE_00345], [SWS_CORE_00353], [SWS_CORE_00355]).

Interpretation: Abandoning the shared state upon destruction of the instance without prior value assignment ([SWS_CORE_00349]) is likely to result, analogously to the standard C++ behavior of std::promise, in an associated Future registering a corresponding error event upon an attempted read. Question Q-fd013bb17a591af9 (open)