asyncio — asynchroner I/O-Scheduler

Dieses Modul stellt einen kooperativen Multitasking-Scheduler für async/await-Coroutinen bereit, zusammen mit Primitiven zur Synchronisation (Locks, Events) und nicht blockierendem TCP-Netzwerkbetrieb über Stream-Reader und -Writer. Tasks werden nebenläufig auf einer einzigen Event-Loop ausgeführt; der aktuell laufende Task gibt die Kontrolle mit await an die Loop zurück.

Beispiel:

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 an OpenMV Cam
from machine import LED
asyncio.run(main(LED(1), LED(2)))

Kernfunktionen

asyncio.create_task(coro: Coroutine) → Task

Erstellt einen neuen Task aus der angegebenen Coroutine und plant ihn zur Ausführung ein.

Gibt das zugehörige Task-Objekt zurück.

asyncio.current_task() → Task

Gibt das Task-Objekt zurück, das mit dem aktuell laufenden Task verknüpft ist.

asyncio.run(coro: Coroutine) → Any

Erstellt einen neuen Task aus der angegebenen Coroutine und führt ihn bis zum Abschluss aus.

Gibt den von coro zurückgegebenen Wert zurück.

asyncio.sleep(t: float) → None

Schläft für t Sekunden (kann ein Float sein).

Dies ist eine Coroutine.

asyncio.sleep_ms(t: int) → None

Schläft für t Millisekunden.

Dies ist eine Coroutine und eine MicroPython-Erweiterung.

Zusätzliche Funktionen

asyncio.wait_for(awaitable: Awaitable, timeout: float) → Any

Wartet auf den Abschluss des awaitable, bricht es jedoch ab, wenn es länger als timeout Sekunden dauert. Wenn awaitable kein Task ist, wird daraus ein Task erstellt.

Tritt ein Timeout auf, wird der Task abgebrochen und asyncio.TimeoutError ausgelöst: Dies sollte vom Aufrufer abgefangen werden. Der Task erhält asyncio.CancelledError, was ignoriert oder mit try...except bzw. try...finally abgefangen werden kann, um Aufräumcode auszuführen.

Gibt den Rückgabewert von awaitable zurück.

Dies ist eine Coroutine.

asyncio.wait_for_ms(awaitable: Awaitable, timeout: int) → Any

Ähnlich wie wait_for(), aber timeout ist eine Ganzzahl in Millisekunden.

Dies ist eine Coroutine und eine MicroPython-Erweiterung.

asyncio.gather(*awaitables, return_exceptions: bool = False) → List

Führt alle awaitables nebenläufig aus. Alle awaitables, die keine Tasks sind, werden zu Tasks befördert.

Gibt eine Liste der Rückgabewerte aller awaitables zurück.

Dies ist eine Coroutine.

class Task

class asyncio.Task

Dieses Objekt kapselt eine Coroutine in einen laufenden Task. Auf Tasks kann mit await task gewartet werden, wodurch auf den Abschluss des Tasks gewartet und dessen Rückgabewert zurückgegeben wird.

Tasks sollten nicht direkt erstellt werden, verwenden Sie stattdessen create_task(), um sie zu erstellen.

cancel() → None

Bricht den Task ab, indem asyncio.CancelledError in ihn injiziert wird. Der Task kann diese Ausnahme ignorieren. Aufräumcode kann durch Abfangen oder über try ... finally ausgeführt werden.

class Event

class asyncio.Event

Erstellt ein neues Event, das zur Synchronisation von Tasks verwendet werden kann. Events beginnen im zurückgesetzten Zustand.

is_set() → bool

Gibt True zurück, wenn das Event gesetzt ist, andernfalls False.

set() → None

Setzt das Event. Alle auf das Event wartenden Tasks werden zur Ausführung eingeplant.

Hinweis: Dies muss aus einem Task heraus aufgerufen werden. Es ist nicht sicher, dies aus einem IRQ, einem Scheduler-Callback oder einem anderen Thread aufzurufen. Siehe ThreadSafeFlag.

clear() → None

Löscht das Event.

wait() → None

Wartet, bis das Event gesetzt wird. Ist das Event bereits gesetzt, kehrt es sofort zurück.

Dies ist eine Coroutine.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

Erstellt ein neues Flag, das zur Synchronisation eines Tasks mit Code verwendet werden kann, der außerhalb der asyncio-Loop läuft, etwa andere Threads, IRQs oder Scheduler-Callbacks. Flags beginnen im zurückgesetzten Zustand.

set() → None

Setzt das Flag. Wenn ein Task auf das Flag wartet, wird er zur Ausführung eingeplant.

clear() → None

Löscht das Flag. Dies kann verwendet werden, um sicherzustellen, dass ein möglicherweise zuvor gesetztes Flag gelöscht ist, bevor darauf gewartet wird.

wait() → None

Wartet, bis das Flag gesetzt wird. Ist das Flag bereits gesetzt, kehrt es sofort zurück. Das Flag wird beim Rückkehren aus wait automatisch zurückgesetzt.

Auf ein Flag kann jeweils nur ein einziger Task gleichzeitig warten.

Dies ist eine Coroutine.

class Lock

class asyncio.Lock

Erstellt ein neues Lock, das zur Koordination von Tasks verwendet werden kann. Locks beginnen im entsperrten Zustand.

Zusätzlich zu den unten aufgeführten Methoden können Locks in einer async with-Anweisung verwendet werden.

locked() → bool

Gibt True zurück, wenn das Lock gesperrt ist, andernfalls False.

acquire() → bool

Wartet, bis sich das Lock im entsperrten Zustand befindet, und sperrt es dann auf atomare Weise. Nur ein Task kann das Lock zu einem bestimmten Zeitpunkt erwerben.

Dies ist eine Coroutine.

release() → None

Gibt das Lock frei. Wenn Tasks auf das Lock warten, wird der nächste in der Warteschlange zur Ausführung eingeplant und das Lock bleibt gesperrt. Andernfalls warten keine Tasks und das Lock wird entsperrt.

TCP-Stream-Verbindungen

asyncio.open_connection(host: str, port: int, ssl: ssl.SSLContext | bool | None = None) → Tuple[Stream, Stream]

Öffnet eine TCP-Verbindung zum angegebenen host und port. Die host-Adresse wird mit socket.getaddrinfo() aufgelöst, was derzeit ein blockierender Aufruf ist. Wenn ssl ein ssl.SSLContext-Objekt ist, wird dieser Kontext zum Erstellen des Transports verwendet; wenn ssl True ist, wird ein Standardkontext verwendet.

Gibt ein Paar von Streams zurück: einen Reader- und einen Writer-Stream. Löst einen socket-spezifischen OSError aus, wenn der Host nicht aufgelöst werden konnte oder die Verbindung nicht hergestellt werden konnte.

Dies ist eine Coroutine.

asyncio.start_server(callback: Callable, host: str, port: int, backlog: int = 5, ssl: ssl.SSLContext | None = None) → Server

Startet einen TCP-Server am angegebenen host und port. Der callback wird mit eingehenden, akzeptierten Verbindungen aufgerufen und erhält 2 Argumente übergeben: Reader- und Writer-Streams für die Verbindung.

Wenn ssl ein ssl.SSLContext-Objekt ist, wird dieser Kontext zum Erstellen des Transports verwendet.

Gibt ein Server-Objekt zurück.

Dies ist eine Coroutine.

class asyncio.Stream

Dies repräsentiert eine TCP-Stream-Verbindung. Um Code zu minimieren, implementiert diese Klasse sowohl einen Reader als auch einen Writer, und sowohl StreamReader als auch StreamWriter sind Aliasnamen für diese Klasse.

get_extra_info(v: str) → Any

Ruft zusätzliche Informationen über den Stream ab, angegeben durch v. Die gültigen Werte für v sind: peername.

close() → None

Schließt den Stream.

wait_closed() → None

Wartet, bis der Stream geschlossen wird.

Dies ist eine Coroutine.

read(n: int = -1) → bytes

Liest bis zu n Bytes und gibt sie zurück. Wird n nicht angegeben oder ist -1, werden alle Bytes bis EOF gelesen. Der zurückgegebene Wert ist ein leeres Bytes-Objekt, wenn EOF erreicht wird, bevor irgendwelche Bytes gelesen wurden.

Dies ist eine Coroutine.

readinto(buf: bytearray | memoryview) → int

Liest bis zu n Bytes in buf, wobei n gleich der Länge von buf ist.

Gibt die Anzahl der in buf gelesenen Bytes zurück.

Dies ist eine Coroutine und eine MicroPython-Erweiterung.

readexactly(n: int) → bytes

Liest genau n Bytes und gibt sie als Bytes-Objekt zurück.

Löst eine EOFError-Ausnahme aus, wenn der Stream endet, bevor n Bytes gelesen wurden.

Dies ist eine Coroutine.

readline() → bytes

Liest eine Zeile und gibt sie zurück.

Dies ist eine Coroutine.

write(buf: bytes) → None

Hängt buf an den Ausgabepuffer an. Die Daten werden erst geleert, wenn Stream.drain() aufgerufen wird. Es wird empfohlen, Stream.drain() unmittelbar nach dem Aufruf dieser Funktion aufzurufen.

drain() → None

Leert (schreibt) alle gepufferten Ausgabedaten in den Stream.

Dies ist eine Coroutine.

class asyncio.Server

Dies repräsentiert die von start_server() zurückgegebene Server-Klasse. Sie kann in einer async with-Anweisung verwendet werden, um den Server beim Verlassen zu schließen.

close() → None

Schließt den Server.

wait_closed() → None

Wartet, bis der Server geschlossen wird.

Dies ist eine Coroutine.

Event-Loop

asyncio.get_event_loop() → Loop

Gibt die Event-Loop zurück, die zum Einplanen und Ausführen von Tasks verwendet wird. Siehe Loop.

asyncio.new_event_loop() → Loop

Setzt die Event-Loop zurück und gibt sie zurück.

Hinweis: Da MicroPython nur eine einzige Event-Loop hat, setzt diese Funktion lediglich den Zustand der Loop zurück, sie erstellt keine neue.

class asyncio.Loop

Dies repräsentiert das Objekt, das Tasks einplant und ausführt. Es kann nicht erstellt werden, verwenden Sie stattdessen get_event_loop().

create_task(coro: Coroutine) → Task

Erstellt einen Task aus der angegebenen coro und gibt das neue Task-Objekt zurück.

run_forever() → None

Führt die Event-Loop aus, bis stop() aufgerufen wird.

run_until_complete(awaitable: Awaitable) → Any

Führt das angegebene awaitable bis zum Abschluss aus. Wenn awaitable kein Task ist, wird es zu einem befördert.

stop() → None

Stoppt die Event-Loop.

close() → None

Schließt die Event-Loop.

set_exception_handler(handler: Callable) → None

Legt den Exception-Handler fest, der aufgerufen wird, wenn ein Task eine Ausnahme auslöst, die nicht abgefangen wird. Der handler sollte zwei Argumente akzeptieren: (loop, context).

get_exception_handler() → Callable | None

Ruft den aktuellen Exception-Handler ab. Gibt den Handler zurück oder None, wenn kein benutzerdefinierter Handler festgelegt ist.

default_exception_handler(context: dict) → None

Der aufgerufene Standard-Exception-Handler.

call_exception_handler(context: dict) → None

Ruft den aktuellen Exception-Handler auf. Das Argument context wird durchgereicht und ist ein Dictionary, das die Schlüssel 'message', 'exception' und 'future' enthält.