Dispatcher

pw_async2: Cooperative async tasks for embedded

pw_async2 dispatchers implement the pw::async2::Dispatcher interface. The pw::async2::RunnableDispatcher class can optionally be used to support running the dispatcher directly in a thread.

Pigweed provides two Dispatcher implementations:

• pw::async2::BasicDispatcher is a simple thread-notification-based RunnableDispatcher implementation.

• pw::async2::EpollDispatcher is a RunnableDispatcher backed by Linux’s epoll notification system.

How a dispatcher manages tasks

The purpose of a Dispatcher is to keep track of a set of Task objects and run them to completion. The dispatcher is essentially a scheduler for cooperatively scheduled (non-preemptive) threads (tasks).

Tasks notify their dispatchers when they are ready to run. The dispatcher then runs and advances each task by invoking its DoPend method. The DoPend method is typically implemented manually by users, though it is automatically provided by coroutines.

If the task is able to complete, DoPend will return Ready, in which case the dispatcher will deregister the task.

If the task is unable to complete, DoPend must return Pending and arrange for the task to be woken up when it is able to make progress again. Once the task is rewoken, the task is re-added to the Dispatcher queue. The dispatcher will then invoke DoPend once more, continuing the cycle until DoPend returns Ready and the task is completed.

See Informed poll for more conceptual explanation.