class ara::core::Future

use

The method get() synchronously retrieves the result of type T from a ara::core::Future [SWS_CORE_00326]. The function behaves identically to its counterpart in std::future; if the asynchronous computation is still ongoing, the call blocks until completion or until an error occurs [SWS_CORE_00336]. By calling it, the object loses its state so that the future becomes invalid immediately (valid() == false) [SWS_CORE_00326]. A non-blocking call can be ensured in advance via is_ready() [SWS_CORE_00332].

Error handling

Failures are reported via C++ exceptions [SWS_CORE_00326]:

• If an error was stored in the associated Promise via SetError() or SetResult(), an exception of the corresponding error type is thrown [SWS_CORE_00326].
• If the shared state is abandoned prematurely by the asynchronous operation, this results in error kBrokenPromise according to FutureErrc [SWS_CORE_00326], [SWS_CORE_00400].
• If the call is made on an invalid instance, a FutureException with error code kNoState is thrown [SWS_CORE_00326].

Concurrency and Limitations

The operation is neither thread-safe nor exception-safe (not exception safe) [SWS_CORE_00326]. Concurrent accesses to the same future from multiple threads require external synchronization. If exceptions are disabled in the compiler toolchain, get() does not participate in overload resolution [SWS_CORE_00326]; for this case, the exception-free alternative GetResult() exists [SWS_CORE_00336]. For instances without a return value, the specialization Future<void, E>::get() is available [SWS_CORE_06226].

The member function then serves to chain asynchronous computations and registers a callable object func as a continuation on an instance of ara::core::Future [SWS_CORE_00331]. After the call returns, the original Future is invalid (valid() == false). The target callable receives the result of the instance retrieved via GetResult() passed as an rvalue of type Result<T, E> [SWS_CORE_00331].

The return type of then depends on the return type U of the continuation [SWS_CORE_00331]:

• If func returns a Future<T2, E2>, implicit future unwrapping to Future<T2, E2> takes place [SWS_CORE_00331].
• If func returns a Result<T2, E2>, implicit result unwrapping to Future<T2, E2> takes place [SWS_CORE_00331].
• In all other cases, the return type is Future<U, E> [SWS_CORE_00331].

The execution of func can take place synchronously in the context of the call to then, in the context of Promise::set_result or Promise::SetError, or in another context [SWS_CORE_00331]. The call is specified as not thread-safe. The continuation is registered in the returned Future; after its destructor returns, no continuation may be executed anymore, while an execution already in progress runs until completion [SWS_CORE_00331].

Standardized error codes do not exist [SWS_CORE_00331]. Errors must be caught by users and forwarded as an error code in a returned Result or a Future, since exceptions must not leave the continuation. Calling an invalid Future triggers FutureInvalidViolation; if the continuation throws an exception, this results in FutureContinuationHasThrownViolation [SWS_CORE_00331].

For executions in an explicit execution context, the overload with executor is available [SWS_CORE_00337], whereas for operations without a return value, the void specialization applies [SWS_CORE_06231].

Usage and Semantics

The method then registers a continuation (func) that is executed asynchronously in the context of the passed executor as soon as the result of the current Future instance is available [SWS_CORE_00337]. The callable entity accepts the result of the instance as an rvalue expression of type Result<T,E> [SWS_CORE_00337]. The return type depends on the return type U of the continuation:

• If the continuation returns a Future<T2,E2>, implicit unwrapping to Future<T2,E2> occurs [SWS_CORE_00337].
• If the continuation returns a Result<T2,E2>, this is likewise implicitly resolved to Future<T2,E2> [SWS_CORE_00337].
• In all other cases, the call yields Future<U,E> [SWS_CORE_00337].

Concurrency and Lifecycle

Immediately after return of the method call, the original Future instance is invalid (valid() == false) [SWS_CORE_00337]. The function is declared as not thread-safe [SWS_CORE_00337]. Registered continuations are managed in the newly returned Future. After its destructor has elapsed, no further continuation may be started; an already running execution is run to completion, so the destructor may block [SWS_CORE_00337].

Error Handling and Interaction

Standardized error codes are not defined [SWS_CORE_00337]. A call on an invalid instance triggers the violation FutureInvalidViolation [SWS_CORE_00337]. If the continuation throws an exception, this results in a FutureContinuationHasThrownViolation; exceptions must therefore be caught and forwarded as errors via ara::core::Result or ara::core::Future [SWS_CORE_00337]. Compared to the overload without an execution context [SWS_CORE_00331], this variant enforces execution on the passed executor; the analogous specialization [SWS_CORE_06237] exists for void result types.

The synchronous query function valid() checks without parameters whether an instance of ara::core::Future has a shared state and is thus usable [SWS_CORE_00327]. It returns true if the object is ready for use, and false if no shared state is present [SWS_CORE_00327]. The behavior corresponds to the standard function std::future::valid and applies equally to the template specialization ara::core::Future<void, E> [SWS_CORE_06227].

The function is declared as noexcept, is considered exception-safe (exception safe), and is explicitly specified as thread-safe (thread-safe) [SWS_CORE_00327]. It does not raise any error codes or exceptions itself and can therefore be safely used for state checking [SWS_CORE_00327].

In interaction with other methods of Future, the validity check is crucial because calling operations such as wait() [SWS_CORE_00328] or is_ready() [SWS_CORE_00332] throw an FutureInvalidViolation in the event of an invalid state (valid() == false). A previously valid Future automatically becomes invalid as soon as its result is consumed via get() [SWS_CORE_00326] or GetResult() [SWS_CORE_00336], or further processing via then() [SWS_CORE_00331], [SWS_CORE_00337] has been registered.

The member function wait of class ara::core::Future synchronously blocks the calling thread until a result value or an error from the asynchronous operation is available [SWS_CORE_00328]. The function takes no parameters, returns no value, and behaves according to the specification analogously to the corresponding function from std::future [SWS_CORE_00328]. The same behavior applies to the template specialization ara::core::Future<void, E> [SWS_CORE_06228].

Regarding error handling and concurrency, the following requirements are defined:

• Error condition: If the future object is invalid (valid == FALSE), a FutureInvalidViolation is present [SWS_CORE_00328], [SWS_CORE_06228]. Nevertheless, the function is declared as noexcept and classified as exception safe (exception safe) [SWS_CORE_00328].
• Thread safety: The call is explicitly classified as not thread-safe [SWS_CORE_00328]. Concurrent access to the same future object without external synchronization is not permitted.

In interaction with related interfaces, checking via is_ready is recommended before calling [SWS_CORE_00332], [SWS_CORE_06232]: If it returns true, calling wait is guaranteed to no longer block. If a time-limited blocking operation is required instead of unlimited waiting, wait_for with a relative duration [SWS_CORE_00329], [SWS_CORE_06229] as well as wait_until with an absolute time point [SWS_CORE_00330], [SWS_CORE_06230] are alternatively available.

use

The member function wait_for of class ara::core::Future blocks the calling thread for a maximum of the passed time span timeoutDuration or until a result value or an error is ready in the shared state [SWS_CORE_00329]. Its behavior corresponds to the matching function from std::future [SWS_CORE_00329]. As a return value, it returns a FutureStatus [SWS_CORE_00329], which indicates whether the shared state is available (kReady) or the specified waiting time has expired (kTimeout) [SWS_CORE_00361].

Error Handling and Boundary Conditions

The function is declared as noexcept and specified as exception-safe (exception safe) [SWS_CORE_00329]. If the Future object is invalid (valid == FALSE), a violation in the form of FutureInvalidViolation occurs [SWS_CORE_00329]. Interpretation: Since no C++ exceptions may be thrown, such a violation is likely handled platform-side as a fatal runtime error. Question Q-2f22a07f6e143856 (open)

Concurrency and Interaction

The operation is classified as not thread-safe [SWS_CORE_00329]; concurrent accesses to the same instance therefore require external synchronization. The semantics and signature apply identically to the template specialization ara::core::Future<void, E> [SWS_CORE_06229]. In contrast to std::future_status, there is no entry for deferred in the enumeration type FutureStatus [SWS_CORE_00361].

The member function wait_until blocks the calling thread until either the specified absolute time point deadline is reached or the ara::core::Future provides a result or an error [SWS_CORE_00330]. The behavior is based on the corresponding function of std::future [SWS_CORE_00330].

As a return value, the function returns a FutureStatus [SWS_CORE_00330]. This enum type signals via state kReady that the shared state is ready (value or error available), or via kTimeout that the deadline has passed without a result [SWS_CORE_00361]. A state analogous to std::future_status::deferred does not exist in FutureStatus [SWS_CORE_00361].

Regarding error handling and exception safety, the function is specified as exception-safe (exception safe) and noexcept [SWS_CORE_00330]. However, if the function is called on an invalid instance (valid == FALSE), a violation in the form of FutureInvalidViolation occurs [SWS_CORE_00330].

Regarding concurrency, wait_until is classified as not thread-safe (not thread-safe) [SWS_CORE_00330]. Parallel accesses to the same ara::core::Future object must therefore be synchronized externally. The same semantics and signature apply to the specialization ara::core::Future<void, E> [SWS_CORE_06230].