From 85434bfe915c180d96042163f0eb61776efbfc40 Mon Sep 17 00:00:00 2001 From: Xuanteng Huang Date: Wed, 16 Oct 2024 22:07:30 +0800 Subject: [PATCH] update asyncio doc landing page with examples --- Doc/library/asyncio.rst | 46 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 5f83b3a2658da4..68a490e72b3f08 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -58,6 +58,52 @@ Additionally, there are **low-level** APIs for .. include:: ../includes/wasm-notavail.rst +.. _asyncio-intro: + +As the **Hello World!** example shows, you can start an asynchronous program by +defining a ``async`` function and execute it with :func:`asyncio.run`. + + +Alternatively, you can start currently asynchronous tasks with +:class:`asyncio.TaskGroup`:: + + import asyncio + + async def say_after(delay, what): + await asyncio.sleep(delay) + print(what) + + async def main(): + async with asyncio.TaskGroup() as tg: + task1 = tg.create_task( + say_after(1, 'hello')) + + task2 = tg.create_task( + say_after(2, 'world')) + + asyncio.run(main()) + +In this case, the asynchronous function ``main`` will invoke another two +*current* tasks via :func:`TaskGroup.create_task`. +All the tasks are awaited before the context manager ``tg`` exits. + +``asyncio`` schedules the asynchronous tasks in the :ref:`asyncio-event-loop`. +You can explicitly create one and append tasks into it:: + + import asyncio + + loop = asyncio.get_event_loop() + tasks = [ + loop.create_task(say_after(1, "hello")), + loop.create_task(say_after(2, "world")) + ] + loop.run_until_complete(asyncio.gather(*tasks)) + loop.close() + +Here, we use :func:`get_event_loop` to obtain the event loop for cunrret thread. +After appending two asynchronous tasks into the loop, we make the loop wait +until both tasks finish. + .. _asyncio-cli: .. rubric:: asyncio REPL