1+++ 2title = "`eager<T>/atomic_eager<T>`" 3description = "An eagerly evaluated coroutine awaitable with Outcome customisation." 4+++ 5 6This is very similar to {{% api "lazy<T>" %}}, except that execution of the `eager<T>` 7returning function begins immediately, and if the function never suspends during the 8course of its execution, no suspend-resume cycle occurs. Functions which return `eager<T>` 9are therefore suitable for tasks which *may* require suspension, but will often complete 10immediately. 11 12`atomic_eager<T>` is like `eager<T>`, except that the setting of the coroutine result 13performs an atomic release, whilst the checking of whether the coroutine has finished 14is an atomic acquire. 15 16Example of use (must be called from within a coroutinised function): 17 18```c++ 19eager<int> func(int x) 20{ 21 co_return x + 1; 22} 23... 24// Executes like a non-coroutine function i.e. r is immediately set to 6. 25int r = co_await func(5); 26``` 27 28`eager<T>` has special semantics if `T` is a type capable of constructing from 29an `exception_ptr` or `error_code` -- any exceptions thrown during the function's body 30are sent via `T`, preferably via the error code route if {{% api "error_from_exception(" %}}`)` 31successfully matches the exception throw. This means that a {{% api "basic_result<T, E, NoValuePolicy>" %}} 32or {{% api "basic_outcome<T, EC, EP, NoValuePolicy>" %}} where one of its types is 33is compatible will have its `.error()` or `.exception()` set. 34 35Note that `eager<T>` does not otherwise transport exception throws, and rethrows 36any exceptions thrown within the coroutine body through the coroutine machinery. 37This does not produce reliable consequences in current C++ compilers. You should 38therefore wrap the coroutine body in a `try...catch` if `T` is not able to transport 39exceptions on its own. 40 41*Requires*: C++ coroutines to be available in your compiler. 42 43*Namespace*: `BOOST_OUTCOME_V2_NAMESPACE::awaitables` 44 45*Header*: `<boost/outcome/coroutine_support.hpp>` 46