generator<T, Executor = void> - Boost.Outcome documentation

# `generator<T, Executor = void>`

This is a classic coroutine generator whereby the coroutine is resumed to calculate the next value, and is suspended upon yielding that value. If the value being yielded is an Outcome type, special semantics are used if the coroutine throws an exception (see below).

The `Executor` template parameter is purely for compatibility with third party software such as ASIO, and this awaitable can be directly used by ASIO.

Example of use:

    generator<int> func(int x)
    {
      while(x >= 0)
      {
        co_yield x--;
      }
    }
    ...
    // Creates the coroutine, immediately suspending it.
    auto f = func(5);
    // If the coroutine has another value to yield ...
    while(f)
    {
      // Get the next value from the coroutine
      int r = f();
      ...
    }

`generator<T>` has special semantics if `T` is a type capable of constructing from an `exception_ptr` or `error_code` – any exceptions thrown during the function’s body are sent via `T`, preferably via the error code route if `error_from_exception(` `)` successfully matches the exception throw. This means that a `basic_result<T, E, NoValuePolicy>` or `basic_outcome<T, EC, EP, NoValuePolicy>` where one of its types is is compatible will have its `.error()` or `.exception()` set.

Note that `generator<T>` does not otherwise transport exception throws, and rethrows any exceptions thrown within the coroutine body through the coroutine machinery. This does not produce reliable consequences in current C++ compilers. You should therefore wrap the coroutine body in a `try...catch` if `T` is not able to transport exceptions on its own.

Requires: C++ coroutines to be available in your compiler.

Namespace: `BOOST_OUTCOME_V2_NAMESPACE::awaitables`

Header: `<boost/outcome/coroutine_support.hpp>`

Last revised: March 18, 2022 at 14:45:32 UTC