1.. _module-pw_async2: 2 3========= 4pw_async2 5========= 6.. pigweed-module:: 7 :name: pw_async2 8 9 - **Simple Ownership**: Say goodbye to that jumble of callbacks and shared 10 state! Complex tasks with many concurrent elements can be expressed by 11 simply combining smaller tasks. 12 - **Efficient**: No dynamic memory allocation required. 13 - **Pluggable**: Your existing event loop, work queue, or task scheduler 14 can run the ``Dispatcher`` without any extra threads. 15 - **Coroutine-capable**: C++20 coroutines work just like other tasks, and can 16 easily plug into an existing ``pw_async2`` system. 17 18:cpp:class:`pw::async2::Task` is Pigweed's async primitive. ``Task`` objects 19are cooperatively-scheduled "threads" which yield to the 20:cpp:class:`pw::async2::Dispatcher` when waiting. When the ``Task`` is able to make 21progress, the ``Dispatcher`` will run it again. For example: 22 23.. tab-set:: 24 25 .. tab-item:: Manual state machine 26 27 .. literalinclude:: examples/basic.cc 28 :language: cpp 29 :linenos: 30 :start-after: [pw_async2-examples-basic-manual] 31 :end-before: [pw_async2-examples-basic-manual] 32 33 .. tab-item:: Coroutine 34 35 .. literalinclude:: examples/basic.cc 36 :language: cpp 37 :linenos: 38 :start-after: [pw_async2-examples-basic-coro] 39 :end-before: [pw_async2-examples-basic-coro] 40 41Tasks can then be run on a :cpp:class:`pw::async2::Dispatcher` using the 42:cpp:func:`pw::async2::Dispatcher::Post` method: 43 44.. literalinclude:: examples/basic.cc 45 :language: cpp 46 :linenos: 47 :start-after: [pw_async2-examples-basic-dispatcher] 48 :end-before: [pw_async2-examples-basic-dispatcher] 49 50.. grid:: 2 51 52 .. grid-item-card:: :octicon:`rocket` Quickstart & guides 53 :link: module-pw_async2-quickstart-guides 54 :link-type: ref 55 :class-item: sales-pitch-cta-primary 56 57 How to: 58 59 * Use dispatchers to coordinate tasks 60 * Pass data between tasks 61 * Use coroutines 62 63 And more. 64 65 .. grid-item-card:: :octicon:`code-square` Reference 66 :link: module-pw_async2-reference 67 :link-type: ref 68 :class-item: sales-pitch-cta-secondary 69 70 API reference for: 71 72 * ``Task`` 73 * ``Dispatcher`` 74 * ``CoRo`` 75 76 And more. 77 78.. grid:: 2 79 80 .. grid-item-card:: :octicon:`code-square` Backends 81 :link: module-pw_async2-backends 82 :link-type: ref 83 :class-item: sales-pitch-cta-secondary 84 85 You can fulfill the ``pw_async2`` interface with a Pigweed-provided 86 backend or roll your own. 87 88 .. grid-item-card:: :octicon:`pencil` Pigweed blog: C++20 coroutines 89 :link: docs-blog-05-coroutines 90 :link-type: ref 91 :class-item: sales-pitch-cta-secondary 92 93 A blog post on how Pigweed implements coroutines without heap 94 allocation, and challenges encountered along the way. 95 96.. toctree:: 97 :hidden: 98 :maxdepth: 1 99 100 guides 101 reference 102 Backends <backends> 103