diff options
Diffstat (limited to 'pw_async/docs.rst')
| -rw-r--r-- | pw_async/docs.rst | 37 |
1 files changed, 33 insertions, 4 deletions
diff --git a/pw_async/docs.rst b/pw_async/docs.rst index e1a34e009..8ead20e04 100644 --- a/pw_async/docs.rst +++ b/pw_async/docs.rst @@ -33,6 +33,11 @@ Dispatcher API Task API ============== +.. doxygenstruct:: pw::async::Context + :members: + +.. doxygentypedef:: pw::async::TaskFunction + .. doxygenclass:: pw::async::Task :members: @@ -41,8 +46,17 @@ Facade API Task ---- -The Task type represents a work item that is submitted to a Dispatcher. The Task -facade enables Dispatcher backends to specify custom state and methods. +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 @@ -50,6 +64,9 @@ The active Task backend is configured with the GN variable 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 @@ -58,13 +75,16 @@ 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 Task backend is configured with the GN variable +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`` @@ -72,6 +92,16 @@ 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 ====== @@ -169,6 +199,5 @@ Roadmap ------- - Stabilize Task cancellation API - Utility for dynamically allocated Tasks -- Bazel support - CMake support - Support for C++20 coroutines |