`asyncio` — 异步 I/O 调度器¶

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: asyncio

例子:

import asyncio

async def blink(led, period_ms):
    while True:
        led.on()
        await asyncio.sleep_ms(5)
        led.off()
        await asyncio.sleep_ms(period_ms)

async def main(led1, led2):
    asyncio.create_task(blink(led1, 700))
    asyncio.create_task(blink(led2, 400))
    await asyncio.sleep_ms(10_000)

# Running on a pyboard
from pyb import LED
asyncio.run(main(LED(1), LED(2)))

# Running on a generic board
from machine import Pin
asyncio.run(main(Pin(1), Pin(2)))

核心函数¶

asyncio.create_task(coro)¶

从给定的协程创建一个新任务并安排其运行。

返回相应的 Task 对象。

asyncio.current_task()¶: 返回当前正在运行的任务关联的 Task 对象。

asyncio.run(coro)¶

从给定的协程创建一个新任务并运行它，直到完成。

返回 coro 返回的值。

asyncio.sleep(t)¶

休眠 t 秒（可以是浮点数）。

这是一个协程。

asyncio.sleep_ms(t)¶

休眠 t 毫秒。

这是一个协程，并且是 MicroPython 的扩展。

其他函数¶

asyncio.wait_for(awaitable, timeout)¶

等待 awaitable 完成，但如果超过 timeout 秒，则取消它。如果 awaitable 不是一个任务，则将从中创建一个任务。

如果超时发生，它会取消任务并引发 asyncio.TimeoutError：这应该由调用者捕获。任务接收 asyncio.CancelledError，可以忽略或使用 try...except 或 try...finally 捕获以运行清理代码。

返回 awaitable 的返回值。

这是一个协程。

asyncio.wait_for_ms(awaitable, timeout)¶

类似于 wait_for，但 timeout 是以毫秒为单位的整数。

这是一个协程，并且是 MicroPython 的扩展。

asyncio.gather(*awaitables, return_exceptions=False)¶

同时运行所有 awaitables。任何不是任务的 awaitables 都会提升为任务。

返回所有 awaitables 的返回值列表。

这是一个协程。

Task 类¶

class asyncio.Task¶

此对象将协程封装到运行中的任务中。任务可以使用 await task 等待，等待任务完成并返回任务的返回值。

任务不应直接创建，而应使用 create_task 创建它们。

Task.cancel()¶: 通过注入 asyncio.CancelledError 来取消任务。任务可以忽略此异常。可以通过捕获它或通过 try ... finally 运行清理代码。

Event 类¶

class asyncio.Event¶: 创建一个新的事件，可用于同步任务。事件从清除状态开始。

Event.is_set()¶: 如果事件已设置，则返回 True，否则返回 False。

Event.set()¶

设置事件。任何等待事件的任务都将被安排运行。

注意：这必须在任务内部调用。从 IRQ、调度程序回调或其他线程调用此函数是不安全的。参见 ThreadSafeFlag。

Event.clear()¶: 清除事件。

Event.wait()¶

等待事件设置。如果事件已设置，则立即返回。

这是一个协程。

ThreadSafeFlag 类¶

class asyncio.ThreadSafeFlag¶: 创建一个新的标志，可以用来将任务与在 asyncio 循环外运行的代码同步，例如其他线程、中断请求（IRQs）或调度器回调。标志默认处于清除状态。

ThreadSafeFlag.set()¶: 设置标志。如果有等待标志的任务，则将其安排运行。

ThreadSafeFlag.clear()¶: 清除标志。这可用于确保在等待标志之前清除可能先前设置的标志。

ThreadSafeFlag.wait()¶

等待标志设置。如果标志已设置，则立即返回。标志在从 wait 返回时会自动重置。

一次只能由一个任务等待标志。

这是一个协程。

Lock 类¶

class asyncio.Lock¶

创建一个新的锁，可用于协调任务。锁从未锁定状态开始。

除了下面列出的方法之外，还可以在 async with 语句中使用锁。

Lock.locked()¶: 如果锁已锁定，则返回 True，否则返回 False。

Lock.acquire()¶

等待锁处于未锁定状态，然后以原子方式锁定它。一次只能有一个任务获取锁。

这是一个协程。

Lock.release()¶: 释放锁。如果有任务在等待锁，则排队中的下一个任务将被安排运行，并且锁仍然保持锁定状态。否则，没有任务等待锁，锁变为未锁定状态。

TCP 流连接¶

asyncio.open_connection(host, port, ssl=None)¶

打开到给定 host 和 port 的 TCP 连接。将使用 socket.getaddrinfo 解析 host 地址，这是一个当前阻塞的调用。如果 ssl 是一个 ssl.SSLContext 对象，则使用此上下文创建传输；如果 ssl 是 True，则使用默认上下文。

返回一对流：读取器流和写入器流。如果无法解析主机或无法建立连接，则会引发特定于套接字的 OSError。

这是一个协程。

asyncio.start_server(callback, host, port, backlog=5, ssl=None)¶

在给定的 host 和 port 上启动 TCP 服务器。将使用 callback 处理传入的、已接受的连接，并传递两个参数：连接的读取器和写入器流。

如果 ssl 是一个 ssl.SSLContext 对象，则使用此上下文创建传输。

返回一个 Server 对象。

这是一个协程。

class asyncio.Stream¶: 这表示 TCP 流连接。为了尽量减少代码，此类实现了读取器和写入器，而 StreamReader 和 StreamWriter 别名为此类。

Stream.get_extra_info(v)¶: 获取有关流的额外信息，由 v 给出。v 的有效值为：peername。

Stream.close()¶: 关闭流。

Stream.wait_closed()¶

等待流关闭。

这是一个协程。

Stream.read(n=-1)¶

读取最多 n 字节并返回它们。如果未提供 n 或为 -1，则读取直到 EOF 的所有字节。如果在读取任何字节之前遇到 EOF，则返回一个空字节对象。

这是一个协程。

Stream.readinto(buf)¶

将最多 n 字节读入到 buf 中，其中 n 等于 buf 的长度。

返回读入 buf 的字节数。

这是一个协程，并且是 MicroPython 的扩展。

Stream.readexactly(n)¶

读取确切的 n 字节并返回它们作为字节对象。

如果在读取 n 字节之前流结束，则引发 EOFError 异常。

这是一个协程。

Stream.readline()¶

读取一行并返回它。

这是一个协程。

Stream.write(buf)¶: 将 buf 累积到输出缓冲区中。只有在调用 Stream.drain 后才会刷新数据。建议在调用此函数后立即调用 Stream.drain。

Stream.drain()¶

将所有缓冲的输出数据刷新到流中。

这是一个协程。

class asyncio.Server¶: 这表示从 start_server 返回的服务器类。可以在 async with 语句中使用它以在退出时关闭服务器。

Server.close()¶: 关闭服务器。

Server.wait_closed()¶

等待服务器关闭。

这是一个协程。

事件循环¶

asyncio.get_event_loop()¶: 返回用于调度和运行任务的事件循环。参见 Loop。

asyncio.new_event_loop()¶

重置事件循环并返回它。

注意：由于 MicroPython 只有一个事件循环，此函数只是重置循环的状态，而不会创建新的循环。

class asyncio.Loop¶: 这表示调度和运行任务的对象。不能创建它，请改用 get_event_loop。

Loop.create_task(coro)¶: 从给定的 coro 创建一个任务，并返回新的 Task 对象。

Loop.run_forever()¶: 运行时间循环直到 stop() 被调用。

Loop.run_until_complete(awaitable)¶: 运行给定的 awaitable 直到完成。如果 awaitable 不是任务，则将其升级为任务。

Loop.stop()¶: 停止事件循环。

Loop.close()¶: 关闭事件循环。

Loop.set_exception_handler(handler)¶: 设置当任务引发未捕获的异常时调用的异常处理程序。handler 应接受两个参数： (loop, context)。

Loop.get_exception_handler()¶: 获取当前的异常处理程序。如果未设置自定义处理程序，则返回处理程序，否则返回 None。

Loop.default_exception_handler(context)¶: 调用默认的异常处理程序。

Loop.call_exception_handler(context)¶: 调用当前的异常处理程序。参数 context 通过，是一个包含键的字典：'message'、'exception'、'future'。

asyncio — 异步 I/O 调度器¶

核心函数¶

其他函数¶

Task 类¶

Event 类¶

ThreadSafeFlag 类¶

Lock 类¶

TCP 流连接¶

事件循环¶

`asyncio` — 异步 I/O 调度器¶