class ara::core::Promise< void, E >

The specialization ara::core::Promise< void, E > serves as an asynchronous producer endpoint for signaling the completion of an operation without a return value or for transmitting an error ([SWS_CORE_06341]). After instantiation, the associated Future for the consumer is retrieved exactly once via get_future() ([SWS_CORE_06344]). Provisioning is performed thread-safely by set_value(), SetError(), or SetResult(), whereby the shared state is marked as ready. Since the class has pure move semantics, repeated setting or missing shared states lead to specified violations.

more ›

Context

The class ara::core::Promise< void, E > represents a template specialization for asynchronous workflows without a payload value (return type void). It forms the producer side of a communication channel and synchronizes asynchronous computations or operations with the consumer side. Via a shared internal state (shared state), it allows signaling either the successful completion of an operation or the occurrence of an error of type E. The corresponding receiver object is provided in the form of ara::core::Future< void, E > ([SWS_CORE_06344]). According to the requirements of the AUTOSAR Adaptive Platform, the implementation requires that the error type E is compatible with ara::core::ErrorCode; any deviation leads to a compilation error.

Lifecycle

Creation of an instance is performed via the parameterless default constructor [SWS_CORE_06341], which creates a new shared state and behaves analogously to the C++ standard function std::promise. The class models exclusive ownership and implements strict move semantics: Both the copy constructor ([SWS_CORE_06350]) and the copy assignment operator ([SWS_CORE_06351]) are deleted (delete).

An existing state can be transferred to other instances via the move constructor ([SWS_CORE_06342]) or the move assignment operator ([SWS_CORE_06343]). Upon move assignment, an abandoned shared state held until then is relinquished and the state is transferred as if by Promise(std::move(other)).swap(*this) ([SWS_CORE_06343]). Furthermore, the function swap ([SWS_CORE_06352]) allows the direct swap of two states.

The destructor [SWS_CORE_06349] releases any still-held shared state. Interpretation: Prematurely relinquishing the shared state upon destruction of an unsatisfied promise is likely to lead to an orphaned state in the associated future. Question Q-e89b32fa3e5994e2 (open) Regarding concurrency, the default creation ([SWS_CORE_06341]) as well as setting the result ([SWS_CORE_06345], [SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]) are thread-safe. In contrast, move operations, swap, retrieving the future ([SWS_CORE_06344]), and destruction are not thread-safe and require external coordination in the event of shared access.

Usage Path

Typical usage of ara::core::Promise< void, E > comprises preparing the asynchronous execution, handing over the reception channel, and subsequently reporting the result:

1. Initialization: The producer instantiates the promise object ([SWS_CORE_06341]).
2. Retrieve future: Via get_future(), the associated ara::core::Future< void, E > is created exactly once ([SWS_CORE_06344]) and handed over to the consumer side.
3. Set result: After completion of the asynchronous operation, the producer transitions the shared state into the ready state (ready):
   • In case of success, by calling set_value() without arguments ([SWS_CORE_06345]).
   • In case of an error, by storing an error via SetError, either by move ([SWS_CORE_06353]) or by copy ([SWS_CORE_06354]).
   • Alternatively, by passing a complete Result< void, E > using SetResult by copy ([SWS_CORE_06355]) or move ([SWS_CORE_06356]).
4. Resolution: As soon as the state is ready, the consumer can consume the result via the future; the promise object is released at the end of its scope ([SWS_CORE_06349]).

Sequence diagram: Typical flow of asynchronous synchronization from creation to provision of the result. Sources: [SWS_CORE_06341], [SWS_CORE_06344], [SWS_CORE_06345], [SWS_CORE_06349]

Error Scenarios

Violations of preconditions lead to defined error situations (violations):

• IsoStdFutureErrcFutureAlreadyRetrievedViolation: Triggered if get_future() is called multiple times for the same shared state ([SWS_CORE_06344]).
• IsoStdFutureErrcNoStateViolation: Occurs if get_future() is called without the promise possessing a shared state ([SWS_CORE_06344]), such as after a move operation ([SWS_CORE_06342]).
• IsoStdFutureErrcPromiseAlreadySatisfiedViolation: Occurs if set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]), or SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) is called although a value or error has already been stored in the shared state.
• PromiseNoSharedStateToSetViolation: Signals that set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]), or SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) was called without an existing shared state.

Regarding exception safety, the methods SetError and SetResult are conditionally exception safe: They guarantee noexcept only if the type E is classified as nothrow move constructible or nothrow copy constructible ([SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]).