Coroutines#

pw_async2: Cooperative async tasks for embedded

For projects using C++20, pw_async2 provides first-class support for coroutines via Coro. This allows writing asynchronous logic in a sequential, synchronous style, eliminating the need to write explicit state machines. The co_await keyword is used to suspend execution until an asynchronous operation is Ready.

See also Pigweed Blog #5: C++20 coroutines without heap allocation, a blog post on how Pigweed implements coroutines without heap allocation, and challenges encountered along the way.

Using coroutines#

Define a coroutine#

A pw_async2 coroutine is a function with CoroContext as its first parameter and a return type of Coro<T>. Here is an example of a coroutine that returns pw::Status:

 1#include <optional>
 2#include <utility>
 3
 4#include "pw_allocator/shared_ptr.h"
 5#include "pw_async2/channel.h"
 6#include "pw_async2/coro.h"
 7#include "pw_log/log.h"
 8#include "pw_result/result.h"
 9#include "pw_status/status.h"
10#include "pw_unit_test/framework.h"
11
12namespace {
13
14using ::pw::OkStatus;
15using ::pw::Status;
16using ::pw::async2::Coro;
17using ::pw::async2::CoroContext;
18using ::pw::async2::Receiver;
19using ::pw::async2::Sender;
20
21/// Create a coroutine which asynchronously receives a value from `receiver` and
22/// forwards it to `sender`.
23///
24/// Note: the `CoroContext` argument is used by the `Coro<T>` internals to
25/// allocate the coroutine state. If this allocation fails, the coroutine
26/// aborts.
27Coro<Status> ForwardingCoro(CoroContext,
28                            Receiver<int> receiver,
29                            Sender<int> sender) {
30  std::optional<int> data = co_await receiver.Receive();
31  if (!data.has_value()) {
32    PW_LOG_ERROR("Receiving failed: channel has closed");
33    co_return Status::Unavailable();
34  }
35
36  if (!(co_await sender.Send(*data))) {
37    PW_LOG_ERROR("Sending failed: channel has closed");
38    co_return Status::Unavailable();
39  }
40
41  co_return OkStatus();
42}
43
44}  // namespace

Any future or coroutine can be passed to co_await, which evaluates to a value_type when the result is ready. To return from a coroutine, use co_return <expression> instead of the usual return <expression> syntax.

Tip

Use PW_CO_TRY and PW_CO_TRY_ASSIGN instead of PW_TRY and PW_TRY_ASSIGN when working with pw::Status or pw::Result in a coroutine. These macros use co_return instead of return.

Run a coroutine#

Run a coroutine as a pw_async2 task using Dispatcher::Post(). The following posts a coroutine as a FutureTask:

  SharedPtr<FutureTask<Coro<Status>>> task = dispatcher.Post<ForwardingCoro>(
      allocator, std::move(receiver1_), std::move(sender2_));

  // The task is automatically posted when allocated.
  dispatcher.RunToCompletion();

The coroutine can also be instantiated directly and passed to Post, though this requires listing the allocator twice:

  SharedPtr<FutureTask<Coro<Status>>> task = dispatcher.Post(
      allocator,
      ForwardingCoro(allocator, std::move(receiver1_), std::move(sender2_)));

  // The task is automatically posted when allocated.
  dispatcher.RunToCompletion();

In the examples above, Dispatcher::Post() returns nullptr if either the initial coroutine frame or the FutureTask fails to allocate. However, if a nested coroutine invoked with co_await fails to allocate while the coroutine is running (or if an unallocated Coro<T> is pended directly), Coro::Pend crashes with PW_CRASH.

To handle coroutine allocation failures gracefully, wrap the coroutine with Coro::MakeFallible:

  auto task = dispatcher.Post(
      allocator,
      ForwardingCoro(allocator, std::move(receiver1_), std::move(sender2_))
          .MakeFallible([] {
            PW_LOG_ERROR("coroutine allocation failed! Aborting...");
            return Status::ResourceExhausted();
          }));

  // The task is automatically posted when allocated.
  dispatcher.RunToCompletion();

MakeFallible returns a FallibleCoro that intercepts allocation failures (both during initial coroutine creation and when invoking nested coroutines with co_await) and resolves gracefully rather than crashing:

  • Fallback value: Pass a fallback value or an error handler function that returns a fallback value (e.g. coro.MakeFallible(Status::ResourceExhausted()) or coro.MakeFallible([] { return Status::ResourceExhausted(); })). The resulting future yields T directly.

      auto task = dispatcher.Post(
          allocator,
          ForwardingCoro(allocator, std::move(receiver1_), std::move(sender2_))
              .MakeFallible(Status::ResourceExhausted()));
    
      dispatcher.RunToCompletion();
    
  • Optional value: If the handler returns void (e.g. coro.MakeFallible([] { PW_LOG_ERROR("Alloc failed"); })) or no arguments are passed (coro.MakeFallible()), the resulting future yields std::optional<T> (or void if T is void), where std::nullopt indicates an allocation failure.

MakeFallible can also be applied to a nested coroutine inside co_await (e.g. co_await InnerCoro(cx).MakeFallible(Status::ResourceExhausted())) to handle a child coroutine’s allocation failure locally without aborting the calling coroutine.

FutureTask (or the CoroTask and FallibleCoroTask aliases in pw_async2/coro_task.h, which discard the coroutine’s return value) can also be stack or statically allocated instead of dynamically allocated with Dispatcher::Post(). This is not recommended, as it is more complex and does not eliminate all allocations. Coroutines always dynamically allocate their frames.

  // NOT RECOMMENDED: Manually declare a FutureTask to wrap a Coro. The
  // coroutine itself still requires dynamic allocation.
  pw::async2::FutureTask task(
      ForwardingCoro(allocator, std::move(receiver1_), std::move(sender2_)));

  dispatcher.Post(task);
  dispatcher.RunToCompletion();

For more details about Pigweed’s coroutine support, see Coro.

Memory#

When using C++20 coroutines, the compiler generates code to save the coroutine’s state (including arguments and local variables) across suspension points (co_await). pw_async2 hooks into this mechanism to control where this state is stored and to support gracefully handling allocation failures.

A pw_async2 coroutine must accept a CoroContext by value as its first argument. CoroContext wraps a reference to a pw::Allocator, and this allocator is used to allocate the coroutine frame. When instantiating a coroutine, simply pass an allocator as the first argument; CoroContext is implicitly constructible from an Allocator&.

If initial coroutine frame allocation fails, the resulting Coro object is invalid (!coro.is_pendable()) and the coroutine body does not execute. If a nested coroutine invoked via co_await fails to allocate while a coroutine is running, the coroutine aborts and unwinds its active coroutine frames, destroying any local variables in scope.

Pending an invalid Coro directly or encountering a nested allocation failure in Coro::Pend crashes with PW_CRASH. To handle initial and nested allocation failures without crashing, wrap the coroutine with MakeFallible.

Argument lifetimes#

Because a coroutine suspends before executing its body, any reference arguments (including the implicit *this receiver on member coroutines) are stored as references inside the coroutine frame and must outlive the returned Coro or Generator.

On compilers that support Clang’s coroutine lifetime attributes, Coro and Generator are annotated with PW_ATTRIBUTE_CORO_RETURN_TYPE and PW_ATTRIBUTE_CORO_LIFETIME_BOUND. Passing a temporary to a reference parameter of a coroutine (outside an immediate co_await expression) triggers a -Wdangling compiler warning. Non-coroutine helper functions or lambdas that construct and return a Coro or Generator must be annotated with PW_ATTRIBUTE_CORO_WRAPPER (and optionally PW_ATTRIBUTE_CORO_DISABLE_LIFETIME_BOUND if reference parameters are copied by value rather than retained by the coroutine).

Passing data between coroutines#

Coroutines run within pw_async2 tasks and can pass data in all the same ways. See Channels for details about passing data with channels.