libs/outcome/doc/src/content/reference/aliases/eager.md

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