diff options
Diffstat (limited to 'examples/async/minimal/doc/minimal.rst')
-rw-r--r-- | examples/async/minimal/doc/minimal.rst | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/examples/async/minimal/doc/minimal.rst b/examples/async/minimal/doc/minimal.rst new file mode 100644 index 000000000..54f847ea9 --- /dev/null +++ b/examples/async/minimal/doc/minimal.rst @@ -0,0 +1,38 @@ +Async "Minimal" Example +======================= + +The Python language provides keywords for asynchronous operations, i.e., +"async" to define coroutines or "await" to schedule asynchronous calls in the +event loop (see `PEP 492 <https://peps.python.org/pep-0492/>`_). It is up to +packages to implement an event loop, support for these keywords, and more. + +The best-known package for this is `asyncio`. asyncio offers an API that allows +for the asyncio event loop to be replaced by a custom implementation. Such an +implementation is available with the `QtAsyncio` module. It is based on Qt and +uses Qt's event loop in the backend. + +`trio` is another popular package that offers a dedicated `low-level API +<https://trio.readthedocs.io/en/stable/reference-lowlevel.html>`_ for more +complex use cases. Specifically, there exists a function `start_guest_run` that +enables running the Trio event loop as a "guest" inside another event loop - +Qt's in our case, standing in contrast to asyncio's approach. + +Based on this functionality, two examples for async usage with Qt have been +implemented: `eratosthenes` and `minimal`: + +.. image:: minimal.png + :alt: Async example: Minimal + +* `eratosthenes` is a more extensive example that visualizes the Sieve of + Eratosthenes algorithm. This algorithm per se is not one that is particularly + suitable for asynchronous operations as it's not I/O-heavy, but synchronizing + coroutines to a configurable tick allows for a good visualization. +* `minimal` is a minimal example featuring a button that triggers an + asynchronous coroutine with a sleep. It is designed to highlight which + boilerplate code is essential for an async program with Qt and offers a + starting point for more complex programs. + +While `eratosthenes` offloads the asynchronous logic that will run in +trio's/asyncio's event loop into a separate class, `minimal` demonstrates that +async functions can be integrated into any class, including subclasses of Qt +classes. |