diff --git a/pw_async2/backends.rst b/pw_async2/backends.rst index 936a363846..31f2918e38 100644 --- a/pw_async2/backends.rst +++ b/pw_async2/backends.rst @@ -3,10 +3,21 @@ ================== pw_async2 backends ================== -.. TODO: b/323607687 - Add backend guidance here +The :ref:`pw_async2 interface ` must be fulfilled +by a concrete implementation. You can use one of the Pigweed-provided backends +listed below or roll your own. If you roll your own, please consider +:ref:`contributing ` it to upstream Pigweed! + +.. _epoll: https://man7.org/linux/man-pages/man7/epoll.7.html + +* :ref:`module-pw_async2_basic`. A backend that uses a thread-notification-based + :cpp:class:`pw::async2::Dispatcher`. +* :ref:`module-pw_async2_epoll`. A backend that uses a :cpp:class:`pw::async2::Dispatcher` + backed by Linux's `epoll`_ notification system. .. toctree:: :maxdepth: 1 + :hidden: Basic <../pw_async2_basic/docs> Linux epoll <../pw_async2_epoll/docs> diff --git a/pw_async2/docs.rst b/pw_async2/docs.rst index 1182628f94..ef07ceb0cc 100644 --- a/pw_async2/docs.rst +++ b/pw_async2/docs.rst @@ -13,7 +13,7 @@ pw_async2 - **Pluggable**: Your existing event loop, work queue, or task scheduler can run the ``Dispatcher`` without any extra threads. - **Coroutine-capable**: C++20 coroutines work just like other tasks, and can - easily plug into an existing ``pw_async2`` systems. + easily plug into an existing ``pw_async2`` system. :cpp:class:`pw::async2::Task` is Pigweed's async primitive. ``Task`` objects are cooperatively-scheduled "threads" which yield to the @@ -22,7 +22,7 @@ progress, the ``Dispatcher`` will run it again. For example: .. tab-set:: - .. tab-item:: Manual ``Task`` State Machine + .. tab-item:: Manual task state machine .. literalinclude:: examples/basic.cc :language: cpp @@ -30,7 +30,7 @@ progress, the ``Dispatcher`` will run it again. For example: :start-after: [pw_async2-examples-basic-manual] :end-before: [pw_async2-examples-basic-manual] - .. tab-item:: Coroutine Function + .. tab-item:: Coroutine function .. literalinclude:: examples/basic.cc :language: cpp @@ -75,6 +75,24 @@ Tasks can then be run on a :cpp:class:`pw::async2::Dispatcher` using the And more. +.. grid:: 2 + + .. grid-item-card:: :octicon:`code-square` Backends + :link: module-pw_async2-backends + :link-type: ref + :class-item: sales-pitch-cta-secondary + + You can fulfill the ``pw_async2`` interface with a Pigweed-provided + backend or roll your own. + + .. grid-item-card:: :octicon:`pencil` Pigweed blog: C++20 coroutines + :link: docs-blog-05-coroutines + :link-type: ref + :class-item: sales-pitch-cta-secondary + + A blog post on how Pigweed implements coroutines without heap + allocation, and challenges encountered along the way. + .. toctree:: :hidden: :maxdepth: 1 diff --git a/pw_async2/guides.rst b/pw_async2/guides.rst index e91ac5d871..0b484d79d3 100644 --- a/pw_async2/guides.rst +++ b/pw_async2/guides.rst @@ -14,8 +14,8 @@ Guides .. _module-pw_async2-guides-tasks: -Dispatchers and tasks -===================== +How a dispatcher manages tasks +============================== The purpose of a :cpp:class:`pw::async2::Dispatcher` is to keep track of a set of :cpp:class:`pw::async2::Task` objects and run them to completion. The dispatcher is essentially a scheduler for cooperatively-scheduled @@ -37,8 +37,8 @@ dispatcher will then invoke ``DoPend`` once more, continuing the cycle until .. _module-pw_async2-guides-waking: -Waking -====== +Waking tasks +============ When a task is unable to complete without waiting, the implementor of ``DoPend`` must return ``Pending`` and should arrange for the task to be reawoken once ``DoPend`` may be able to make more progress. This is done by calling @@ -107,7 +107,6 @@ C++20 users can define tasks using coroutines! :end-before: [pw_async2-examples-basic-coro] Any value with a ``Poll Pend(Context&)`` method can be passed to - ``co_await``, which will return with a ``T`` when the result is ready. To return from a coroutine, ``co_return `` must be used instead of @@ -116,8 +115,8 @@ the usual ``return `` syntax. Because of this, the coroutines. :c:macro:`PW_CO_TRY` and :c:macro:`PW_CO_TRY_ASSIGN` should be used instead. -For a more detailed explanation of Pigweed's coroutine support, see the -documentation on the :cpp:class:`pw::async2::Coro` type. +For a more detailed explanation of Pigweed's coroutine support, see +:cpp:class:`pw::async2::Coro`. .. _module-pw_async2-guides-timing: @@ -136,5 +135,5 @@ for a timeout or deadline using the Additionally, code which uses :cpp:class:`pw::async2::TimeProvider` for timing can be tested with simulated time using :cpp:class:`pw::async2::SimulatedTimeProvider`. Doing so helps avoid -timing-dependent test flakes, as well as ensure that tests are fast since they +timing-dependent test flakes and helps ensure that tests are fast since they don't need to wait for real-world time to elapse. diff --git a/pw_async2_epoll/docs.rst b/pw_async2_epoll/docs.rst index 79f2ce424e..cd801e4940 100644 --- a/pw_async2_epoll/docs.rst +++ b/pw_async2_epoll/docs.rst @@ -3,9 +3,7 @@ =================== pw_async2_epoll =================== +.. _epoll: https://man7.org/linux/man-pages/man7/epoll.7.html --------- -Overview --------- This is a simple backend for ``pw_async2`` that uses a ``Dispatcher`` backed -by Linux's epoll notification system. +by Linux's `epoll`_ notification system.