このドキュメンテーションは、MicroPython の最新開発ブランチのためのものです。 リリースバージョンでは利用できない機能に言及することがあります。

特定のリリースのドキュメントをお探しの場合は、左側のドロップダウンメニューを使って、 望みのバージョンを選択します。

asyncio --- 非同期 I/O スケジューラ

このモジュールは、該当する CPython モジュールのサブセットを実装しています。 詳しくはオリジナルの CPython ドキュメンテーションを参照してください: 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)

# pyboard での実行
from pyb import LED
asyncio.run(main(LED(1), LED(2)))

# 一般的なボードでの実行
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 秒間スリープします(float値も指定できます)。

これはコルーチンです。

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 を使って実行終了を待機できます。 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

他のスレッド、IRQ、スケジューラコールバックなど、asyncio ループの外部で動作しているコードのタスクを同期するために使えるフラグを新規作成します。フラグはクリアされた状態で始まります。

ThreadSafeFlag.set()

フラグを設定します。フラグを待機しているタスクがある場合、そのタスクが実行されるようスケジュールされます。

ThreadSafeFlag.clear()

フラグをクリアします。これは、以前に設定した可能性のあるフラグについて、それを待機する前に確実にクリアするために使います。

ThreadSafeFlag.wait()

フラグが設定されるのを待ちます。フラグがすでに設定されている場合はすぐに戻ります。このフラグは wait から戻ったときに自動的にリセットされます。

フラグは、一度に1つのタスクでのみ待機できます。

これはコルーチンです。

クラス Lock

class asyncio.Lock

タスクの調整に使用できる新しいロックを作成します。ロックは解除状態から始まります。

以下のメソッドに加えて、 async with ステートメントでロックを使用できます。

Lock.locked()

ロックされていれば True を返し、さもなければ False を返します。

Lock.acquire()

ロックが解除状態になるのを待ってから、アトミックな手段でロックします。一度に1つのタスクのみがロックを取得できます。

これはコルーチンです。

Lock.release()

ロックを解除します。ロックで待機しているタスクがある場合、キュー内の次のタスクが実行されるようスケジュールされ、ロックされたままになります。待機中のタスクが無い場合は、ロックが解除されます。

TCP ストリーム接続

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

指定したホスト host とポート port への TCP 接続を開きます。 host のアドレスは、現在のところブロッキング呼出しで行われる socket.getaddrinfo を使って解決されます。 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)

buf に最大 n バイトを読み込みます。n は buf の長さと同じです。

戻り値は buf に読み込んだバイト数です。

これはコルーチンであり、MicroPython 拡張機能です。

Stream.readexactly(n)

正確に n バイトを読み込んで、バイト列オブジェクトとして返します。

n バイトを読み込む前にストリームが終了すると EOFError 例外が発生します。

これはコルーチンです。

Stream.readline()

1行を読み込んで返します。

これはコルーチンです。

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 には1つのイベントループしかないので、この関数はループの状態をリセットするだけで、新しいループを作ることはありません。

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' を持つ辞書です。