协程和任务 ¶

此节提纲的高级 asyncio API 能操控协程和任务。

协程
可期待
创建任务
任务消除
任务组
休眠
并发运行任务
从消除屏蔽
超时
等待原语
在线程中运行
从其它线程调度
自省
任务对象

协程  ¶

协程采用 async/await 句法声明是编写 asyncio 应用程序的首选方式。例如，以下代码片段打印 hello，等待 1 秒，然后打印 world：

>>> import asyncio
>>> async def main():
...     print('hello')
...     await asyncio.sleep(1)
...     print('world')
>>> asyncio.run(main())
hello
world

注意，简单调用协程不会调度它的执行：

>>> main()
<coroutine object main at 0x1053bb7c8>

要实际运行协程，asyncio 提供下列机制：

asyncio.run() 函数运行顶层入口点 main() 函数 (见以上范例)。

等待协程。以下代码片段将在等待 1 秒后打印 hello，然后打印 world 后于等待 another 2 秒：

import asyncio
import time
async def say_after(delay, what):
    await asyncio.sleep(delay)
    print(what)
async def main():
    print(f"started at {time.strftime('%X')}")
    await say_after(1, 'hello')
    await say_after(2, 'world')
    print(f"finished at {time.strftime('%X')}")
asyncio.run(main())

期望输出：

started at 17:13:52
hello
world
finished at 17:13:55

asyncio.create_task() 函数并发运行协程如 asyncio Tasks .

让我们修改以上范例并运行 2 say_after 协程 concurrently :

async def main():
    task1 = asyncio.create_task(
        say_after(1, 'hello'))
    task2 = asyncio.create_task(
        say_after(2, 'world'))
    print(f"started at {time.strftime('%X')}")
    # Wait until both tasks are completed (should take
    # around 2 seconds.)
    await task1
    await task2
    print(f"finished at {time.strftime('%X')}")

注意，现在期望的输出展示片段运行速度比之前快了 1 秒：

started at 17:14:32
hello
world
finished at 17:14:34

asyncio.TaskGroup 类提供了更现代替代对于 create_task() 。使用此 API，范例最后变成：

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'))
        print(f"started at {time.strftime('%X')}")
    # The wait is implicit when the context manager exits.
    print(f"finished at {time.strftime('%X')}")

计时和输出应该如同先前版本。

3.11 版新增： asyncio.TaskGroup .

可期待  ¶

我们说对象是 awaitable object if it can be used in an await expression. Many asyncio APIs are designed to accept awaitables.

有 3 种主要类型的 awaitable 对象：协程 , 任务，和未来 .

协程

Python 协程是 awaitables 因此可以从其它协程等待：

import asyncio
async def nested():
    return 42
async def main():
    # Nothing happens if we just call "nested()".
    # A coroutine object is created but not awaited,
    # so it *won't run at all*.
    nested()
    # Let's do it differently now and await it:
    print(await nested())  # will print "42".
asyncio.run(main())

重要

In this documentation the term “coroutine” can be used for two closely related concepts:

a 协程函数 ： async def 函数；
a 协程对象 : an object returned by calling a 协程函数 .

任务

任务被用于调度协程 concurrently .

When a coroutine is wrapped into a Task with functions like asyncio.create_task() the coroutine is automatically scheduled to run soon:

import asyncio
async def nested():
    return 42
async def main():
    # Schedule nested() to run soon concurrently
    # with "main()".
    task = asyncio.create_task(nested())
    # "task" can now be used to cancel "nested()", or
    # can simply be awaited to wait until it is complete:
    await task
asyncio.run(main())

未来

A Future is a special 低级 awaitable object that represents an eventual result of an asynchronous operation.

When a Future object is awaited it means that the coroutine will wait until the Future is resolved in some other place.

Future objects in asyncio are needed to allow callback-based code to be used with async/await.

Normally there is no need to create Future objects at the application level code.

Future objects, sometimes exposed by libraries and some asyncio APIs, can be awaited:

async def main():
    await function_that_returns_a_future_object()
    # this is also valid:
    await asyncio.gather(
        function_that_returns_a_future_object(),
        some_python_coroutine()
    )

A good example of a low-level function that returns a Future object is loop.run_in_executor() .

创建任务  ¶

asyncio. create_task ( coro , * , name = None , context = None ) ¶

3.7 版新增。

3.8 版改变：添加 name 参数。

3.11 版改变：添加 context 参数。

任务消除  ¶

可以轻松且安全地取消任务。当取消任务时， asyncio.CancelledError will be raised in the task at the next opportunity.

It is recommended that coroutines use try/finally blocks to robustly perform clean-up logic. In case asyncio.CancelledError is explicitly caught, it should generally be propagated when clean-up is complete. Most code can safely ignore asyncio.CancelledError .

The asyncio components that enable structured concurrency, like asyncio.TaskGroup and asyncio.timeout() , are implemented using cancellation internally and might misbehave if a coroutine swallows asyncio.CancelledError . Similarly, user code should not call uncancel .

任务组  ¶

Task groups combine a task creation API with a convenient and reliable way to wait for all tasks in the group to finish.

class asyncio. TaskGroup ¶

create_task ( coro , * , name = None , context = None ) ¶

协程 asyncio. sleep ( delay , result = None ) ¶

并发运行任务  ¶

awaitable asyncio. gather ( * aws , return_exceptions = False ) ¶

从消除屏蔽  ¶

awaitable asyncio. shield ( aw ) ¶

超时  ¶

协程 asyncio. timeout ( delay ) ¶

常量	描述
`FIRST_COMPLETED`	The function will return when any future finishes or is cancelled.
`FIRST_EXCEPTION`	The function will return when any future finishes by raising an exception. If no future raises an exception then it is equivalent to `ALL_COMPLETED` .
`ALL_COMPLETED`	The function will return when all futures finish or are cancelled.

协程和任务 ¶

协程  ¶

可期待  ¶

创建任务  ¶

任务消除  ¶

任务组  ¶

休眠  ¶

并发运行任务  ¶

从消除屏蔽  ¶

超时  ¶

等待原语  ¶

在线程中运行  ¶

从其它线程调度  ¶

自省  ¶

任务对象  ¶

内容表

上一话题

下一话题

本页

快速搜索