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

このモジュールは、該当する :term:`CPython` モジュールのサブセットを実装しています。 詳しくはオリジナルの CPython ドキュメンテーションを参照してください: asyncio

サンプルコード:

import uasyncio

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

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

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

# 一般的なボードでの実行
from machine import Pin
uasyncio.run(main(Pin(1), Pin(2)))

コア関数

uasyncio.create_task(coro)

指定したコルーチンから新しいタスクを作成し、実行をスケジューリングします。

対応する Task オブジェクトを返します。

uasyncio.current_task()

現在実行中のタスクに関連付けられている Task オブジェクトを返します。

uasyncio.run(coro)

指定したコルーチンから新しいタスクを作成し、完了するまで実行します。

コルーチン coro の戻り値を返します。

uasyncio.sleep(t)

t 秒間スリープします(float値も指定できます)。

これはコルーチンです。

uasyncio.sleep_ms(t)

t ミリ秒間スリープします。

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

追加関数

uasyncio.wait_for(awaitable, timeout)

awaitable が完了するまで待ちますが、 timeout 秒を超えた場合はキャンセルします。 awaitable がタスクでない場合、それからタスクが作成されます。

タイムアウトが起きると、タスクはキャンセルされ、例外 asyncio.TimeoutError が発生します: この例外を呼んだ側で捕らえるようにしてください。タスクは asyncio.CancelledError を受け取りますが、これは無視するか、 try...except や try...finally を使って捉えて、クリーンアップコードを実行するようにします。

awaitable の戻り値を返します。

これはコルーチンです。

uasyncio.wait_for_ms(awaitable, timeout)

wait_for と同様ですが、 timeout にはミリ秒単位の整数で指定します。

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

uasyncio.gather(*awaitables, return_exceptions=False)

すべての awaitables を同時に実行します。タスクではないすべての awaitables はタスクに昇格します。

すべての awaitables の戻り値のリストを返します。

これはコルーチンです。

クラス Task

class uasyncio.Task

このオブジェクトは、コルーチンを実行タスクにラップします。タスクは await task を使って実行終了を待機できます。 await task はタスクの戻り値を返します。

タスクのオブジェクトは直接作成するのではなく、 create_task を使って作成してください。

Task.cancel()

タスクに asyncio.CancelledError 例外を発生させることにより、タスクをキャンセルします。タスクはこの例外を無視できます。この例外を捉えるか、 try...finally を使ってクリーンアップコードを実行するようにもできます。

クラス Event

class uasyncio.Event

タスクの同期に使う新しいイベントを作成します。イベントはクリアされた状態で開始します。

Event.is_set()

イベントが設定されていれば True を返し、さもなければ False を返します。

Event.set()

イベントを設定します。イベントを待機しているタスクはすべて実行するようにスケジュールされます。

注記: これはタスク内から呼び出す必要があります。これを IRQ、スケジューラコールバック、その他のスレッドから呼び出すことは安全ではありません。 ThreadSafeFlag を参照してください。

Event.clear()

イベントをクリアします。

Event.wait()

イベントが設定されるのを待ちます。イベントがすでに設定されている場合は、すぐに戻ります。

これはコルーチンです。

クラス ThreadSafeFlag

class uasyncio.ThreadSafeFlag

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

ThreadSafeFlag.set()

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

ThreadSafeFlag.wait()

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

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

これはコルーチンです。

クラス Lock

class uasyncio.Lock

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

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

Lock.locked()

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

Lock.acquire()

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

これはコルーチンです。

Lock.release()

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

TCP ストリーム接続

uasyncio.open_connection(host, port)

指定したホスト host とポート port への TCP 接続を開きます。 host のアドレスは socket.getaddrinfo を使って解決されます。この解決は現在のところブロッキング呼出しです。

ストリームのペア、読み取りストリームと書き込みストリームを返します。ホストを解決できなかった場合、または接続を確立できなかった場合はソケット特有の OSError 例外を発生します。

これはコルーチンです。

uasyncio.start_server(callback, host, port, backlog=5)

指定したホスト host とポート port で TCP サーバを始動します。コールバック callback は、受信、接続の受入れ、接続時の２つの引数の引き渡し(読み取りストリームと書き込みストリーム)で呼び出されます。

Server オブジェクトを返します。

これはコルーチンです。

class uasyncio.Stream

これは TCP ストリーム接続を表します。コードを最小限に抑えるために、このクラスには読み取りと書き込みの両方を実装していますStreamReader と StreamWriter は両方ともこのクラスの別名となっています。

Stream.get_extra_info(v)

v で指定したストリームに関する追加情報を取得します。 v の有効な値は peername です。

Stream.close()

ストリームをクローズします。

Stream.wait_closed()

ストリームがクローズするまで待ちます。

これはコルーチンです。

Stream.read(n)

最大 n バイトを読み取って返します。

これはコルーチンです。

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 uasyncio.Server

これは start_server から返されるサーバークラスを表します。 終了時にサーバーを閉じるには async with ステートメントが使えます。

Server.close()

サーバーをクローズします。

Server.wait_closed()

サーバーがクローズするまで待ちます。

これはコルーチンです。

イベントループ

uasyncio.get_event_loop()

タスクのスケジュールと実行に使うイベントループを返します。 Loop を参照してください。

uasyncio.new_event_loop()

イベントループをリセットして返します。

注記: MicroPython には1つのイベントループしかないので、この関数はループの状態をリセットするだけで、新しいループを作ることはありません。

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