Coroutines

As one cannot call statement return from within a Coroutine, the very first part of Outcome’s support for Coroutines is OUTCOME_CO_TRYV(expr)/OUTCOME_CO_TRY(expr) , which is literally the same as OUTCOME_TRY() except that co_return is called to return early instead of return. eager<result<std::string>> to_string(int x) { if(x >= 0) { OUTCOME_CO_TRY(convert(x)); } co_return "out of range"; } »

The second part of the support is provided by header <outcome/coroutine_support.hpp> (or <outcome/experimental/coroutine_support.hpp> if you want Coroutine support for Experimental Outcome). This adds into namespace OUTCOME_V2_NAMESPACE::awaitables (or OUTCOME_V2_NAMESPACE::experimental::awaitables) these awaitable types suitable for returning from a Coroutinised function: eager<T, Executor = void> An eagerly evaluated Coroutine: invoking co_await upon a function returning one of these immediately begins the execution of the function now. If the function never suspends, the overhead is similar to calling an ordinary function. »

In v2.1.2 Outcome published official support for using Outcome within C++ coroutines. This page documents that support. All standard C++ Coroutines have the following form: // Coroutine functions MUST return an AWAITABLE type AWAITABLE<int> function_name(Args ...) { ... ordinary C++ ... if(!...) { co_return 5; // CANNOT use ordinary 'return' from coroutines } ... // Possibly suspend this coroutine's execution until the // awaitable resumes execution of dependent code auto x = co_await expr_resulting_in_AWAITABLE; . »

eager<T, Executor = void> and lazy<T, Executor = void> and their atomic editions are completely standard awaitables with no special behaviours, except if T is a basic_result or basic_outcome. In that situation, the following occurs: If the Coroutine throws a C++ exception which was not handled inside the Coroutine body, Outcome’s awaitable types try to convert it into a form which your Result or Outcome type being returned can transport. For example: »

Many people have requested that operator co_await be overloaded to behave as a TRY operator when supplied with an Outcome type. Outcome does not implement that extension, nor will we accept PRs contributing support for this. We think you should use OUTCOME_CO_TRY() as this will lead to more maintainable and future proof code. However, we deliberately do not get in the way of you implementing that overload yourself in your own Outcome-based code. »