pigweed/pw_async/docs.rst

.. _module-pw_async:

========
pw_async
========
.. pigweed-module::
   :name: pw_async

--------
Overview
--------
Pigweed's async module provides portable APIs and utilities for writing
asynchronous code. Currently, it provides:

- Message loop APIs

.. attention::
  This module is still under construction. The API is not yet stable.

----------
Dispatcher
----------
Dispatcher is an API for a message loop that schedules and executes Tasks. See
:bdg-ref-primary-line:`module-pw_async_basic` for an example implementation.

Dispatcher is a pure virtual interface that is implemented by backends and
FakeDispatcher. A virtual interface is used instead of a facade to allow
substituting a FakeDispatcher for a Dispatcher backend in tests.

Dispatcher API
==============
.. doxygenclass:: pw::async::Dispatcher
   :members:


Task API
==============
.. doxygenstruct:: pw::async::Context
   :members:

.. doxygentypedef:: pw::async::TaskFunction

.. doxygenclass:: pw::async::Task
   :members:

Facade API
==========

Task
----
The ``Task`` type represents a work item that can be submitted to and executed
by a ``Dispatcher``.

To run work on a ``Dispatcher`` event loop, a ``Task`` can be constructed from
a function or lambda (see ``pw::async::TaskFunction``) and submitted to run
using the ``pw::async::Dispatcher::Post`` method (and its siblings, ``PostAt``
etc.).

The ``Task`` facade enables backends to provide custom storage containers for
``Task`` s, as well as to keep per- ``Task`` data alongside the ``TaskFunction``
(such as ``next`` pointers for intrusive linked-lists of ``Task``).

The active Task backend is configured with the GN variable
``pw_async_TASK_BACKEND``. The specified target must define a class
``pw::async::backend::NativeTask`` in the header ``pw_async_backend/task.h``
that meets the interface requirements in ``public/pw_async/task.h``. Task will
then trivially wrap ``NativeTask``.

The bazel build provides the ``pw_async_task_backend`` label flag to configure
the active Task backend.

FakeDispatcher
--------------
The FakeDispatcher facade is a utility for simulating a real Dispatcher
in tests. FakeDispatcher simulates time to allow for reliable, fast testing of
code that uses Dispatcher. FakeDispatcher is a facade instead of a concrete
implementation because it depends on Task state for processing tasks, which
varies across Task backends.

The active FakeDispatcher backend is configured with the GN variable
``pw_async_FAKE_DISPATCHER_BACKEND``. The specified target must define a class
``pw::async::test::backend::NativeFakeDispatcher`` in the header
``pw_async_backend/fake_dispatcher.h`` that meets the interface requirements in
``public/pw_async/task.h``. FakeDispatcher will then trivially wrap
``NativeFakeDispatcher``.

The bazel build provides the ``pw_async_fake_dispatcher_backend`` label flag to
configure the FakeDispatcher backend.

Testing FakeDispatcher
^^^^^^^^^^^^^^^^^^^^^^
The GN template ``fake_dispatcher_tests`` in ``fake_dispatcher_tests.gni``
creates a test target that tests a FakeDispatcher backend. This enables
one test suite to be shared across FakeDispatcher backends and ensures
conformance.

FunctionDispatcher
------------------
.. doxygenclass:: pw::async::FunctionDispatcher
   :members:

HeapDispatcher
--------------
.. doxygenclass:: pw::async::HeapDispatcher
   :members:

Design
======

Task Ownership
--------------
Tasks are owned by clients rather than the Dispatcher. This avoids either
memory allocation or queue size limits in Dispatcher implementations. However,
care must be taken that clients do not destroy Tasks before they have been
executed or canceled.

Getting Started
===============
First, configure the Task backend for the Dispatcher backend you will be using:

.. code-block::

   pw_async_TASK_BACKEND = "$dir_pw_async_basic:task"


Next, create an executable target that depends on the Dispatcher backend you
want to use:

.. code-block::

   pw_executable("hello_world") {
     sources = [ "main.cc" ]
     deps = [ "$dir_pw_async_basic:dispatcher" ]
   }

Next, instantiate the Dispatcher and post a task:

.. code-block:: cpp

   #include "pw_async_basic/dispatcher.h"

   int main() {
     BasicDispatcher dispatcher;

     // Spawn a thread for the dispatcher to run on.
     Thread work_thread(thread::stl::Options(), dispatcher);

     Task task([](pw::async::Context& ctx){
       printf("hello world\n");
       ctx.dispatcher->RequestStop();
     });

     // Execute `task` in 5 seconds.
     dispatcher.PostAfter(task, 5s);

     // Blocks until `task` runs.
     work_thread.join();
     return 0;
   }

The above example runs the dispatcher on a new thread, but it can also run on
the current/main thread:

.. code-block:: cpp

   #include "pw_async_basic/dispatcher.h"

   int main() {
     BasicDispatcher dispatcher;

     Task task([](pw::async::Context& ctx){
       printf("hello world\n");
     });

     // Execute `task` in 5 seconds.
     dispatcher.PostAfter(task, 5s);

     dispatcher.Run();
     return 0;
   }

Fake Dispatcher
===============
To test async code, FakeDispatcher should be dependency injected in place of
Dispatcher. Then, time should be driven in unit tests using the ``Run*()``
methods. For convenience, you can use the test fixture
FakeDispatcherFixture.

.. doxygenclass:: pw::async::test::FakeDispatcherFixture
   :members:

.. attention::

   ``FakeDispatcher::now()`` will return the simulated time.
   ``Dispatcher::now()`` should therefore be used to get the current time in
   async code instead of other sources of time to ensure consistent time values
   and reliable tests.

-------
Roadmap
-------
- Stabilize Task cancellation API
- Utility for dynamically allocated Tasks
- CMake support
- Support for C++20 coroutines

.. toctree::
   :hidden:
   :maxdepth: 1

   Backends <backends>