Design#

Task#

A pw::async2::Task is the basic unit of asynchronous work. It can be thought of as a lightweight, cooperatively scheduled “thread” or a state machine. Users define tasks by subclassing pw::async2::Task and implementing the DoPend virtual method. This method contains the core logic of the task and is called by the Dispatcher to advance the task’s state.

Dispatcher#

The pw::async2::Dispatcher is the scheduler or event loop. Its primary role is to manage a queue of tasks and run them to completion. It polls tasks to see if they can make progress and puts them to sleep when they are blocked waiting for an event.

Poll#

Asynchronous operations in pw_async2 do not block. Instead, they return a pw::async2::Poll to indicate their status.

• Ready(T): The operation has completed, and the Poll object contains the result of type T.

• Pending(): The operation has not yet completed. The task should yield control back to the Dispatcher and arrange to be woken up later.

Context#

When the Dispatcher polls a Task, it provides a pw::async2::Context object. This context contains the necessary information for the task to interact with the asynchronous runtime, most importantly the Waker for the current task.

Waker#

A pw::async2::Waker is a handle that allows a suspended task to be resumed. When a task’s DoPend method returns Pending(), it must have first arranged for its Waker to be stored somewhere accessible to the event source it is waiting on. When the event occurs (e.g., data arrives, a timer fires), the event handler calls Wake() on the stored Waker. This notifies the Dispatcher to place the corresponding task back on the run queue.

Signature#

A pendable function has the general signature:

Poll<T> PendFoo(Context& cx, ...);

Where:

• Poll<T> is the return type, indicating whether the operation is complete (Ready(T)) or not (Pending()).

• Context& cx is a required first parameter that provides access to the asynchronous runtime, including the task’s Waker.

• ... represents any additional arguments required by the operation.

Though not required, the names of these functions are conventionally prefixed with Pend.

Invariants#

To ensure the correct behavior of the scheduler, all pendable functions must adhere to the following rules.

Task Lifetime and Storage#

The memory for a Task object itself is managed by the user. This provides flexibility in how tasks are allocated and stored. Common patterns include:

• Static or Member Storage: For tasks that live for the duration of the application or are part of a long-lived object, they can be allocated statically or as class members. This is the most common and memory-safe approach. The user must ensure the Task object is not destroyed while it is still registered with a Dispatcher. Calling pw::async2::Task::Deregister() before destruction guarantees safety.

• Dynamic Allocation: For tasks with a dynamic lifetime, pw_async2 provides the pw::async2::AllocateTask() helper. This function allocates a task using a provided pw::allocator::Allocator and wraps it in a concrete Task implementation that automatically calls the allocator’s Delete method upon completion. This simplifies memory management for “fire-and-forget” tasks.

// This task will be deallocated from the provided allocator when it's done.
Task* task = AllocateTask<MyPendable>(my_allocator, arg1, arg2);
dispatcher.Post(*task);

Coroutine Memory#

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

A pw::async2::CoroContext, which holds a pw::allocator::Allocator, must be passed to any function that returns a pw::async2::Coro. This allocator is used to allocate the coroutine frame. If allocation fails, the resulting Coro will be invalid and will immediately return a Ready(Status::Internal()) result when polled. This design makes coroutine memory usage explicit and controllable.

Integrating with Callback-Based APIs#

It’s common to have a system where some parts use pw_async2 and others use callbacks. To bridge this gap, pw_async2 provides helpers to wrap a pendable function and invoke a callback with its result.

• pw::async2::OneshotCallbackTask: Polls a pendable function until it completes. When the function returns Ready(value), invokes a provided callback with the value and then finishes the task. This is ideal for request/response patterns.

• pw::async2::RecurringCallbackTask: This task is similar but reschedules itself after the callback is invoked. This allows it to handle pendable functions that produce a stream of values over time.

This allows non-pw_async2 code to initiate and receive results from asynchronous operations without needing to be structured as a Task itself.

// A pendable function from the async part of the system.
Poll<Result<int>> ReadSensorAsync(Context&);

// Non-async code wants to read the sensor.
void ReadAndPrintSensor() {
  // Create a task that will call our lambda when the sensor read is done.
  auto callback_task = OneshotCallbackTaskFor<&ReadSensorAsync>(
    [](Result<int> result) {
      if (result.ok()) {
        printf("Sensor value: %d\n", *result);
      }
    });

  // Post the task to the system's dispatcher.
  GetMainDispatcher().Post(callback_task);

  // The task must outlive the operation. Here, we might block or wait
  // on a semaphore for the callback to signal completion.
}

TimeProvider#

The pw::async2::TimeProvider is an abstract interface that acts as a factory for timers. Its key responsibilities are:

• Providing the current time: The now() method returns the current time according to a specific clock.

• Creating timers: The WaitUntil(timestamp) and WaitFor(delay) methods return a pw::async2::TimeFuture object.

This design is friendly to dependency injection. By providing different implementations of TimeProvider, code that uses timers can be tested with a simulated clock (like pw::chrono::SimulatedClock), allowing for fast and deterministic tests without real-world delays. For production code, the pw::async2::GetSystemTimeProvider() function returns a global TimeProvider that uses the configured system clock.

TimeFuture#

A pw::async2::TimeFuture is a pendable object that completes at a specific time. A task can Pend on a TimeFuture to suspend itself until the time designated by the future. When the time is reached, the TimeProvider wakes the task, and its next poll of the TimeFuture will return Ready(timestamp).

Example#

Here is an example of a task that logs a message, sleeps for one second, and then logs another message.

#include "pw_async2/dispatcher.h"
#include "pw_async2/system_time_provider.h"
#include "pw_async2/task.h"
#include "pw_chrono/system_clock.h"
#include "pw_log/log.h"

using namespace std::chrono_literals;

class LoggingTask : public pw::async2::Task {
 public:
  LoggingTask() : state_(State::kLogFirstMessage) {}

 private:
  enum class State {
    kLogFirstMessage,
    kSleeping,
    kLogSecondMessage,
    kDone,
  };

  Poll<> DoPend(Context& cx) override {
    while (true) {
      switch (state_) {
        case State::kLogFirstMessage:
          PW_LOG_INFO("Hello, async world!");
          future_ = GetSystemTimeProvider().WaitFor(1s);
          state_ = State::kSleeping;
          continue;

        case State::kSleeping:
          if (future_.Pend(cx).IsPending()) {
            return Pending();
          }
          state_ = State::kLogSecondMessage;
          continue;

        case State::kLogSecondMessage:
          PW_LOG_INFO("Goodbye, async world!");
          state_ = State::kDone;
          continue;

        case State::kDone:
          return Ready();
      }
    }
  }

  State state_;
  pw::async2::TimeFuture<pw::chrono::SystemClock> future_;
};

Coroutines (Coro<T>)#

For projects using C++20, pw_async2 provides first-class support for coroutines via pw::async2::Coro. This allows you to write 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.

Coro<Status> ReadAndSend(Reader& reader, Writer& writer) {
  // co_await suspends the coroutine until the Read operation completes.
  Result<Data> data = co_await reader.Read();
  if (!data.ok()) {
    co_return data.status();
  }

  // The coroutine resumes here and continues.
  co_await writer.Write(*data);
  co_return OkStatus();
}

Data Passing (OnceSender / OnceReceiver)#

This pair of types provides a simple, single-use channel for passing a value from one task to another. The receiving task pends on the pw::async2::OnceReceiver until the producing task sends a value through the pw::async2::OnceSender.

Combinators (Join and Select)#

These powerful utilities allow for the composition of multiple asynchronous operations:

• pw::async2::Join: Waits for all of a set of pendable operations to complete.

• pw_async2::Select: Waits for the first of a set of pendable operations to complete, returning its result.